A thread based event loop implementation based on pa_mainloop. More...

Typedefs
typedef struct pa_threaded_mainloop	pa_threaded_mainloop
	An opaque threaded main loop object. More...

Functions
pa_threaded_mainloop *	pa_threaded_mainloop_new (void)
	Allocate a new threaded main loop object. More...

void	pa_threaded_mainloop_free (pa_threaded_mainloop *m)
	Free a threaded main loop object. More...

int	pa_threaded_mainloop_start (pa_threaded_mainloop *m)
	Start the event loop thread. More...

void	pa_threaded_mainloop_stop (pa_threaded_mainloop *m)
	Terminate the event loop thread cleanly. More...

void	pa_threaded_mainloop_lock (pa_threaded_mainloop *m)
	Lock the event loop object, effectively blocking the event loop thread from processing events. More...

void	pa_threaded_mainloop_unlock (pa_threaded_mainloop *m)
	Unlock the event loop object, inverse of pa_threaded_mainloop_lock(). More...

void	pa_threaded_mainloop_wait (pa_threaded_mainloop *m)
	Wait for an event to be signalled by the event loop thread. More...

void	pa_threaded_mainloop_signal (pa_threaded_mainloop *m, int wait_for_accept)
	Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait(). More...

void	pa_threaded_mainloop_accept (pa_threaded_mainloop *m)
	Accept a signal from the event thread issued with pa_threaded_mainloop_signal(). More...

int	pa_threaded_mainloop_get_retval (const pa_threaded_mainloop *m)
	Return the return value as specified with the main loop's pa_mainloop_quit() routine. More...

pa_mainloop_api *	pa_threaded_mainloop_get_api (pa_threaded_mainloop *m)
	Return the main loop abstraction layer vtable for this main loop. More...

int	pa_threaded_mainloop_in_thread (pa_threaded_mainloop *m)
	Returns non-zero when called from within the event loop thread. More...

void	pa_threaded_mainloop_set_name (pa_threaded_mainloop m, const char name)
	Sets the name of the thread. More...

void	pa_threaded_mainloop_once_unlocked (pa_threaded_mainloop m, void(callback)(pa_threaded_mainloop m, void userdata), void *userdata)
	Runs the given callback in the mainloop thread without the lock held. More...

Detailed Description

A thread based event loop implementation based on pa_mainloop.

The event loop is run in a helper thread in the background. A few synchronization primitives are available to access the objects attached to the event loop safely.

Typedef Documentation

◆ pa_threaded_mainloop

typedef struct pa_threaded_mainloop pa_threaded_mainloop

An opaque threaded main loop object.

Function Documentation

◆ pa_threaded_mainloop_accept()

void pa_threaded_mainloop_accept ( pa_threaded_mainloop * m )

Accept a signal from the event thread issued with pa_threaded_mainloop_signal().

This call should only be used in conjunction with pa_threaded_mainloop_signal() with a non-zero wait_for_accept value.

◆ pa_threaded_mainloop_free()

void pa_threaded_mainloop_free ( pa_threaded_mainloop * m )

Free a threaded main loop object.

If the event loop thread is still running, terminate it with pa_threaded_mainloop_stop() first.

◆ pa_threaded_mainloop_get_api()

pa_mainloop_api* pa_threaded_mainloop_get_api ( pa_threaded_mainloop * m )

Return the main loop abstraction layer vtable for this main loop.

There is no need to free this object as it is owned by the loop and is destroyed when the loop is freed.

◆ pa_threaded_mainloop_get_retval()

int pa_threaded_mainloop_get_retval ( const pa_threaded_mainloop * m )

Return the return value as specified with the main loop's pa_mainloop_quit() routine.

◆ pa_threaded_mainloop_in_thread()

int pa_threaded_mainloop_in_thread ( pa_threaded_mainloop * m )

Returns non-zero when called from within the event loop thread.

Since: 0.9.7

◆ pa_threaded_mainloop_lock()

void pa_threaded_mainloop_lock ( pa_threaded_mainloop * m )

Lock the event loop object, effectively blocking the event loop thread from processing events.

You can use this to enforce exclusive access to all objects attached to the event loop. This lock is recursive. This function may not be called inside the event loop thread. Events that are dispatched from the event loop thread are executed with this lock held.

◆ pa_threaded_mainloop_new()

pa_threaded_mainloop* pa_threaded_mainloop_new ( void )

Allocate a new threaded main loop object.

You have to call pa_threaded_mainloop_start() before the event loop thread starts running. Free with pa_threaded_mainloop_free.

◆ pa_threaded_mainloop_once_unlocked()

void pa_threaded_mainloop_once_unlocked	(	pa_threaded_mainloop *	m,
		void()(pa_threaded_mainloop m, void *userdata)	callback,
		void *	userdata
	)

Runs the given callback in the mainloop thread without the lock held.

The caller is responsible for ensuring that PulseAudio data structures are only accessed in a thread-safe way (that is, APIs that take pa_context and pa_stream are not thread-safe, and should not accessed without some synchronisation). This is the only situation in which pa_threaded_mainloop_lock() and pa_threaded_mainloop_unlock() may be used in the mainloop thread context.

Since: 13.0

◆ pa_threaded_mainloop_set_name()

void pa_threaded_mainloop_set_name	(	pa_threaded_mainloop *	m,
		const char *	name
	)

Sets the name of the thread.

Since: 5.0

◆ pa_threaded_mainloop_signal()

void pa_threaded_mainloop_signal	(	pa_threaded_mainloop *	m,
		int	wait_for_accept
	)

Signal all threads waiting for a signalling event in pa_threaded_mainloop_wait().

If wait_for_accept is non-zero, do not return before the signal was accepted by a pa_threaded_mainloop_accept() call. While waiting for that condition the event loop object is unlocked.

◆ pa_threaded_mainloop_start()

int pa_threaded_mainloop_start ( pa_threaded_mainloop * m )

Start the event loop thread.

Returns zero on success, negative on error.

◆ pa_threaded_mainloop_stop()

void pa_threaded_mainloop_stop ( pa_threaded_mainloop * m )

Terminate the event loop thread cleanly.

Make sure to unlock the mainloop object before calling this function.

◆ pa_threaded_mainloop_unlock()

void pa_threaded_mainloop_unlock ( pa_threaded_mainloop * m )

Unlock the event loop object, inverse of pa_threaded_mainloop_lock().

◆ pa_threaded_mainloop_wait()

void pa_threaded_mainloop_wait ( pa_threaded_mainloop * m )

Wait for an event to be signalled by the event loop thread.

You can use this to pass data from the event loop thread to the main thread in a synchronized fashion. This function may not be called inside the event loop thread. Prior to this call the event loop object needs to be locked using pa_threaded_mainloop_lock(). While waiting the lock will be released. Immediately before returning it will be acquired again. This function may spuriously wake up even without pa_threaded_mainloop_signal() being called. You need to make sure to handle that!

Typedefs

Functions