Namespace LrTasks

This namespace allows you to start and manage tasks that run cooperatively on Lightroom's main (user interface) thread. These are expressed in Lua as coroutines, and are similar to lightweight threads.

Summary

LrTasks.canYield()
Reports whether a cooperative task is currently running; that is, a task that was started with LrTasks.startAsyncTasks() or similar.
LrTasks.execute( cmd )
Similar to Lua's built-in os.execute() function, but blocks only the task that calls it, instead of blocking the entire application.
LrTasks.pcall( func, ... )
Simulates Lua's standard pcall(), but in a way that allows a call to LrTasks.yield() to occur inside it.
LrTasks.sleep( delay )
Temporarily stops this task and allows other tasks on Lightroom's main user interface thread to proceed.
LrTasks.startAsyncTask( func, optName )
Start a function that will run as a cooperative task on Lightroom's main thread.
LrTasks.startAsyncTaskWithoutErrorHandler( func, optName )
Starts a function that will run as a cooperative task on Lightroom's main thread.
LrTasks.yield()
Temporarily stops this task and allows other tasks on Lightroom's main user interface thread to proceed.

Functions

LrTasks.canYield()
Reports whether a cooperative task is currently running; that is, a task that was started with LrTasks.startAsyncTasks() or similar. If so, you can call LrTasks.yield().

First supported in version 1.3 of the Lightroom SDK.

Return value

(Boolean) True if LrTasks.yield() can be called.
LrTasks.execute( cmd )
Similar to Lua's built-in os.execute() function, but blocks only the task that calls it, instead of blocking the entire application.

First supported in version 1.3 of the Lightroom SDK.

Note that if Lightroom is running in an application sandbox environment, which will be the case for version 5.0 and higher when purchased from the Mac App Store, other sandboxed applications' binaries cannot be invoked directly by this API, as that results in violation of sandbox restrictions. A child process inherits the sandbox restrictions from its parent, so the OS doesn't allow for creation of a new sandbox for the new process. There are also other OS provided utilities that cannot be used by a sandboxed application, i.e 'ps'. Consult Apple's documentation for further details.

Parameters

1. cmd
(string) A command to pass to the command line of the OS shell.

Return value

(number) The exit status of the OS shell.
LrTasks.pcall( func, ... )
Simulates Lua's standard pcall(), but in a way that allows a call to LrTasks.yield() to occur inside it.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. func
(function) The function to call
2. ...
Parameters that are passed through to the function.

Return value

(Boolean + ...) Success (true) or failure (false) + the return value from the function (same as Lua's pcall()).
LrTasks.sleep( delay )
Temporarily stops this task and allows other tasks on Lightroom's main user interface thread to proceed. This task will resume no earlier than the given number of seconds later than it is called.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. delay
(number) The number of seconds to delay. Fractional values are allowed.
LrTasks.startAsyncTask( func, optName )
Start a function that will run as a cooperative task on Lightroom's main thread. If an error is thrown while this task is executing, shows a standard error dialog.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. func
(function) The function to start.
2. optName
(string, optional) A name to assign to the task, for debugging only.

See also

LrFunctionContext.postAsyncTaskWithContext
LrTasks.startAsyncTaskWithoutErrorHandler( func, optName )
Starts a function that will run as a cooperative task on Lightroom's main thread. This version does not automatically show an error dialog on failure.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. func
(function) The function to start.
2. optName
(string, optional) A name to assign to the task, for debugging only.
LrTasks.yield()
Temporarily stops this task and allows other tasks on Lightroom's main user interface thread to proceed. This task will resume at an unspecified time in the relatively near future (usually well under a second).

First supported in version 1.3 of the Lightroom SDK.