spa_loop_control_methods Struct Reference

Control an event loop. More...

#include <spa/support/loop.h>

Data Fields
uint32_t	version
int(*	get_fd )(void *object)
	get the loop fd
void(*	add_hook )(void *object, struct spa_hook *hook, const struct spa_loop_control_hooks *hooks, void *data)
	Add a hook.
void(*	enter )(void *object)
	Enter a loop.
void(*	leave )(void *object)
	Leave a loop.
int(*	iterate )(void *object, int timeout)
	Perform one iteration of the loop.
int(*	check )(void *object)
	Check context of the loop.
int(*	lock )(void *object)
	Lock the loop.
int(*	unlock )(void *object)
	Unlock the loop.
int(*	get_time )(void *object, struct timespec *abstime, int64_t timeout)
	get the absolute time Get the current time with timeout that can be used in wait.
int(*	wait )(void *object, const struct timespec *abstime)
	Wait for a signal Wait until a thread performs signal.
int(*	signal )(void *object, bool wait_for_accept)
	Signal waiters Wake up all threads blocked in wait.
int(*	accept )(void *object)
	Accept signalers Resume the thread that signaled with wait_for accept.

Detailed Description

Control an event loop.

The event loop control function provide API to run the event loop.

The below (pseudo)code is a minimal example outlining the use of the loop control:

spa_loop_control_enter(loop);
while (running) {
  spa_loop_control_iterate(loop, -1);
}
spa_loop_control_leave(loop);

It is also possible to add the loop to an existing event loop by using the spa_loop_control_get_fd() call. This fd will become readable when activity has been detected on the sources in the loop. spa_loop_control_iterate() with a 0 timeout should be called to process the pending sources.

spa_loop_control_enter() and spa_loop_control_leave() should be called once from the thread that will run the iterate() function.

Field Documentation

version

uint32_t spa_loop_control_methods::version

get_fd

int(* spa_loop_control_methods::get_fd) (void *object)

get the loop fd

Parameters

object

the control to query

Get the fd of this loop control. This fd will be readable when a source in the loop has activity. The user should call iterate() with a 0 timeout to schedule one iteration of the loop and dispatch the sources.

Returns

the fd of the loop

add_hook

void(* spa_loop_control_methods::add_hook) (void *object, struct spa_hook *hook, const struct spa_loop_control_hooks *hooks, void *data)

Add a hook.

Parameters

object	the control to change
hooks	the hooks to add

Adds hooks to the loop controlled by ctrl.

enter

void(* spa_loop_control_methods::enter) (void *object)

Enter a loop.

Parameters

object

the control

This function should be called before calling iterate and is typically used to capture the thread that this loop will run in. It should ideally be called once from the thread that will run the loop. This function will lock the loop.

leave

void(* spa_loop_control_methods::leave) (void *object)

Leave a loop.

Parameters

object

the control

It should ideally be called once after calling iterate when the loop will no longer be iterated from the thread that called enter().

This function will unlock the loop.

iterate

int(* spa_loop_control_methods::iterate) (void *object, int timeout)

Perform one iteration of the loop.

Parameters

ctrl	the control
timeout	an optional timeout in milliseconds. 0 for no timeout, -1 for infinite timeout.

This function will first unlock the loop and then block up to timeout milliseconds, lock the loop again and then dispatch the fds with activity.

The number of dispatched fds is returned.

check

int(* spa_loop_control_methods::check) (void *object)

Check context of the loop.

Parameters

ctrl	the control

This function will check if the current thread is currently the one that did the enter call. Since version 1:1.

returns 1 on success, 0 or negative errno value on error.

lock

int(* spa_loop_control_methods::lock) (void *object)

Lock the loop.

This will ensure the loop is not in the process of dispatching callbacks. Since version 2:2

Parameters

[in]

object

the control

Returns

0 on success or a negative return value on error.

unlock

int(* spa_loop_control_methods::unlock) (void *object)

Unlock the loop.

Unlocks the loop again so that callbacks can be dispatched again. Since version 2:2

Parameters

[in]

object

the control

Returns

0 on success or a negative return value on error.

get_time

int(* spa_loop_control_methods::get_time) (void *object, struct timespec *abstime, int64_t timeout)

get the absolute time Get the current time with timeout that can be used in wait.

Since version 2:2

This function can be called from any thread.

wait

int(* spa_loop_control_methods::wait) (void *object, const struct timespec *abstime)

Wait for a signal Wait until a thread performs signal.

Since version 2:2

This function must be called with the loop lock. Because this is a blocking call, it should not be performed from a realtime thread.

Parameters

[in]	object	the control
[in]	abstime	the maximum time to wait for the signal or NULL

Returns

0 on success or a negative return value on error.

signal

int(* spa_loop_control_methods::signal) (void *object, bool wait_for_accept)

Signal waiters Wake up all threads blocked in wait.

Since version 2:2 When wait_for_accept is set, this functions blocks until all threads performed accept.

This function must be called with the loop lock and is safe to call from a realtime thread source dispatch functions when wait_for_accept is false.

Parameters

[in]	object	the control
[in]	wait_for_accept	block for accept

Returns

0 on success or a negative return value on error.

accept

int(* spa_loop_control_methods::accept) (void *object)

Accept signalers Resume the thread that signaled with wait_for accept.

This function must be called with the loop lock and is safe to call from a realtime thread source dispatch functions.

Parameters

[in]

object

the control

Returns

0 on success or a negative return value on error.

---

The documentation for this struct was generated from the following file:

• spa/support/loop.h