1 /* 2 Copyright 2012 David Robillard <http://drobilla.net> 3 4 Permission to use, copy, modify, and/or distribute this software for any 5 purpose with or without fee is hereby granted, provided that the above 6 copyright notice and this permission notice appear in all copies. 7 8 THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /** 18 @file worker.h C header for the LV2 Worker extension 19 <http://lv2plug.in/ns/ext/worker>. 20 */ 21 22 #ifndef LV2_WORKER_H 23 #define LV2_WORKER_H 24 25 #include <stdint.h> 26 27 #include "lv2.h" 28 29 #define LV2_WORKER_URI "http://lv2plug.in/ns/ext/worker" 30 #define LV2_WORKER_PREFIX LV2_WORKER_URI "#" 31 32 #define LV2_WORKER__interface LV2_WORKER_PREFIX "interface" 33 #define LV2_WORKER__schedule LV2_WORKER_PREFIX "schedule" 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 /** 40 A status code for worker functions. 41 */ 42 typedef enum { 43 LV2_WORKER_SUCCESS = 0, /**< Completed successfully. */ 44 LV2_WORKER_ERR_UNKNOWN = 1, /**< Unknown error. */ 45 LV2_WORKER_ERR_NO_SPACE = 2 /**< Failed due to lack of space. */ 46 } LV2_Worker_Status; 47 48 typedef void* LV2_Worker_Respond_Handle; 49 50 /** 51 A function to respond to run() from the worker method. 52 53 The @p data MUST be safe for the host to copy and later pass to 54 work_response(), and the host MUST guarantee that it will be eventually 55 passed to work_response() if this function returns LV2_WORKER_SUCCESS. 56 */ 57 typedef LV2_Worker_Status (*LV2_Worker_Respond_Function)( 58 LV2_Worker_Respond_Handle handle, 59 uint32_t size, 60 const void* data); 61 62 /** 63 LV2 Plugin Worker Interface. 64 65 This is the interface provided by the plugin to implement a worker method. 66 The plugin's extension_data() method should return an LV2_Worker_Interface 67 when called with LV2_WORKER__interface as its argument. 68 */ 69 typedef struct _LV2_Worker_Interface { 70 /** 71 The worker method. This is called by the host in a non-realtime context 72 as requested, possibly with an arbitrary message to handle. 73 74 A response can be sent to run() using @p respond. The plugin MUST NOT 75 make any assumptions about which thread calls this method, other than 76 the fact that there are no real-time requirements. 77 78 @param instance The LV2 instance this is a method on. 79 @param respond A function for sending a response to run(). 80 @param handle Must be passed to @p respond if it is called. 81 @param size The size of @p data. 82 @param data Data from run(), or NULL. 83 */ 84 LV2_Worker_Status (*work)(LV2_Handle instance, 85 LV2_Worker_Respond_Function respond, 86 LV2_Worker_Respond_Handle handle, 87 uint32_t size, 88 const void* data); 89 90 /** 91 Handle a response from the worker. This is called by the host in the 92 run() context when a response from the worker is ready. 93 94 @param instance The LV2 instance this is a method on. 95 @param size The size of @p body. 96 @param body Message body, or NULL. 97 */ 98 LV2_Worker_Status (*work_response)(LV2_Handle instance, 99 uint32_t size, 100 const void* body); 101 102 /** 103 Called when all responses for this cycle have been delivered. 104 105 Since work_response() may be called after run() finished, this provides 106 a hook for code that must run after the cycle is completed. 107 108 This field may be NULL if the plugin has no use for it. Otherwise, the 109 host MUST call it after every run(), regardless of whether or not any 110 responses were sent that cycle. 111 */ 112 LV2_Worker_Status (*end_run)(LV2_Handle instance); 113 } LV2_Worker_Interface; 114 115 typedef void* LV2_Worker_Schedule_Handle; 116 117 typedef struct _LV2_Worker_Schedule { 118 /** 119 Opaque host data. 120 */ 121 LV2_Worker_Schedule_Handle handle; 122 123 /** 124 Request from run() that the host call the worker. 125 126 This function is in the audio threading class. It should be called from 127 run() to request that the host call the work() method in a non-realtime 128 context with the given arguments. 129 130 This function is always safe to call from run(), but it is not 131 guaranteed that the worker is actually called from a different thread. 132 In particular, when free-wheeling (e.g. for offline rendering), the 133 worker may be executed immediately. This allows single-threaded 134 processing with sample accuracy and avoids timing problems when run() is 135 executing much faster or slower than real-time. 136 137 Plugins SHOULD be written in such a way that if the worker runs 138 immediately, and responses from the worker are delivered immediately, 139 the effect of the work takes place immediately with sample accuracy. 140 141 The @p data MUST be safe for the host to copy and later pass to work(), 142 and the host MUST guarantee that it will be eventually passed to work() 143 if this function returns LV2_WORKER_SUCCESS. 144 145 @param handle The handle field of this struct. 146 @param size The size of @p data. 147 @param data Message to pass to work(), or NULL. 148 */ 149 LV2_Worker_Status (*schedule_work)(LV2_Worker_Schedule_Handle handle, 150 uint32_t size, 151 const void* data); 152 } LV2_Worker_Schedule; 153 154 #ifdef __cplusplus 155 } /* extern "C" */ 156 #endif 157 158 #endif /* LV2_WORKER_H */ 159