< Previous | Contents | Manuals Home | Boris FX | Next >

Cancellable Tasks ‌

You can move long-running tasks to a background thread, so that they can be cancelled, and so that SynthEyes is not entirely locked up while the task runs. You can see this in the AprilTags Detector, for example.

This requires some planning and refactoring of the code (see Apriltags):

 Put the background task into a specific function that will run in the background.

 Move all changes to the SynthEyes scene, ie that are subject to Undo processing, from the background task function into one or more functions that will run in the foreground.

 Move all user interface operations, such as dialogs created with NewDialog(), Message(), or YesNoCancel(), into functions that will run in the foreground.

 Inside the background task, regularly test (see below) if the task has been cancelled and should terminate; do so if requested.

 Start the cancellable background function with Scene.CancellableCall(“background_function_name”, arguments…). The cancellable-task dialog will pop up and be shown while the task is running. This call will not return until the background function completes; the return value of this call will be the result returned by the background function.

The result of this scheme by design is a task running in a separate thread, with the SynthEyes user interface still running, but tightly controlled so that the user cannot do anything conflicting. Sizzle scripts always run within, and produce a single Undo object. It is a cancellable task, not an independent background task. This approach is necessary to avoid conflict between the script accesses to the scene and accesses required to change or redraw the main user interface, and because macOS and Linux require all window-related operations to happen from the main thread. For a true independent task, Python must be (carefully) used.

You should partition the foreground and background functions such that the foreground functions don’t require too long to run, and that there aren’t too many foreground/background transitions, as that does create overhead.

Inside the foreground and background functions, you refer to an object named Cancellable with the following attributes and functions:

.elapsed Time in seconds since the cancellable task was started, can be used to throttle unnecessarily frequent user interface updates.

.ForegroundCall(function_name, args) Call function_name from the main user-

interface thread, where user-interface tasks or scene updates can be performed. The background task waits for the foreground function to complete; the result of this call is the result returned by function_name.

.message A read/write arbitrary text message that can be used to show information about what’s

happening and how much time is left, for example.

.percent A 0-100 percentage value controlling the progress bar.

.pleaseCancel Zero initially, set to one if the user clicks the Cancel or Close buttons. Note that setting this flag is the only inherent effect of clicking the cancel button; everything else is determined by your Sizzle script.

.title Read/write to set the (narrow!) title of the cancellable task dialog. Typically the description of the task, same or similar to the name of the script that started this task.

< Previous | Contents | Manuals Home | Boris FX | Next >