bluesky_queueserver_api.zmq.REManagerAPI.function_execute

REManagerAPI.function_execute(item, *, run_in_background=None, user=None, user_group=None, lock_key=None)

Start execution of a function in RE Worker namespace. The function must be defined in the namespace (in startup code or a script uploaded using script_upload method). The function may be executed as a foreground task (only if RE Manager and RE Worker environment are IDLE) or as a background task. Background tasks are executed in separate threads and may consume processing or memory resources and interfere with running plans or other tasks. RE Manager does not guarantee thread safety of the user code running in the background. Developers of startup scripts are fully responsible for preventing threading issues.

The method allows to pass parameters (args and kwargs) to the function. Once the task is completed, the results of the function execution, including the return value, can be loaded using task_result method. If the task fails, the return value is a string with full traceback of the raised exception. The data types of parameters and return values must be JSON serializable. The task fails if the return value can not be serialized.

The method only initiates execution of the function. If the request is successful ("success": True), the server starts the task, which attempts to execute the function with given name and parameters. The function may still fail to start (e.g. if the user is permitted to execute function with the given name, but the function is not defined in the namespace). Use task_result API with the returned task_uid to check the status of the tasks and load the result after the task is completed.

Parameters:
item: BItem, BFunc or dict

BItem, BFunc or dictionary with function name, args and kwargs. The structure of dictionary is the same as for items representing plans and instructions, except that item_type is "function".

run_in_background: boolean (optional, default False)

Set this parameter True to upload and execute the script in the background (while a plan or another foreground task is running). Generally, it is not recommended to update RE Worker namespace in the background. Background tasks are executed in separate threads and only thread-safe scripts should be uploaded in the background. Developers of data acquisition workflows and/or user specific code are responsible for thread safety.

user, user_group: str or None (optional)

User name and user group name used in the API request. The parameter values override the default user and user group names (accessible using user and user_group properties). The default user or user group name is used if the respective parameter is not specified or None. The parameters are ignored by the HTTP version of the API.

lock_key: str or None (optional)

The lock key enables access to the API when RE Manager environment is locked. If the parameter is not None, the key overrides the current lock key set by REManagerAPI.lock_key. See documentation on REMangerAPI.lock() for more information. Default: None.

Returns:
response: dict

Dictionary keys:

  • success: boolean - success of the request.

  • msg: str - error message in case the request is rejected by RE Manager or operation failed.

  • item - dictionary of function parameters (may be None if operation fails).

  • task_uid - UID of the started task.

Raises:
RequestTimeoutError, RequestFailedError, HTTPRequestError, HTTPClientError, HTTPServerError

All exceptions raised by send_request API.

Examples

function = BFunc("function_sleep", 10)

# Synchronous code (0MQ, HTTP)
RM.function_execute(function)

# Asynchronous code (0MQ, HTTP)
await RM.function_execute(function)