PipeWire: spa/support/loop.h Source File

PipeWire 1.4.2 |

Loading...
Searching...
No Matches
loop.h
Go to the documentation of this file.
1/* Simple Plugin API */
2/* SPDX-FileCopyrightText: Copyright © 2018 Wim Taymans */
3/* SPDX-License-Identifier: MIT */
4
5#ifndef SPA_LOOP_H
6#define SPA_LOOP_H
7
8#ifdef __cplusplus
9extern "C" {
10#endif
11
12#include <errno.h>
13
14#include <spa/utils/defs.h>
15#include <spa/utils/hook.h>
16#include <spa/support/system.h>
17
18#ifndef SPA_API_LOOP
19 #ifdef SPA_API_IMPL
20 #define SPA_API_LOOP SPA_API_IMPL
21 #else
22 #define SPA_API_LOOP static inline
23 #endif
24#endif
25
29
34
35#define SPA_TYPE_INTERFACE_Loop SPA_TYPE_INFO_INTERFACE_BASE "Loop"
36#define SPA_TYPE_INTERFACE_DataLoop SPA_TYPE_INFO_INTERFACE_BASE "DataLoop"
37#define SPA_VERSION_LOOP 0
38struct spa_loop { struct spa_interface iface; };
39
40#define SPA_TYPE_INTERFACE_LoopControl SPA_TYPE_INFO_INTERFACE_BASE "LoopControl"
41#define SPA_VERSION_LOOP_CONTROL 1
42struct spa_loop_control { struct spa_interface iface; };
43
44#define SPA_TYPE_INTERFACE_LoopUtils SPA_TYPE_INFO_INTERFACE_BASE "LoopUtils"
45#define SPA_VERSION_LOOP_UTILS 0
46struct spa_loop_utils { struct spa_interface iface; };
47
48 struct spa_source;
49
50typedef void (*spa_source_func_t) (struct spa_source *source);
51
52struct spa_source {
53 struct spa_loop *loop;
54 spa_source_func_t func;
55 void *data;
56 int fd;
57 uint32_t mask;
58 uint32_t rmask;
59 /* private data for the loop implementer */
60 void *priv;
61};
62
63typedef int (*spa_invoke_func_t) (struct spa_loop *loop,
64 bool async,
65 uint32_t seq,
66 const void *data,
67 size_t size,
68 void *user_data);
69
73 struct spa_loop_methods {
74 /* the version of this structure. This can be used to expand this
75 * structure in the future */
76#define SPA_VERSION_LOOP_METHODS 0
77 uint32_t version;
78
85 int (*add_source) (void *object,
86 struct spa_source *source);
87
88 /** Update the source io mask. Must be called from the loop's own thread.
89 *
90 * \param[in] object The callbacks data.
91 * \param[in] source The source.
92 * \return 0 on success, negative errno-style value on failure.
93 */
94 int (*update_source) (void *object,
95 struct spa_source *source);
96
103 int (*remove_source) (void *object,
104 struct spa_source *source);
105
129 int (*invoke) (void *object,
130 spa_invoke_func_t func,
131 uint32_t seq,
132 const void *data,
133 size_t size,
134 bool block,
135 void *user_data);
136};
137
138 SPA_API_LOOP int spa_loop_add_source(struct spa_loop *object, struct spa_source *source)
139{
140 return spa_api_method_r(int, -ENOTSUP,
141 spa_loop, &object->iface, add_source, 0, source);
142}
143 SPA_API_LOOP int spa_loop_update_source(struct spa_loop *object, struct spa_source *source)
144{
145 return spa_api_method_r(int, -ENOTSUP,
146 spa_loop, &object->iface, update_source, 0, source);
147}
148 SPA_API_LOOP int spa_loop_remove_source(struct spa_loop *object, struct spa_source *source)
149{
150 return spa_api_method_r(int, -ENOTSUP,
151 spa_loop, &object->iface, remove_source, 0, source);
152}
153 SPA_API_LOOP int spa_loop_invoke(struct spa_loop *object,
154 spa_invoke_func_t func, uint32_t seq, const void *data,
155 size_t size, bool block, void *user_data)
156{
157 return spa_api_method_r(int, -ENOTSUP,
158 spa_loop, &object->iface, invoke, 0, func, seq, data,
159 size, block, user_data);
160}
161
164
164 * is not running or when it is locked). */
165struct spa_loop_control_hooks {
166#define SPA_VERSION_LOOP_CONTROL_HOOKS 0
167 uint32_t version;
169
169 * release locks. */
170 void (*before) (void *data);
173 void (*after) (void *data);
174};
175
176 SPA_API_LOOP void spa_loop_control_hook_before(struct spa_hook_list *l)
177{
178 struct spa_hook *h;
179 spa_list_for_each_reverse(h, &l->list, link)
180 spa_callbacks_call_fast(&h->cb, struct spa_loop_control_hooks, before, 0);
181}
182
183 SPA_API_LOOP void spa_loop_control_hook_after(struct spa_hook_list *l)
184{
185 struct spa_hook *h;
186 spa_list_for_each(h, &l->list, link)
187 spa_callbacks_call_fast(&h->cb, struct spa_loop_control_hooks, after, 0);
188}
189
192
193 * The event loop control function provide API to run the event loop.
194 *
195 * The below (pseudo)code is a minimal example outlining the use of the loop
196 * control:
197 * \code{.c}
198 * spa_loop_control_enter(loop);
199 * while (running) {
200 * spa_loop_control_iterate(loop, -1);
201 * }
202 * spa_loop_control_leave(loop);
203 * \endcode
204 *
205 * It is also possible to add the loop to an existing event loop by using the
206 * spa_loop_control_get_fd() call. This fd will become readable when activity
207 * has been detected on the sources in the loop. spa_loop_control_iterate() with
208 * a 0 timeout should be called to process the pending sources.
209 *
210 * spa_loop_control_enter() and spa_loop_control_leave() should be called once
211 * from the thread that will run the iterate() function.
212 */
213struct spa_loop_control_methods {
214 /* the version of this structure. This can be used to expand this
215 * structure in the future */
216#define SPA_VERSION_LOOP_CONTROL_METHODS 1
217 uint32_t version;
218
228 int (*get_fd) (void *object);
229
230 /** Add a hook
231 * \param object the control to change
232 * \param hooks the hooks to add
233 *
234 * Adds hooks to the loop controlled by \a ctrl.
235 */
236 void (*add_hook) (void *object,
237 struct spa_hook *hook,
238 const struct spa_loop_control_hooks *hooks,
239 void *data);
240
249 void (*enter) (void *object);
256 void (*leave) (void *object);
257
267 int (*iterate) (void *object, int timeout);
268
277 int (*check) (void *object);
278};
279
280 SPA_API_LOOP int spa_loop_control_get_fd(struct spa_loop_control *object)
281{
282 return spa_api_method_r(int, -ENOTSUP,
283 spa_loop_control, &object->iface, get_fd, 0);
284}
285 SPA_API_LOOP void spa_loop_control_add_hook(struct spa_loop_control *object,
286 struct spa_hook *hook, const struct spa_loop_control_hooks *hooks,
287 void *data)
288{
289 spa_api_method_v(spa_loop_control, &object->iface, add_hook, 0,
290 hook, hooks, data);
291}
292 SPA_API_LOOP void spa_loop_control_enter(struct spa_loop_control *object)
293{
294 spa_api_method_v(spa_loop_control, &object->iface, enter, 0);
295}
296 SPA_API_LOOP void spa_loop_control_leave(struct spa_loop_control *object)
297{
298 spa_api_method_v(spa_loop_control, &object->iface, leave, 0);
299}
300 SPA_API_LOOP int spa_loop_control_iterate(struct spa_loop_control *object,
301 int timeout)
302{
303 return spa_api_method_r(int, -ENOTSUP,
304 spa_loop_control, &object->iface, iterate, 0, timeout);
305}
306 SPA_API_LOOP int spa_loop_control_iterate_fast(struct spa_loop_control *object,
307 int timeout)
308{
309 return spa_api_method_fast_r(int, -ENOTSUP,
310 spa_loop_control, &object->iface, iterate, 0, timeout);
311}
312 SPA_API_LOOP int spa_loop_control_check(struct spa_loop_control *object)
313{
314 return spa_api_method_r(int, -ENOTSUP,
315 spa_loop_control, &object->iface, check, 1);
316}
317
318 typedef void (*spa_source_io_func_t) (void *data, int fd, uint32_t mask);
319typedef void (*spa_source_idle_func_t) (void *data);
320typedef void (*spa_source_event_func_t) (void *data, uint64_t count);
321typedef void (*spa_source_timer_func_t) (void *data, uint64_t expirations);
322typedef void (*spa_source_signal_func_t) (void *data, int signal_number);
323
324
324/**
325 * Create sources for an event loop
326 */
327struct spa_loop_utils_methods {
328 /* the version of this structure. This can be used to expand this
329 * structure in the future */
330#define SPA_VERSION_LOOP_UTILS_METHODS 0
331 uint32_t version;
332
333 struct spa_source *(*add_io) (void *object,
334 int fd,
335 uint32_t mask,
336 bool close,
337 spa_source_io_func_t func, void *data);
338
339 int (*update_io) (void *object, struct spa_source *source, uint32_t mask);
340
341 struct spa_source *(*add_idle) (void *object,
342 bool enabled,
343 spa_source_idle_func_t func, void *data);
344 int (*enable_idle) (void *object, struct spa_source *source, bool enabled);
345
346 struct spa_source *(*add_event) (void *object,
347 spa_source_event_func_t func, void *data);
348 int (*signal_event) (void *object, struct spa_source *source);
349
350 struct spa_source *(*add_timer) (void *object,
351 spa_source_timer_func_t func, void *data);
352 int (*update_timer) (void *object,
353 struct spa_source *source,
354 struct timespec *value,
355 struct timespec *interval,
356 bool absolute);
357 struct spa_source *(*add_signal) (void *object,
358 int signal_number,
359 spa_source_signal_func_t func, void *data);
360
364 void (*destroy_source) (void *object, struct spa_source *source);
365};
366
367 SPA_API_LOOP struct spa_source *
368 spa_loop_utils_add_io(struct spa_loop_utils *object, int fd, uint32_t mask,
369 bool close, spa_source_io_func_t func, void *data)
370{
371 return spa_api_method_r(struct spa_source *, NULL,
372 spa_loop_utils, &object->iface, add_io, 0, fd, mask, close, func, data);
373}
374 SPA_API_LOOP int spa_loop_utils_update_io(struct spa_loop_utils *object,
375 struct spa_source *source, uint32_t mask)
376{
377 return spa_api_method_r(int, -ENOTSUP,
378 spa_loop_utils, &object->iface, update_io, 0, source, mask);
379}
380 SPA_API_LOOP struct spa_source *
381 spa_loop_utils_add_idle(struct spa_loop_utils *object, bool enabled,
382 spa_source_idle_func_t func, void *data)
383{
384 return spa_api_method_r(struct spa_source *, NULL,
385 spa_loop_utils, &object->iface, add_idle, 0, enabled, func, data);
386}
387 SPA_API_LOOP int spa_loop_utils_enable_idle(struct spa_loop_utils *object,
388 struct spa_source *source, bool enabled)
389{
390 return spa_api_method_r(int, -ENOTSUP,
391 spa_loop_utils, &object->iface, enable_idle, 0, source, enabled);
392}
393 SPA_API_LOOP struct spa_source *
394 spa_loop_utils_add_event(struct spa_loop_utils *object, spa_source_event_func_t func, void *data)
395{
396 return spa_api_method_r(struct spa_source *, NULL,
397 spa_loop_utils, &object->iface, add_event, 0, func, data);
398}
399 SPA_API_LOOP int spa_loop_utils_signal_event(struct spa_loop_utils *object,
400 struct spa_source *source)
401{
402 return spa_api_method_r(int, -ENOTSUP,
403 spa_loop_utils, &object->iface, signal_event, 0, source);
404}
405 SPA_API_LOOP struct spa_source *
406 spa_loop_utils_add_timer(struct spa_loop_utils *object, spa_source_timer_func_t func, void *data)
407{
408 return spa_api_method_r(struct spa_source *, NULL,
409 spa_loop_utils, &object->iface, add_timer, 0, func, data);
410}
411 SPA_API_LOOP int spa_loop_utils_update_timer(struct spa_loop_utils *object,
412 struct spa_source *source, struct timespec *value,
413 struct timespec *interval, bool absolute)
414{
415 return spa_api_method_r(int, -ENOTSUP,
416 spa_loop_utils, &object->iface, update_timer, 0, source,
417 value, interval, absolute);
418}
419 SPA_API_LOOP struct spa_source *
420 spa_loop_utils_add_signal(struct spa_loop_utils *object, int signal_number,
421 spa_source_signal_func_t func, void *data)
422{
423 return spa_api_method_r(struct spa_source *, NULL,
424 spa_loop_utils, &object->iface, add_signal, 0,
425 signal_number, func, data);
426}
427 SPA_API_LOOP void spa_loop_utils_destroy_source(struct spa_loop_utils *object,
428 struct spa_source *source)
429{
430 spa_api_method_v(spa_loop_utils, &object->iface, destroy_source, 0, source);
431}
432
436
437#ifdef __cplusplus
438} /* extern "C" */
439#endif
440
441#endif /* SPA_LOOP_H */
defs.h
spa/utils/defs.h
seq
uint32_t int seq
Definition core.h:432
spa_api_method_r
#define spa_api_method_r(rtype, def, type, o, method, version,...)
Definition hook.h:291
spa_api_method_fast_r
#define spa_api_method_fast_r(rtype, def, type, o, method, version,...)
Definition hook.h:325
spa_callbacks_call_fast
#define spa_callbacks_call_fast(callbacks, type, method, vers,...)
Definition hook.h:184
spa_api_method_v
#define spa_api_method_v(type, o, method, version,...)
Definition hook.h:285
spa_list_for_each_reverse
#define spa_list_for_each_reverse(pos, head, member)
Definition list.h:122
spa_list_for_each
#define spa_list_for_each(pos, head, member)
Definition list.h:119
spa_loop_invoke
SPA_API_LOOP int spa_loop_invoke(struct spa_loop *object, spa_invoke_func_t func, uint32_t seq, const void *data, size_t size, bool block, void *user_data)
Definition loop.h:169
spa_loop_control_hook_before
SPA_API_LOOP void spa_loop_control_hook_before(struct spa_hook_list *l)
Definition loop.h:193
spa_loop_utils_add_idle
SPA_API_LOOP struct spa_source * spa_loop_utils_add_idle(struct spa_loop_utils *object, bool enabled, spa_source_idle_func_t func, void *data)
Definition loop.h:400
spa_loop_utils_add_signal
SPA_API_LOOP struct spa_source * spa_loop_utils_add_signal(struct spa_loop_utils *object, int signal_number, spa_source_signal_func_t func, void *data)
Definition loop.h:439
spa_loop_add_source
SPA_API_LOOP int spa_loop_add_source(struct spa_loop *object, struct spa_source *source)
Definition loop.h:154
spa_source_timer_func_t
void(* spa_source_timer_func_t)(void *data, uint64_t expirations)
Definition loop.h:339
spa_loop_utils_add_timer
SPA_API_LOOP struct spa_source * spa_loop_utils_add_timer(struct spa_loop_utils *object, spa_source_timer_func_t func, void *data)
Definition loop.h:425
spa_loop_control_get_fd
SPA_API_LOOP int spa_loop_control_get_fd(struct spa_loop_control *object)
Definition loop.h:298
spa_loop_control_enter
SPA_API_LOOP void spa_loop_control_enter(struct spa_loop_control *object)
Definition loop.h:310
spa_loop_remove_source
SPA_API_LOOP int spa_loop_remove_source(struct spa_loop *object, struct spa_source *source)
Definition loop.h:164
spa_loop_utils_update_timer
SPA_API_LOOP int spa_loop_utils_update_timer(struct spa_loop_utils *object, struct spa_source *source, struct timespec *value, struct timespec *interval, bool absolute)
Definition loop.h:430
spa_loop_utils_enable_idle
SPA_API_LOOP int spa_loop_utils_enable_idle(struct spa_loop_utils *object, struct spa_source *source, bool enabled)
Definition loop.h:406
spa_source_event_func_t
void(* spa_source_event_func_t)(void *data, uint64_t count)
Definition loop.h:338
spa_source_signal_func_t
void(* spa_source_signal_func_t)(void *data, int signal_number)
Definition loop.h:340
spa_loop_control_iterate_fast
SPA_API_LOOP int spa_loop_control_iterate_fast(struct spa_loop_control *object, int timeout)
Definition loop.h:324
spa_loop_control_add_hook
SPA_API_LOOP void spa_loop_control_add_hook(struct spa_loop_control *object, struct spa_hook *hook, const struct spa_loop_control_hooks *hooks, void *data)
Definition loop.h:303
spa_source_idle_func_t
void(* spa_source_idle_func_t)(void *data)
Definition loop.h:337
spa_loop_control_iterate
SPA_API_LOOP int spa_loop_control_iterate(struct spa_loop_control *object, int timeout)
Definition loop.h:318
spa_loop_utils_destroy_source
SPA_API_LOOP void spa_loop_utils_destroy_source(struct spa_loop_utils *object, struct spa_source *source)
Definition loop.h:446
spa_source_func_t
void(* spa_source_func_t)(struct spa_source *source)
Definition loop.h:65
spa_loop_control_check
SPA_API_LOOP int spa_loop_control_check(struct spa_loop_control *object)
Definition loop.h:330
spa_loop_control_hook_after
SPA_API_LOOP void spa_loop_control_hook_after(struct spa_hook_list *l)
Definition loop.h:200
spa_loop_utils_add_event
SPA_API_LOOP struct spa_source * spa_loop_utils_add_event(struct spa_loop_utils *object, spa_source_event_func_t func, void *data)
Definition loop.h:413
spa_invoke_func_t
int(* spa_invoke_func_t)(struct spa_loop *loop, bool async, uint32_t seq, const void *data, size_t size, void *user_data)
Definition loop.h:78
spa_source_io_func_t
void(* spa_source_io_func_t)(void *data, int fd, uint32_t mask)
Definition loop.h:336
spa_loop_utils_signal_event
SPA_API_LOOP int spa_loop_utils_signal_event(struct spa_loop_utils *object, struct spa_source *source)
Definition loop.h:418
spa_loop_utils_update_io
SPA_API_LOOP int spa_loop_utils_update_io(struct spa_loop_utils *object, struct spa_source *source, uint32_t mask)
Definition loop.h:393
spa_loop_control_leave
SPA_API_LOOP void spa_loop_control_leave(struct spa_loop_control *object)
Definition loop.h:314
spa_loop_update_source
SPA_API_LOOP int spa_loop_update_source(struct spa_loop *object, struct spa_source *source)
Definition loop.h:159
spa_loop_utils_add_io
SPA_API_LOOP struct spa_source * spa_loop_utils_add_io(struct spa_loop_utils *object, int fd, uint32_t mask, bool close, spa_source_io_func_t func, void *data)
Definition loop.h:387
hook.h
spa/utils/hook.h
SPA_API_LOOP
#define SPA_API_LOOP
Definition loop.h:29
spa_hook_list
A list of hooks.
Definition hook.h:416
spa_hook_list::list
struct spa_list list
Definition hook.h:417
spa_hook
A hook, contains the structure with functions and the data passed to the functions.
Definition hook.h:427
spa_hook::cb
struct spa_callbacks cb
Definition hook.h:429
spa_hook::link
struct spa_list link
Definition hook.h:428
spa_interface
Definition hook.h:148
spa_loop_control_hooks
Control hooks.
Definition loop.h:181
spa_loop_control_hooks::before
void(* before)(void *data)
Executed right before waiting for events.
Definition loop.h:187
spa_loop_control_hooks::version
uint32_t version
Definition loop.h:184
spa_loop_control_hooks::after
void(* after)(void *data)
Executed right after waiting for events.
Definition loop.h:190
spa_loop_control_methods
Control an event loop.
Definition loop.h:230
spa_loop_control_methods::iterate
int(* iterate)(void *object, int timeout)
Perform one iteration of the loop.
Definition loop.h:285
spa_loop_control_methods::enter
void(* enter)(void *object)
Enter a loop.
Definition loop.h:267
spa_loop_control_methods::add_hook
void(* add_hook)(void *object, struct spa_hook *hook, const struct spa_loop_control_hooks *hooks, void *data)
Add a hook.
Definition loop.h:254
spa_loop_control_methods::check
int(* check)(void *object)
Check context of the loop.
Definition loop.h:295
spa_loop_control_methods::leave
void(* leave)(void *object)
Leave a loop.
Definition loop.h:274
spa_loop_control
Definition loop.h:54
spa_loop_control::iface
struct spa_interface iface
Definition loop.h:54
spa_loop_methods
Register sources and work items to an event loop.
Definition loop.h:88
spa_loop_methods::add_source
int(* add_source)(void *object, struct spa_source *source)
Add a source to the loop.
Definition loop.h:101
spa_loop_methods::remove_source
int(* remove_source)(void *object, struct spa_source *source)
Remove a source from the loop.
Definition loop.h:119
spa_loop_methods::invoke
int(* invoke)(void *object, spa_invoke_func_t func, uint32_t seq, const void *data, size_t size, bool block, void *user_data)
Invoke a function in the context of this loop.
Definition loop.h:145
spa_loop_methods::update_source
int(* update_source)(void *object, struct spa_source *source)
Update the source io mask.
Definition loop.h:110
spa_loop_methods::version
uint32_t version
Definition loop.h:93
spa_loop_utils_methods
Create sources for an event loop.
Definition loop.h:345
spa_loop_utils_methods::enable_idle
int(* enable_idle)(void *object, struct spa_source *source, bool enabled)
Definition loop.h:363
spa_loop_utils_methods::add_idle
struct spa_source *(* add_idle)(void *object, bool enabled, spa_source_idle_func_t func, void *data)
Definition loop.h:360
spa_loop_utils_methods::signal_event
int(* signal_event)(void *object, struct spa_source *source)
Definition loop.h:367
spa_loop_utils_methods::update_timer
int(* update_timer)(void *object, struct spa_source *source, struct timespec *value, struct timespec *interval, bool absolute)
Definition loop.h:371
spa_loop_utils_methods::destroy_source
void(* destroy_source)(void *object, struct spa_source *source)
destroy a source allocated with this interface.
Definition loop.h:383
spa_loop_utils_methods::add_io
struct spa_source *(* add_io)(void *object, int fd, uint32_t mask, bool close, spa_source_io_func_t func, void *data)
Definition loop.h:352
spa_loop_utils_methods::version
uint32_t version
Definition loop.h:350
spa_loop_utils
Definition loop.h:60
spa_loop_utils::iface
struct spa_interface iface
Definition loop.h:60
spa_loop
Definition loop.h:48
spa_loop::iface
struct spa_interface iface
Definition loop.h:48
spa_source
Definition loop.h:67
spa_source::rmask
uint32_t rmask
Definition loop.h:73
spa_source::priv
void * priv
Definition loop.h:75
spa_source::mask
uint32_t mask
Definition loop.h:72
spa_source::func
spa_source_func_t func
Definition loop.h:69
spa_source::fd
int fd
Definition loop.h:71
spa_source::loop
struct spa_loop * loop
Definition loop.h:68
system.h
spa/support/system.h