Mercurial > hg > pub > prymula > com

comparison DPF-Prymula-audioplugins/dpf/distrho/src/lv2/worker.h @ 3:84e66ea83026

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
DPF-Prymula-audioplugins-0.231015-2
author prymula <prymula76@outlook.com>
date Mon, 16 Oct 2023 21:53:34 +0200
parents
children
comparison
equal deleted inserted replaced
2:cf2cb71d31dd 3:84e66ea83026
1 /*
2 Copyright 2012-2016 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 @defgroup worker Worker
19
20 Support for non-realtime plugin operations, see
21 <http://lv2plug.in/ns/ext/worker> for details.
22
23 @{
24 */
25
26 #ifndef LV2_WORKER_H
27 #define LV2_WORKER_H
28
29 #include <stdint.h>
30
31 #include "lv2.h"
32
33 #define LV2_WORKER_URI "http://lv2plug.in/ns/ext/worker" ///< http://lv2plug.in/ns/ext/worker
34 #define LV2_WORKER_PREFIX LV2_WORKER_URI "#" ///< http://lv2plug.in/ns/ext/worker#
35
36 #define LV2_WORKER__interface LV2_WORKER_PREFIX "interface" ///< http://lv2plug.in/ns/ext/worker#interface
37 #define LV2_WORKER__schedule LV2_WORKER_PREFIX "schedule" ///< http://lv2plug.in/ns/ext/worker#schedule
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /**
44 Status code for worker functions.
45 */
46 typedef enum {
47 LV2_WORKER_SUCCESS = 0, /**< Completed successfully. */
48 LV2_WORKER_ERR_UNKNOWN = 1, /**< Unknown error. */
49 LV2_WORKER_ERR_NO_SPACE = 2 /**< Failed due to lack of space. */
50 } LV2_Worker_Status;
51
52 /** Opaque handle for LV2_Worker_Interface::work(). */
53 typedef void* LV2_Worker_Respond_Handle;
54
55 /**
56 A function to respond to run() from the worker method.
57
58 The `data` MUST be safe for the host to copy and later pass to
59 work_response(), and the host MUST guarantee that it will be eventually
60 passed to work_response() if this function returns LV2_WORKER_SUCCESS.
61 */
62 typedef LV2_Worker_Status (*LV2_Worker_Respond_Function)(
63 LV2_Worker_Respond_Handle handle,
64 uint32_t size,
65 const void* data);
66
67 /**
68 Plugin Worker Interface.
69
70 This is the interface provided by the plugin to implement a worker method.
71 The plugin's extension_data() method should return an LV2_Worker_Interface
72 when called with LV2_WORKER__interface as its argument.
73 */
74 typedef struct _LV2_Worker_Interface {
75 /**
76 The worker method. This is called by the host in a non-realtime context
77 as requested, possibly with an arbitrary message to handle.
78
79 A response can be sent to run() using `respond`. The plugin MUST NOT
80 make any assumptions about which thread calls this method, except that
81 there are no real-time requirements and only one call may be executed at
82 a time. That is, the host MAY call this method from any non-real-time
83 thread, but MUST NOT make concurrent calls to this method from several
84 threads.
85
86 @param instance The LV2 instance this is a method on.
87 @param respond A function for sending a response to run().
88 @param handle Must be passed to `respond` if it is called.
89 @param size The size of `data`.
90 @param data Data from run(), or NULL.
91 */
92 LV2_Worker_Status (*work)(LV2_Handle instance,
93 LV2_Worker_Respond_Function respond,
94 LV2_Worker_Respond_Handle handle,
95 uint32_t size,
96 const void* data);
97
98 /**
99 Handle a response from the worker. This is called by the host in the
100 run() context when a response from the worker is ready.
101
102 @param instance The LV2 instance this is a method on.
103 @param size The size of `body`.
104 @param body Message body, or NULL.
105 */
106 LV2_Worker_Status (*work_response)(LV2_Handle instance,
107 uint32_t size,
108 const void* body);
109
110 /**
111 Called when all responses for this cycle have been delivered.
112
113 Since work_response() may be called after run() finished, this provides
114 a hook for code that must run after the cycle is completed.
115
116 This field may be NULL if the plugin has no use for it. Otherwise, the
117 host MUST call it after every run(), regardless of whether or not any
118 responses were sent that cycle.
119 */
120 LV2_Worker_Status (*end_run)(LV2_Handle instance);
121 } LV2_Worker_Interface;
122
123 /** Opaque handle for LV2_Worker_Schedule. */
124 typedef void* LV2_Worker_Schedule_Handle;
125
126 /**
127 Schedule Worker Host Feature.
128
129 The host passes this feature to provide a schedule_work() function, which
130 the plugin can use to schedule a worker call from run().
131 */
132 typedef struct _LV2_Worker_Schedule {
133 /**
134 Opaque host data.
135 */
136 LV2_Worker_Schedule_Handle handle;
137
138 /**
139 Request from run() that the host call the worker.
140
141 This function is in the audio threading class. It should be called from
142 run() to request that the host call the work() method in a non-realtime
143 context with the given arguments.
144
145 This function is always safe to call from run(), but it is not
146 guaranteed that the worker is actually called from a different thread.
147 In particular, when free-wheeling (e.g. for offline rendering), the
148 worker may be executed immediately. This allows single-threaded
149 processing with sample accuracy and avoids timing problems when run() is
150 executing much faster or slower than real-time.
151
152 Plugins SHOULD be written in such a way that if the worker runs
153 immediately, and responses from the worker are delivered immediately,
154 the effect of the work takes place immediately with sample accuracy.
155
156 The `data` MUST be safe for the host to copy and later pass to work(),
157 and the host MUST guarantee that it will be eventually passed to work()
158 if this function returns LV2_WORKER_SUCCESS.
159
160 @param handle The handle field of this struct.
161 @param size The size of `data`.
162 @param data Message to pass to work(), or NULL.
163 */
164 LV2_Worker_Status (*schedule_work)(LV2_Worker_Schedule_Handle handle,
165 uint32_t size,
166 const void* data);
167 } LV2_Worker_Schedule;
168
169 #ifdef __cplusplus
170 } /* extern "C" */
171 #endif
172
173 #endif /* LV2_WORKER_H */
174
175 /**
176 @}
177 */