PipeWire: spa/support/loop.h Source File

PipeWire 1.4.9

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
132 int (*invoke) (void *object,
133 spa_invoke_func_t func,
134 uint32_t seq,
135 const void *data,
136 size_t size,
137 bool block,
138 void *user_data);
139};
140
141 SPA_API_LOOP int spa_loop_add_source(struct spa_loop *object, struct spa_source *source)
142{
143 return spa_api_method_r(int, -ENOTSUP,
144 spa_loop, &object->iface, add_source, 0, source);
145}
146 SPA_API_LOOP int spa_loop_update_source(struct spa_loop *object, struct spa_source *source)
147{
148 return spa_api_method_r(int, -ENOTSUP,
149 spa_loop, &object->iface, update_source, 0, source);
150}
151 SPA_API_LOOP int spa_loop_remove_source(struct spa_loop *object, struct spa_source *source)
152{
153 return spa_api_method_r(int, -ENOTSUP,
154 spa_loop, &object->iface, remove_source, 0, source);
155}
156 SPA_API_LOOP int spa_loop_invoke(struct spa_loop *object,
157 spa_invoke_func_t func, uint32_t seq, const void *data,
158 size_t size, bool block, void *user_data)
159{
160 return spa_api_method_r(int, -ENOTSUP,
161 spa_loop, &object->iface, invoke, 0, func, seq, data,
162 size, block, user_data);
163}
164
167
167 * is not running or when it is locked). */
168struct spa_loop_control_hooks {
169#define SPA_VERSION_LOOP_CONTROL_HOOKS 0
170 uint32_t version;
172
172 * release locks. */
173 void (*before) (void *data);
176 void (*after) (void *data);
177};
178
179 SPA_API_LOOP void spa_loop_control_hook_before(struct spa_hook_list *l)
180{
181 struct spa_hook *h;
182 spa_list_for_each_reverse(h, &l->list, link)
183 spa_callbacks_call_fast(&h->cb, struct spa_loop_control_hooks, before, 0);
184}
185
186 SPA_API_LOOP void spa_loop_control_hook_after(struct spa_hook_list *l)
187{
188 struct spa_hook *h;
189 spa_list_for_each(h, &l->list, link)
190 spa_callbacks_call_fast(&h->cb, struct spa_loop_control_hooks, after, 0);
191}
192
195
196 * The event loop control function provide API to run the event loop.
197 *
198 * The below (pseudo)code is a minimal example outlining the use of the loop
199 * control:
200 * \code{.c}
201 * spa_loop_control_enter(loop);
202 * while (running) {
203 * spa_loop_control_iterate(loop, -1);
204 * }
205 * spa_loop_control_leave(loop);
206 * \endcode
207 *
208 * It is also possible to add the loop to an existing event loop by using the
209 * spa_loop_control_get_fd() call. This fd will become readable when activity
210 * has been detected on the sources in the loop. spa_loop_control_iterate() with
211 * a 0 timeout should be called to process the pending sources.
212 *
213 * spa_loop_control_enter() and spa_loop_control_leave() should be called once
214 * from the thread that will run the iterate() function.
215 */
216struct spa_loop_control_methods {
217 /* the version of this structure. This can be used to expand this
218 * structure in the future */
219#define SPA_VERSION_LOOP_CONTROL_METHODS 1
220 uint32_t version;
221
231 int (*get_fd) (void *object);
232
233 /** Add a hook
234 * \param object the control to change
235 * \param hooks the hooks to add
236 *
237 * Adds hooks to the loop controlled by \a ctrl.
238 */
239 void (*add_hook) (void *object,
240 struct spa_hook *hook,
241 const struct spa_loop_control_hooks *hooks,
242 void *data);
243
252 void (*enter) (void *object);
259 void (*leave) (void *object);
260
270 int (*iterate) (void *object, int timeout);
271
280 int (*check) (void *object);
281};
282
283 SPA_API_LOOP int spa_loop_control_get_fd(struct spa_loop_control *object)
284{
285 return spa_api_method_r(int, -ENOTSUP,
286 spa_loop_control, &object->iface, get_fd, 0);
287}
288 SPA_API_LOOP void spa_loop_control_add_hook(struct spa_loop_control *object,
289 struct spa_hook *hook, const struct spa_loop_control_hooks *hooks,
290 void *data)
291{
292 spa_api_method_v(spa_loop_control, &object->iface, add_hook, 0,
293 hook, hooks, data);
294}
295 SPA_API_LOOP void spa_loop_control_enter(struct spa_loop_control *object)
296{
297 spa_api_method_v(spa_loop_control, &object->iface, enter, 0);
298}
299 SPA_API_LOOP void spa_loop_control_leave(struct spa_loop_control *object)
300{
301 spa_api_method_v(spa_loop_control, &object->iface, leave, 0);
302}
303 SPA_API_LOOP int spa_loop_control_iterate(struct spa_loop_control *object,
304 int timeout)
305{
306 return spa_api_method_r(int, -ENOTSUP,
307 spa_loop_control, &object->iface, iterate, 0, timeout);
308}
309 SPA_API_LOOP int spa_loop_control_iterate_fast(struct spa_loop_control *object,
310 int timeout)
311{
312 return spa_api_method_fast_r(int, -ENOTSUP,
313 spa_loop_control, &object->iface, iterate, 0, timeout);
314}
315 SPA_API_LOOP int spa_loop_control_check(struct spa_loop_control *object)
316{
317 return spa_api_method_r(int, -ENOTSUP,
318 spa_loop_control, &object->iface, check, 1);
319}
320
321 typedef void (*spa_source_io_func_t) (void *data, int fd, uint32_t mask);
322typedef void (*spa_source_idle_func_t) (void *data);
323typedef void (*spa_source_event_func_t) (void *data, uint64_t count);
324typedef void (*spa_source_timer_func_t) (void *data, uint64_t expirations);
325typedef void (*spa_source_signal_func_t) (void *data, int signal_number);
326
327
327/**
328 * Create sources for an event loop
329 */
330struct spa_loop_utils_methods {
331 /* the version of this structure. This can be used to expand this
332 * structure in the future */
333#define SPA_VERSION_LOOP_UTILS_METHODS 0
334 uint32_t version;
335
336 struct spa_source *(*add_io) (void *object,
337 int fd,
338 uint32_t mask,
339 bool close,
340 spa_source_io_func_t func, void *data);
341
342 int (*update_io) (void *object, struct spa_source *source, uint32_t mask);
343
344 struct spa_source *(*add_idle) (void *object,
345 bool enabled,
346 spa_source_idle_func_t func, void *data);
347 int (*enable_idle) (void *object, struct spa_source *source, bool enabled);
348
349 struct spa_source *(*add_event) (void *object,
350 spa_source_event_func_t func, void *data);
351 int (*signal_event) (void *object, struct spa_source *source);
352
353 struct spa_source *(*add_timer) (void *object,
354 spa_source_timer_func_t func, void *data);
355 int (*update_timer) (void *object,
356 struct spa_source *source,
357 struct timespec *value,
358 struct timespec *interval,
359 bool absolute);
360 struct spa_source *(*add_signal) (void *object,
361 int signal_number,
362 spa_source_signal_func_t func, void *data);
363
367 void (*destroy_source) (void *object, struct spa_source *source);
368};
369
370 SPA_API_LOOP struct spa_source *
371 spa_loop_utils_add_io(struct spa_loop_utils *object, int fd, uint32_t mask,
372 bool close, spa_source_io_func_t func, void *data)
373{
374 return spa_api_method_r(struct spa_source *, NULL,
375 spa_loop_utils, &object->iface, add_io, 0, fd, mask, close, func, data);
376}
377 SPA_API_LOOP int spa_loop_utils_update_io(struct spa_loop_utils *object,
378 struct spa_source *source, uint32_t mask)
379{
380 return spa_api_method_r(int, -ENOTSUP,
381 spa_loop_utils, &object->iface, update_io, 0, source, mask);
382}
383 SPA_API_LOOP struct spa_source *
384 spa_loop_utils_add_idle(struct spa_loop_utils *object, bool enabled,
385 spa_source_idle_func_t func, void *data)
386{
387 return spa_api_method_r(struct spa_source *, NULL,
388 spa_loop_utils, &object->iface, add_idle, 0, enabled, func, data);
389}
390 SPA_API_LOOP int spa_loop_utils_enable_idle(struct spa_loop_utils *object,
391 struct spa_source *source, bool enabled)
392{
393 return spa_api_method_r(int, -ENOTSUP,
394 spa_loop_utils, &object->iface, enable_idle, 0, source, enabled);
395}
396 SPA_API_LOOP struct spa_source *
397 spa_loop_utils_add_event(struct spa_loop_utils *object, spa_source_event_func_t func, void *data)
398{
399 return spa_api_method_r(struct spa_source *, NULL,
400 spa_loop_utils, &object->iface, add_event, 0, func, data);
401}
402 SPA_API_LOOP int spa_loop_utils_signal_event(struct spa_loop_utils *object,
403 struct spa_source *source)
404{
405 return spa_api_method_r(int, -ENOTSUP,
406 spa_loop_utils, &object->iface, signal_event, 0, source);
407}
408 SPA_API_LOOP struct spa_source *
409 spa_loop_utils_add_timer(struct spa_loop_utils *object, spa_source_timer_func_t func, void *data)
410{
411 return spa_api_method_r(struct spa_source *, NULL,
412 spa_loop_utils, &object->iface, add_timer, 0, func, data);
413}
414 SPA_API_LOOP int spa_loop_utils_update_timer(struct spa_loop_utils *object,
415 struct spa_source *source, struct timespec *value,
416 struct timespec *interval, bool absolute)
417{
418 return spa_api_method_r(int, -ENOTSUP,
419 spa_loop_utils, &object->iface, update_timer, 0, source,
420 value, interval, absolute);
421}
422 SPA_API_LOOP struct spa_source *
423 spa_loop_utils_add_signal(struct spa_loop_utils *object, int signal_number,
424 spa_source_signal_func_t func, void *data)
425{
426 return spa_api_method_r(struct spa_source *, NULL,
427 spa_loop_utils, &object->iface, add_signal, 0,
428 signal_number, func, data);
429}
430 SPA_API_LOOP void spa_loop_utils_destroy_source(struct spa_loop_utils *object,
431 struct spa_source *source)
432{
433 spa_api_method_v(spa_loop_utils, &object->iface, destroy_source, 0, source);
434}
435
439
440#ifdef __cplusplus
441} /* extern "C" */
442#endif
443
444#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:172
spa_loop_control_hook_before
SPA_API_LOOP void spa_loop_control_hook_before(struct spa_hook_list *l)
Definition loop.h:196
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:403
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:442
spa_loop_add_source
SPA_API_LOOP int spa_loop_add_source(struct spa_loop *object, struct spa_source *source)
Definition loop.h:157
spa_source_timer_func_t
void(* spa_source_timer_func_t)(void *data, uint64_t expirations)
Definition loop.h:342
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:428
spa_loop_control_get_fd
SPA_API_LOOP int spa_loop_control_get_fd(struct spa_loop_control *object)
Definition loop.h:301
spa_loop_control_enter
SPA_API_LOOP void spa_loop_control_enter(struct spa_loop_control *object)
Definition loop.h:313
spa_loop_remove_source
SPA_API_LOOP int spa_loop_remove_source(struct spa_loop *object, struct spa_source *source)
Definition loop.h:167
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:433
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:409
spa_source_event_func_t
void(* spa_source_event_func_t)(void *data, uint64_t count)
Definition loop.h:341
spa_source_signal_func_t
void(* spa_source_signal_func_t)(void *data, int signal_number)
Definition loop.h:343
spa_loop_control_iterate_fast
SPA_API_LOOP int spa_loop_control_iterate_fast(struct spa_loop_control *object, int timeout)
Definition loop.h:327
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:306
spa_source_idle_func_t
void(* spa_source_idle_func_t)(void *data)
Definition loop.h:340
spa_loop_control_iterate
SPA_API_LOOP int spa_loop_control_iterate(struct spa_loop_control *object, int timeout)
Definition loop.h:321
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:449
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:333
spa_loop_control_hook_after
SPA_API_LOOP void spa_loop_control_hook_after(struct spa_hook_list *l)
Definition loop.h:203
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:416
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:339
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:421
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:396
spa_loop_control_leave
SPA_API_LOOP void spa_loop_control_leave(struct spa_loop_control *object)
Definition loop.h:317
spa_loop_update_source
SPA_API_LOOP int spa_loop_update_source(struct spa_loop *object, struct spa_source *source)
Definition loop.h:162
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:390
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:184
spa_loop_control_hooks::before
void(* before)(void *data)
Executed right before waiting for events.
Definition loop.h:190
spa_loop_control_hooks::version
uint32_t version
Definition loop.h:187
spa_loop_control_hooks::after
void(* after)(void *data)
Executed right after waiting for events.
Definition loop.h:193
spa_loop_control_methods
Control an event loop.
Definition loop.h:233
spa_loop_control_methods::iterate
int(* iterate)(void *object, int timeout)
Perform one iteration of the loop.
Definition loop.h:288
spa_loop_control_methods::enter
void(* enter)(void *object)
Enter a loop.
Definition loop.h:270
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:257
spa_loop_control_methods::check
int(* check)(void *object)
Check context of the loop.
Definition loop.h:298
spa_loop_control_methods::leave
void(* leave)(void *object)
Leave a loop.
Definition loop.h:277
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:148
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:348
spa_loop_utils_methods::enable_idle
int(* enable_idle)(void *object, struct spa_source *source, bool enabled)
Definition loop.h:366
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:363
spa_loop_utils_methods::signal_event
int(* signal_event)(void *object, struct spa_source *source)
Definition loop.h:370
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:374
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:386
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:355
spa_loop_utils_methods::version
uint32_t version
Definition loop.h:353
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