Thread Loop
Implementation API

The threaded loop object runs a Loop in a separate thread and ensures proper locking is done. More...

## Files

file | thread-loop.h
| `pipewire/thread-loop.h`

## Data Structures

struct | pw_thread_loop_events
| Thread loop events. More...
struct | pw_thread_loop

## Macros

#define | PW_VERSION_THREAD_LOOP_EVENTS 0

## Functions

struct pw_thread_loop * | pw_thread_loop_new (const char *name, const struct spa_dict *props)
| Make a new thread loop with the given name and optional properties. More...
struct pw_thread_loop * | pw_thread_loop_new_full (struct pw_loop *loop, const char *name, const struct spa_dict *props)
| Make a new thread loop with the given loop, name and optional properties. More...
void | pw_thread_loop_destroy (struct pw_thread_loop *loop)
| Destroy a thread loop. More...
void | pw_thread_loop_add_listener (struct pw_thread_loop *loop, struct spa_hook *listener, const struct pw_thread_loop_events *events, void *data)
| Add an event listener. More...
struct pw_loop * | pw_thread_loop_get_loop (struct pw_thread_loop *loop)
| Get the loop implementation of the thread loop. More...
int | pw_thread_loop_start (struct pw_thread_loop *loop)
| Start the thread loop. More...
void | pw_thread_loop_stop (struct pw_thread_loop *loop)
| Stop the thread loop. More...
void | pw_thread_loop_lock (struct pw_thread_loop *loop)
| Lock the loop. More...
void | pw_thread_loop_unlock (struct pw_thread_loop *loop)
| Unlock the loop. More...
void | pw_thread_loop_wait (struct pw_thread_loop *loop)
| Release the lock and wait until some thread calls pw_thread_loop_signal. More...
int | pw_thread_loop_timed_wait (struct pw_thread_loop *loop, int wait_max_sec)
| Release the lock and wait a maximum of 'wait_max_sec' seconds until some thread calls pw_thread_loop_signal or time out. More...
int | pw_thread_loop_get_time (struct pw_thread_loop *loop, struct timespec *abstime, int64_t timeout)
| Get a struct timespec suitable for pw_thread_loop_timed_wait_full. More...
int | pw_thread_loop_timed_wait_full (struct pw_thread_loop *loop, struct timespec *abstime)
| Release the lock and wait up to abstime until some thread calls pw_thread_loop_signal. More...
void | pw_thread_loop_signal (struct pw_thread_loop *loop, bool wait_for_accept)
| Signal all threads waiting with pw_thread_loop_wait. More...
void | pw_thread_loop_accept (struct pw_thread_loop *loop)
| Signal all threads executing pw_thread_loop_signal with wait_for_accept. More...
bool | pw_thread_loop_in_thread (struct pw_thread_loop *loop)
| Check if inside the thread. More...

## Detailed Description

The threaded loop object runs a Loop in a separate thread and ensures proper locking is done.

All of the loop callbacks will be executed with the loop lock held.

See also Thread Loop

## Macro Definition Documentation

## PW_VERSION_THREAD_LOOP_EVENTS

#define PW_VERSION_THREAD_LOOP_EVENTS 0

## Function Documentation

## pw_thread_loop_new()

struct pw_thread_loop* pw_thread_loop_new | ( | const char * | name,
|  | const struct spa_dict * | props
| ) |  |

Make a new thread loop with the given name and optional properties.

Make a new thread loop with the given name and optional properties.

Parameters

  name | the name of the thread or NULL
  props | a dict of properties for the thread loop

Returns
  a newly allocated Thread Loop

Make a new Thread Loop that will run in a thread with name.

After this function you should probably call pw_thread_loop_start() to actually start the thread

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_new_full()

struct pw_thread_loop* pw_thread_loop_new_full | ( | struct pw_loop * | loop,
|  | const char * | name,
|  | const struct spa_dict * | props
| ) |  |

Make a new thread loop with the given loop, name and optional properties.

When loop is NULL, a new loop will be created.

Make a new thread loop with the given loop, name and optional properties.

Parameters

  loop | the loop to wrap
  name | the name of the thread or NULL
  props | a dict of properties for the thread loop

Returns
  a newly allocated Thread Loop

Make a new Thread Loop that will run loop in a thread with name.

After this function you should probably call pw_thread_loop_start() to actually start the thread

## pw_thread_loop_destroy()

void pw_thread_loop_destroy | ( | struct pw_thread_loop * | loop | ) |

Destroy a thread loop.

Destroy a thread loop.

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_add_listener()

