LV2: Worker

# LV2

An open and extensible audio plugin standard

Version | 1.18.10

Data Structures | Macros | Typedefs | Enumerations
Worker
LV2

## Detailed Description

Support for non-realtime plugin operations.

See http://lv2plug.in/ns/ext/worker for details.

## Data Structures
struct | LV2_Worker_Interface
struct | LV2_Worker_Schedule

## Macros
#define | LV2_WORKER_URI "http://lv2plug.in/ns/ext/worker"
#define | LV2_WORKER_PREFIX LV2_WORKER_URI "#"
#define | LV2_WORKER__interface LV2_WORKER_PREFIX "interface"
#define | LV2_WORKER__schedule LV2_WORKER_PREFIX "schedule"

## Typedefs
typedef void * | LV2_Worker_Respond_Handle
typedef LV2_Worker_Status(* | LV2_Worker_Respond_Function) (LV2_Worker_Respond_Handle handle, uint32_t size, const void *data)
typedef void * | LV2_Worker_Schedule_Handle

## Enumerations
enum | LV2_Worker_Status { LV2_WORKER_SUCCESS = 0 , LV2_WORKER_ERR_UNKNOWN = 1 , LV2_WORKER_ERR_NO_SPACE = 2 }

## Data Structure Documentation

## ◆ LV2_Worker_Interface

struct LV2_Worker_Interface

Plugin Worker Interface.

This is the interface provided by the plugin to implement a worker method. The plugin's extension_data() method should return an LV2_Worker_Interface when called with LV2_WORKER__interface as its argument.

### Data Fields
LV2_Worker_Status(* | work )(LV2_Handle instance, LV2_Worker_Respond_Function respond, LV2_Worker_Respond_Handle handle, uint32_t size, const void *data)
LV2_Worker_Status(* | work_response )(LV2_Handle instance, uint32_t size, const void *body)
LV2_Worker_Status(* | end_run )(LV2_Handle instance)

#### Field Documentation

## ◆ work

LV2_Worker_Status(* LV2_Worker_Interface::work) (LV2_Handle instance, LV2_Worker_Respond_Function respond, LV2_Worker_Respond_Handle handle, uint32_t size, const void *data)

The worker method.

This is called by the host in a non-realtime context as requested, possibly with an arbitrary message to handle.

A response can be sent to run() using respond. The plugin MUST NOT make any assumptions about which thread calls this method, except that there are no real-time requirements and only one call may be executed at a time. That is, the host MAY call this method from any non-real-time thread, but MUST NOT make concurrent calls to this method from several threads.

Parameters

  instance | The LV2 instance this is a method on.
  respond | A function for sending a response to run().
  handle | Must be passed to respond if it is called.
  size | The size of data.
  data | Data from run(), or NULL.

## ◆ work_response

LV2_Worker_Status(* LV2_Worker_Interface::work_response) (LV2_Handle instance, uint32_t size, const void *body)

Handle a response from the worker.

This is called by the host in the run() context when a response from the worker is ready.

Parameters

  instance | The LV2 instance this is a method on.
  size | The size of body.
  body | Message body, or NULL.

## ◆ end_run

LV2_Worker_Status(* LV2_Worker_Interface::end_run) (LV2_Handle instance)

Called when all responses for this cycle have been delivered.

Since work_response() may be called after run() finished, this provides a hook for code that must run after the cycle is completed.

This field may be NULL if the plugin has no use for it. Otherwise, the host MUST call it after every run(), regardless of whether or not any responses were sent that cycle.

## ◆ LV2_Worker_Schedule

struct LV2_Worker_Schedule

Schedule Worker Host Feature.

The host passes this feature to provide a schedule_work() function, which the plugin can use to schedule a worker call from run().

### Data Fields
LV2_Worker_Schedule_Handle | handle
LV2_Worker_Status(* | schedule_work )(LV2_Worker_Schedule_Handle handle, uint32_t size, const void *data)

#### Field Documentation

## ◆ handle

LV2_Worker_Schedule_Handle LV2_Worker_Schedule::handle

Opaque host data.

## ◆ schedule_work

LV2_Worker_Status(* LV2_Worker_Schedule::schedule_work) (LV2_Worker_Schedule_Handle handle, uint32_t size, const void *data)

Request from run() that the host call the worker.

This function is in the audio threading class. It should be called from run() to request that the host call the work() method in a non-realtime context with the given arguments.

This function is always safe to call from run(), but it is not guaranteed that the worker is actually called from a different thread. In particular, when free-wheeling (for example, during offline rendering), the worker may be executed immediately. This allows single-threaded processing with sample accuracy and avoids timing problems when run() is executing much faster or slower than real-time.

Plugins SHOULD be written in such a way that if the worker runs immediately, and responses from the worker are delivered immediately, the effect of the work takes place immediately with sample accuracy.

The data MUST be safe for the host to copy and later pass to work(), and the host MUST guarantee that it will be eventually passed to work() if this function returns LV2_WORKER_SUCCESS.

Parameters

  handle | The handle field of this struct.
  size | The size of data.
  data | Message to pass to work(), or NULL.

## Macro Definition Documentation

## ◆ LV2_WORKER_URI

#define LV2_WORKER_URI "http://lv2plug.in/ns/ext/worker"

http://lv2plug.in/ns/ext/worker

## ◆ LV2_WORKER_PREFIX

#define LV2_WORKER_PREFIX LV2_WORKER_URI "#"

http://lv2plug.in/ns/ext/worker#

## ◆ LV2_WORKER__interface

#define LV2_WORKER__interface LV2_WORKER_PREFIX "interface"

http://lv2plug.in/ns/ext/worker#interface

## ◆ LV2_WORKER__schedule

#define LV2_WORKER__schedule LV2_WORKER_PREFIX "schedule"

http://lv2plug.in/ns/ext/worker#schedule

## Typedef Documentation

## ◆ LV2_Worker_Respond_Handle

typedef void* LV2_Worker_Respond_Handle

Opaque handle for LV2_Worker_Interface::work().

## ◆ LV2_Worker_Respond_Function

typedef LV2_Worker_Status(* LV2_Worker_Respond_Function) (LV2_Worker_Respond_Handle handle, uint32_t size, const void *data)

A function to respond to run() from the worker method.

The data MUST be safe for the host to copy and later pass to work_response(), and the host MUST guarantee that it will be eventually passed to work_response() if this function returns LV2_WORKER_SUCCESS.

## ◆ LV2_Worker_Schedule_Handle

typedef void* LV2_Worker_Schedule_Handle

Opaque handle for LV2_Worker_Schedule.

## Enumeration Type Documentation

## ◆ LV2_Worker_Status

enum LV2_Worker_Status

Status code for worker functions.

Enumerator
LV2_WORKER_SUCCESS | Completed successfully.
LV2_WORKER_ERR_UNKNOWN | Unknown error.
LV2_WORKER_ERR_NO_SPACE | Failed due to lack of space.