VLC  4.0.0-dev
Functions

Low-level queue functions. More...

Collaboration diagram for Queue internals:

Functions

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

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 )

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(), vlc_queue_Wait(), and vlc_stream_fifo_Destroy().

◆ vlc_queue_DequeueUnlocked()

void* vlc_queue_DequeueUnlocked ( vlc_queue_t )

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(), vlc_queue_DequeueKillable(), and vlc_queue_Wait().

◆ vlc_queue_EnqueueUnlocked()

void vlc_queue_EnqueueUnlocked ( vlc_queue_t ,
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
entryNULL-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(), vlc_queue_Wait(), 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
falsethe queue contains one or more entries
truethe queue is empty

References vlc_queue::first, VLC_API, vlc_queue_Dequeue(), vlc_queue_DequeueAll(), vlc_queue_Enqueue(), and VLC_USED.

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_API, vlc_cond_wait(), vlc_queue_DequeueAllUnlocked(), vlc_queue_DequeueUnlocked(), vlc_queue_EnqueueUnlocked(), VLC_USED, and vlc_queue::wait.

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