void pw_thread_loop_add_listener | ( | struct pw_thread_loop * | loop,
|  | struct spa_hook * | listener,
|  | const struct pw_thread_loop_events * | events,
|  | void * | data
| ) |  |

Add an event listener.

## pw_thread_loop_get_loop()

struct pw_loop* pw_thread_loop_get_loop | ( | struct pw_thread_loop * | loop | ) |

Get the loop implementation of the thread loop.

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_start()

int pw_thread_loop_start | ( | struct pw_thread_loop * | loop | ) |

Start the thread loop.

Start the thread loop.

Parameters

  loop | a Thread Loop

Returns
  0 on success

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_stop()

void pw_thread_loop_stop | ( | struct pw_thread_loop * | loop | ) |

Stop the thread loop.

Stop the thread loop.

Parameters

  loop | a Thread Loop

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_lock()

void pw_thread_loop_lock | ( | struct pw_thread_loop * | loop | ) |

Lock the loop.

This ensures exclusive ownership of the loop

Lock the loop.

Parameters

  loop | a Thread Loop

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_unlock()

void pw_thread_loop_unlock | ( | struct pw_thread_loop * | loop | ) |

Unlock the loop.

Unlock the loop.

Parameters

  loop | a Thread Loop

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_wait()

void pw_thread_loop_wait | ( | struct pw_thread_loop * | loop | ) |

Release the lock and wait until some thread calls pw_thread_loop_signal.

Release the lock and wait until some thread calls pw_thread_loop_signal.

Parameters

  loop | a Thread Loop to signal

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_timed_wait()

int pw_thread_loop_timed_wait | ( | struct pw_thread_loop * | loop,
|  | int | wait_max_sec
| ) |  |

Release the lock and wait a maximum of 'wait_max_sec' seconds until some thread calls pw_thread_loop_signal or time out.

Release the lock and wait a maximum of 'wait_max_sec' seconds until some thread calls pw_thread_loop_signal or time out.

Parameters

  loop | a Thread Loop to signal
  wait_max_sec | the maximum number of seconds to wait for a pw_thread_loop_signal()

Returns
  0 on success or ETIMEDOUT on timeout or a negative errno value.

## pw_thread_loop_get_time()

int pw_thread_loop_get_time | ( | struct pw_thread_loop * | loop,
|  | struct timespec * | abstime,
|  | int64_t | timeout
| ) |  |

Get a struct timespec suitable for pw_thread_loop_timed_wait_full.

Since: 0.3.7

Get a struct timespec suitable for pw_thread_loop_timed_wait_full.

This can be used in pw_thread_loop_timed_wait_full().

Parameters

  loop | a Thread Loop
  abstime | the result struct timesspec
  timeout | the time in nanoseconds to add to tp

Returns
  0 on success or a negative errno value on error.

## pw_thread_loop_timed_wait_full()

int pw_thread_loop_timed_wait_full | ( | struct pw_thread_loop * | loop,
|  | struct timespec * | abstime
| ) |  |

Release the lock and wait up to abstime until some thread calls pw_thread_loop_signal.

Use pw_thread_loop_get_time to make a timeout. Since: 0.3.7

Release the lock and wait up to abstime until some thread calls pw_thread_loop_signal.

Parameters

  loop | a Thread Loop to signal
  abstime | the absolute time to wait for a pw_thread_loop_signal()

Returns
  0 on success or -ETIMEDOUT on timeout or a negative error value

## pw_thread_loop_signal()

void pw_thread_loop_signal | ( | struct pw_thread_loop * | loop,
|  | bool | wait_for_accept
| ) |  |

Signal all threads waiting with pw_thread_loop_wait.

Signal all threads waiting with pw_thread_loop_wait.

Parameters

  loop | a Thread Loop to signal
  wait_for_accept | if we need to wait for accept

Signal the thread of loop. If wait_for_accept is true, this function waits until pw_thread_loop_accept() is called.

Examples
  video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## pw_thread_loop_accept()

void pw_thread_loop_accept | ( | struct pw_thread_loop * | loop | ) |

Signal all threads executing pw_thread_loop_signal with wait_for_accept.

Signal all threads executing pw_thread_loop_signal with wait_for_accept.

Parameters

  loop | a Thread Loop to signal

## pw_thread_loop_in_thread()

bool pw_thread_loop_in_thread | ( | struct pw_thread_loop * | loop | ) |

Check if inside the thread.

Check if inside the thread.

Parameters

  loop | a Thread Loop to signal

Returns
  true when called inside the thread of loop.