How long should a plugin call take?

This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core

When the RIP calls the plugin the calling thread cannot do anything until the call returns. Yet the RIP always has many tasks to attend to, and often cannot afford to wait for the plugin to finish certain kinds of selector call.

If a plugin call blocks, or takes a long time (of the order of a second or more) to return, the RIP goes without processing time, with the following consequences:

1. No image data is passed to the output device. (Output plugins.)

This can lead to data underrun, with the output device consuming all available data and pausing, with a potentially negative impact on quality.

1. Some time‐critical tasks may not be accomplished.

Tasks such as tickles of other plugins and status updates in the GUI cannot be completed. When the plugin returns control, the RIP begins a ‘catch up' phase, attempting to clear its backlog of tasks, which in turn can delay the production of more image data. In extreme cases, network connections might be lost due to protocol timeouts.

Warning: Plugin calls should be over in less than a second (ideally, less than 0.1 seconds). They must never block. The RIP must be able to attend to its other duties with as little delay as possible.

In addition to the length of time a routine in your plugin takes to return to complete, you should con‐ sider the cumulative effect of calling routines repetitively.

To ensure that plugin calls are over in a very short time, plugins can be written in the form of state machines that avoid the possibility of blocking by regularly returning control to the RIP, but retaining state information so that operations can be completed over several calls.

With the exception of those selectors, which are only ever called once, whenever the RIP calls the plugin, it does so with the same selector and arguments until it receives confirmation that the call is complete. In between such calls the RIP attends to other necessary tasks and other plugins. The RIP usually confirms that call is complete by checking the state of the data structures it is passing to the plugin. This means that the plugin can regularly return control to the RIP without the worry that the RIP will move on to the next call prematurely, provided it maintains an internal ʹstate machineʹ.