Queue internals

Low-level queue functions. More...

Collaboration diagram for Queue internals:

Functions
static void	vlc_queue_Lock (vlc_queue_t *q)
	Locks a queue.
static void	vlc_queue_Unlock (vlc_queue_t *q)
	Unlocks a queue.
static void	vlc_queue_Signal (vlc_queue_t *q)
	Wakes one thread waiting for a queue entry up.
static void	vlc_queue_Wait (vlc_queue_t *q)
	Waits for a queue entry.
void	vlc_queue_EnqueueUnlocked (vlc_queue_t *q, void *entry)
	Queues an entry (without locking).
void *	vlc_queue_DequeueUnlocked (vlc_queue_t *)
	Dequeues the oldest entry (without locking).
void *	vlc_queue_DequeueAllUnlocked (vlc_queue_t *)
	Dequeues all entries (without locking).
static bool	vlc_queue_IsEmpty (const vlc_queue_t *q)
	Checks if a queue is empty (without locking).

Detailed Description

Low-level queue functions.

In some cases, the high-level queue functions do not exactly fit the use case requirements, and it is necessary to access the queue internals. This typically occurs when threads wait for elements to be added to the queue at the same time as some other type of events.

Function Documentation

vlc_queue_DequeueAllUnlocked()

void * vlc_queue_DequeueAllUnlocked

(

vlc_queue_t *

q

)

Dequeues all entries (without locking).

This is equivalent to calling vlc_queue_DequeueUnlocked() repeatedly until the queue is emptied. However this function is much faster than that, as it does not need to update the linked-list pointers.

Warning

It is assumed that the caller already holds the queue lock; otherwise the behaviour is undefined.

Returns

a linked-list of all entries (possibly NULL if none)

References vlc_queue::first, vlc_queue::lastp, vlc_queue::lock, and vlc_mutex_assert.

Referenced by vlc_fifo_DequeueAllUnlocked(), vlc_queue_DequeueAll(), and vlc_stream_fifo_Destroy().

vlc_queue_DequeueUnlocked()

void * vlc_queue_DequeueUnlocked

(

vlc_queue_t *

q

)

Dequeues the oldest entry (without locking).

This function dequeues an entry from a thread-safe queue. It is assumed that the caller already holds the queue lock; otherwise the behaviour is undefined.

Warning

It is assumed that the caller already holds the queue lock; otherwise the behaviour is undefined.

Returns

the first entry in the queue, or NULL if the queue is empty

References vlc_queue::first, vlc_queue::lastp, vlc_queue::lock, next_get(), vlc_queue::next_offset, next_set(), and vlc_mutex_assert.

Referenced by vlc_fifo_DequeueUnlocked(), vlc_queue_Dequeue(), and vlc_queue_DequeueKillable().

vlc_queue_EnqueueUnlocked()

void vlc_queue_EnqueueUnlocked	(	vlc_queue_t *	q,
		void *	entry
	)

Queues an entry (without locking).

This function enqueues an entry, or rather a linked-list of entries, in a thread-safe queue, without taking the queue lock.

Warning

It is assumed that the caller already holds the queue lock; otherwise the behaviour is undefined.

Parameters

q	A queue locked with vlc_queue_Lock
entry	NULL-terminated list of entries to queue (if NULL, this function has no effects)

References entry_get(), entry_set(), vlc_queue::lastp, vlc_queue::lock, next_get(), vlc_queue::next_offset, next_p(), vlc_mutex_assert, and vlc_queue_Signal().

Referenced by vlc_fifo_QueueUnlocked(), vlc_queue_Enqueue(), and vlc_stream_fifo_Queue().

vlc_queue_IsEmpty()

static bool vlc_queue_IsEmpty ( const vlc_queue_t *  q )

inlinestatic

Checks if a queue is empty (without locking).

Warning

It is assumed that the caller already holds the queue lock; otherwise the behaviour is undefined.

Return values

false	the queue contains one or more entries
true	the queue is empty

References vlc_queue::first.

Referenced by vlc_fifo_IsEmpty(), vlc_queue_Dequeue(), and vlc_queue_DequeueKillable().

vlc_queue_Lock()

static void vlc_queue_Lock ( vlc_queue_t *  q )

inlinestatic

Locks a queue.

No more than one thread can lock a queue at any given time, and no other thread can modify the queue while it is locked. Accordingly, if the queue is already locked by another thread, this function waits.

Use vlc_queue_Unlock() to release the lock.

Warning

Recursively locking a single queue is undefined. Also locking more than one queue at a time may lead to lock inversion: mind the locking order!

References vlc_queue::lock, and vlc_mutex_lock().

Referenced by vlc_fifo_Lock(), vlc_queue_Dequeue(), vlc_queue_DequeueAll(), vlc_queue_DequeueKillable(), vlc_queue_Enqueue(), vlc_queue_Kill(), vlc_stream_fifo_Close(), vlc_stream_fifo_Destroy(), and vlc_stream_fifo_Queue().

vlc_queue_Signal()

static void vlc_queue_Signal ( vlc_queue_t *  q )

inlinestatic

Wakes one thread waiting for a queue entry up.

References vlc_cond_signal(), and vlc_queue::wait.

Referenced by vlc_fifo_Signal(), vlc_queue_EnqueueUnlocked(), vlc_queue_Kill(), and vlc_stream_fifo_Close().

vlc_queue_Unlock()

static void vlc_queue_Unlock ( vlc_queue_t *  q )

inlinestatic

Unlocks a queue.

This releases the lock on a queue, allowing other threads to manipulate the queue. The behaviour is undefined if the calling thread is not holding the queue lock.

References vlc_queue::lock, and vlc_mutex_unlock().

Referenced by vlc_fifo_Unlock(), vlc_queue_Dequeue(), vlc_queue_DequeueAll(), vlc_queue_DequeueKillable(), vlc_queue_Enqueue(), vlc_queue_Kill(), vlc_stream_fifo_Close(), vlc_stream_fifo_Destroy(), and vlc_stream_fifo_Queue().

vlc_queue_Wait()

static void vlc_queue_Wait ( vlc_queue_t *  q )

inlinestatic

Waits for a queue entry.

Note

This function is a cancellation point. In case of cancellation, the queue will be locked, as is consistent for condition variable semantics.

Bug:

This function should probably not be aware of cancellation.

References vlc_queue::lock, vlc_cond_wait(), and vlc_queue::wait.

Referenced by vlc_fifo_Wait(), vlc_queue_Dequeue(), and vlc_queue_DequeueKillable().