PipeWire: spa_loop_control_methods Struct Reference

PipeWire 1.6.8

Loading...
Searching...
No Matches
spa_loop_control_methods Struct Reference
SPA » Support » Loop

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);
spa_loop_control_enter
SPA_API_LOOP void spa_loop_control_enter(struct spa_loop_control *object)
Definition loop.h:409
spa_loop_control_iterate
SPA_API_LOOP int spa_loop_control_iterate(struct spa_loop_control *object, int timeout)
Definition loop.h:417
spa_loop_control_leave
SPA_API_LOOP void spa_loop_control_leave(struct spa_loop_control *object)
Definition loop.h:413

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