Block FIFO

Thread-safe block queue functions. More...

Collaboration diagram for Block FIFO:

Macros
#define	vlc_fifo_Assert(fifo)   assert(vlc_fifo_Held(fifo))
	Asserts that a vlc_fifo_t is locked by the calling thread. More...
#define	vlc_fifo_CleanupPush(fifo)   vlc_cleanup_push(vlc_fifo_Cleanup, fifo)

Functions
vlc_fifo_t *	vlc_fifo_New (void)
	Creates a thread-safe FIFO queue of blocks. More...
void	vlc_fifo_Delete (vlc_fifo_t *)
	Delete a FIFO created by vlc_fifo_New(). More...
vlc_frame_t *	vlc_fifo_Get (vlc_fifo_t *)
	Dequeue the first block from the FIFO. More...
vlc_frame_t *	vlc_fifo_Show (vlc_fifo_t *)
	Peeks the first block in the FIFO. More...
static vlc_queue_t *	vlc_fifo_queue (const vlc_fifo_t *fifo)
static void	vlc_fifo_Lock (vlc_fifo_t *fifo)
	Locks a block FIFO. More...
static void	vlc_fifo_Unlock (vlc_fifo_t *fifo)
	Unlocks a block FIFO. More...
static void	vlc_fifo_Signal (vlc_fifo_t *fifo)
	Wakes up one thread waiting on the FIFO, if any. More...
static void	vlc_fifo_Wait (vlc_fifo_t *fifo)
	Waits on the FIFO. More...
static void	vlc_fifo_WaitCond (vlc_fifo_t *fifo, vlc_cond_t *condvar)
void	vlc_fifo_QueueUnlocked (vlc_fifo_t *fifo, vlc_frame_t *block)
	Queues a linked-list of blocks into a locked FIFO. More...
vlc_frame_t *	vlc_fifo_DequeueUnlocked (vlc_fifo_t *)
	Dequeues the first block from a locked FIFO, if any. More...
vlc_frame_t *	vlc_fifo_DequeueAllUnlocked (vlc_fifo_t *)
	Dequeues the all blocks from a locked FIFO. More...
size_t	vlc_fifo_GetCount (const vlc_fifo_t *)
	Counts blocks in a FIFO. More...
size_t	vlc_fifo_GetBytes (const vlc_fifo_t *)
	Counts bytes in a FIFO. More...
bool	vlc_fifo_Held (const vlc_fifo_t *fifo)
	Checks whether the vlc_fifo_t object is being locked. More...
static bool	vlc_fifo_IsEmpty (const vlc_fifo_t *fifo)
static void	vlc_fifo_Cleanup (void *fifo)
static void	vlc_fifo_Empty (vlc_fifo_t *fifo)
	Clears all blocks in a FIFO. More...
static void	vlc_fifo_Put (vlc_fifo_t *fifo, vlc_frame_t *block)
	Immediately queue one block at the end of a FIFO. More...
static size_t	vlc_fifo_Size (vlc_fifo_t *fifo)
static size_t	vlc_fifo_Count (vlc_fifo_t *fifo)

Detailed Description

Thread-safe block queue functions.

Macro Definition Documentation

vlc_fifo_Assert

#define vlc_fifo_Assert

(

fifo

)

assert(vlc_fifo_Held(fifo))

Asserts that a vlc_fifo_t is locked by the calling thread.

vlc_fifo_CleanupPush

#define vlc_fifo_CleanupPush

(

fifo

)

vlc_cleanup_push(vlc_fifo_Cleanup, fifo)

Function Documentation

vlc_fifo_Cleanup()

static void vlc_fifo_Cleanup ( void *  fifo )

inlinestatic

References vlc_fifo_Unlock().

vlc_fifo_Count()

static size_t vlc_fifo_Count ( vlc_fifo_t *  fifo )

inlinestatic

References vlc_fifo_GetCount(), vlc_fifo_Lock(), and vlc_fifo_Unlock().

vlc_fifo_Delete()

void vlc_fifo_Delete

(

vlc_fifo_t *

p_fifo

)

Delete a FIFO created by vlc_fifo_New().

Note

Any queued blocks are also deleted.

Warning

No other threads may be using the FIFO when this function is called. Otherwise, undefined behaviour will occur.

References vlc_fifo_Empty().

vlc_fifo_DequeueAllUnlocked()

vlc_frame_t * vlc_fifo_DequeueAllUnlocked

(

vlc_fifo_t *

fifo

)

Dequeues the all blocks from a locked FIFO.

This is equivalent to calling vlc_fifo_DequeueUnlocked() repeatedly until the FIFO is emptied, but this function is much faster.

Note

This function is not a cancellation point.

Warning

The FIFO must be locked by the calling thread using vlc_fifo_Lock(). Otherwise behaviour is undefined.

Returns

a linked-list of all blocks in the FIFO (possibly NULL)

References vlc_fifo_t::i_depth, vlc_fifo_t::i_size, vlc_fifo_t::q, and vlc_queue_DequeueAllUnlocked().

Referenced by vlc_fifo_Empty(), vlc_input_decoder_Decode(), and vlc_input_decoder_Flush().

vlc_fifo_DequeueUnlocked()

vlc_frame_t * vlc_fifo_DequeueUnlocked

(

vlc_fifo_t *

fifo

)

Dequeues the first block from a locked FIFO, if any.

Note

This function is not a cancellation point.

Warning

The FIFO must be locked by the calling thread using vlc_fifo_Lock(). Otherwise behaviour is undefined.

Returns

the first block in the FIFO or NULL if the FIFO is empty

References vlc_frame_t::i_buffer, vlc_fifo_t::i_depth, vlc_fifo_t::i_size, vlc_fifo_t::q, and vlc_queue_DequeueUnlocked().

Referenced by DecoderThread(), and vlc_fifo_Get().

vlc_fifo_Empty()

static void vlc_fifo_Empty ( vlc_fifo_t *  fifo )

inlinestatic

Clears all blocks in a FIFO.

References vlc_fifo_DequeueAllUnlocked(), vlc_fifo_Lock(), vlc_fifo_Unlock(), and vlc_frame_ChainRelease().

Referenced by vlc_fifo_Delete().

vlc_fifo_Get()

vlc_frame_t * vlc_fifo_Get

(

vlc_fifo_t *

fifo

)

Dequeue the first block from the FIFO.

If necessary, wait until there is one block in the queue. This function is (always) cancellation point.

Returns

a valid block

References vlc_cleanup_pop, vlc_fifo_CleanupPush, vlc_fifo_DequeueUnlocked(), vlc_fifo_IsEmpty(), vlc_fifo_Lock(), vlc_fifo_Unlock(), vlc_fifo_Wait(), and vlc_testcancel().

vlc_fifo_GetBytes()

size_t vlc_fifo_GetBytes

(

const vlc_fifo_t *

fifo

)

Counts bytes in a FIFO.

Checks how many bytes are queued in a locked FIFO.

Note

This function is not cancellation point.

Warning

The FIFO must be locked by the calling thread using vlc_fifo_Lock(). Otherwise behaviour is undefined.

Returns

the total number of bytes

Note

Zero bytes does not necessarily mean that the FIFO is empty since a block could contain zero bytes. Use vlc_fifo_GetCount() to determine if a FIFO is empty.

References vlc_fifo_t::i_size, vlc_queue::lock, vlc_fifo_t::q, and vlc_mutex_assert.

Referenced by vlc_fifo_Size(), and vlc_input_decoder_Decode().

vlc_fifo_GetCount()

size_t vlc_fifo_GetCount

(

const vlc_fifo_t *

fifo

)

Counts blocks in a FIFO.

Checks how many blocks are queued in a locked FIFO.

Note

This function is not cancellation point.

Warning

The FIFO must be locked by the calling thread using vlc_fifo_Lock(). Otherwise behaviour is undefined.

Returns

the number of blocks in the FIFO (zero if it is empty)

References vlc_fifo_t::i_depth, vlc_queue::lock, vlc_fifo_t::q, and vlc_mutex_assert.

Referenced by vlc_fifo_Count(), and vlc_input_decoder_Decode().

vlc_fifo_Held()

bool vlc_fifo_Held

(

const vlc_fifo_t *

fifo

)

Checks whether the vlc_fifo_t object is being locked.

This function checks if the calling thread holds a given vlc_fifo_t object. It has no side effects and is essentially intended for run-time debugging.

Note

This function is the vlc_fifo_t equivalent of vlc_mutex_held.

To assert that the calling thread holds a lock, the helper macro vlc_fifo_Assert() should be used instead of this function.

Return values

false	the fifo is not locked by the calling thread
true	the fifo is locked by the calling thread

References vlc_queue::lock, vlc_fifo_t::q, and vlc_mutex_held().

vlc_fifo_IsEmpty()

static bool vlc_fifo_IsEmpty ( const vlc_fifo_t *  fifo )

inlinestatic

References vlc_fifo_queue(), and vlc_queue_IsEmpty().

Referenced by vlc_fifo_Get(), vlc_input_decoder_Decode(), vlc_input_decoder_IsEmpty(), and vlc_input_decoder_Wait().

vlc_fifo_Lock()

static void vlc_fifo_Lock ( vlc_fifo_t *  fifo )

inlinestatic

Locks a block FIFO.

No more than one thread can lock the FIFO at any given time, and no other thread can modify the FIFO while it is locked. vlc_fifo_Unlock() releases the lock.

Note

If the FIFO is already locked by another thread, this function waits. This function is not a cancellation point.

Warning

Recursively locking a single FIFO is undefined. Locking more than one FIFO at a time may lead to lock inversion; mind the locking order.

References vlc_fifo_queue(), and vlc_queue_Lock().

Referenced by CreateVoutIfNeeded(), DecoderPlayCc(), DecoderThread(), DecoderThread_ProcessInput(), ModuleThread_GetDecoderDevice(), ModuleThread_GetDisplayDate(), ModuleThread_GetDisplayRate(), ModuleThread_NewSpuBuffer(), ModuleThread_PlaySpu(), ModuleThread_QueueAudio(), ModuleThread_QueueSpu(), ModuleThread_QueueThumbnail(), ModuleThread_QueueVideo(), ModuleThread_UpdateAudioFormat(), ModuleThread_UpdateVideoFormat(), thumbnailer_buffer_new(), vlc_fifo_Count(), vlc_fifo_Empty(), vlc_fifo_Get(), vlc_fifo_Put(), vlc_fifo_Show(), vlc_fifo_Size(), vlc_input_decoder_AddVoutOverlay(), vlc_input_decoder_ChangeDelay(), vlc_input_decoder_ChangePause(), vlc_input_decoder_ChangeRate(), vlc_input_decoder_Decode(), vlc_input_decoder_Delete(), vlc_input_decoder_DelVoutOverlay(), vlc_input_decoder_Drain(), vlc_input_decoder_Flush(), vlc_input_decoder_FrameNext(), vlc_input_decoder_GetStatus(), vlc_input_decoder_IsEmpty(), vlc_input_decoder_SetSpuHighlight(), vlc_input_decoder_StartWait(), vlc_input_decoder_StopWait(), and vlc_input_decoder_Wait().

vlc_fifo_New()

vlc_fifo_t * vlc_fifo_New

(

void

)

Creates a thread-safe FIFO queue of blocks.

See also vlc_fifo_Put() and vlc_fifo_Get(). The created queue must be deleted with vlc_fifo_Delete().

Returns

the FIFO or NULL on memory error

References vlc_fifo_t::i_depth, vlc_fifo_t::i_size, likely, vlc_fifo_t::q, and vlc_queue_Init().

vlc_fifo_Put()

static void vlc_fifo_Put ( vlc_fifo_t *  fifo, vlc_frame_t *  block  )

inlinestatic

Immediately queue one block at the end of a FIFO.

Parameters

fifo	queue
block	head of a block list to queue (may be NULL)

References vlc_fifo_Lock(), vlc_fifo_QueueUnlocked(), and vlc_fifo_Unlock().

vlc_fifo_queue()

static vlc_queue_t * vlc_fifo_queue ( const vlc_fifo_t *  fifo )

inlinestatic

Referenced by vlc_fifo_IsEmpty(), vlc_fifo_Lock(), vlc_fifo_Signal(), vlc_fifo_Unlock(), vlc_fifo_Wait(), and vlc_fifo_WaitCond().

vlc_fifo_QueueUnlocked()

void vlc_fifo_QueueUnlocked	(	vlc_fifo_t *	fifo,
		vlc_frame_t *	block
	)

Queues a linked-list of blocks into a locked FIFO.

Parameters

block

the head of the list of blocks (if NULL, this function has no effects)

Note

This function is not a cancellation point.

Warning

The FIFO must be locked by the calling thread using vlc_fifo_Lock(). Otherwise behaviour is undefined.

References vlc_fifo_t::i_depth, vlc_fifo_t::i_size, vlc_frame_t::p_next, vlc_fifo_t::q, and vlc_queue_EnqueueUnlocked().

Referenced by vlc_fifo_Put(), and vlc_input_decoder_Decode().

vlc_fifo_Show()

vlc_frame_t * vlc_fifo_Show

(

vlc_fifo_t *

p_fifo

)

Peeks the first block in the FIFO.

Warning

This function leaves the block in the FIFO. You need to protect against concurrent threads who could dequeue the block. Preferably, there should be only one thread reading from the FIFO.

This function is undefined if the FIFO is empty.

Returns

a valid block.

References vlc_queue::first, vlc_fifo_t::q, vlc_fifo_Lock(), and vlc_fifo_Unlock().

vlc_fifo_Signal()

static void vlc_fifo_Signal ( vlc_fifo_t *  fifo )

inlinestatic

Wakes up one thread waiting on the FIFO, if any.

Note

This function is not a cancellation point.

Warning

For race-free operations, the FIFO should be locked by the calling thread. The function can be called on a unlocked FIFO however.

References vlc_fifo_queue(), and vlc_queue_Signal().

Referenced by vlc_input_decoder_ChangePause(), vlc_input_decoder_Delete(), vlc_input_decoder_Drain(), vlc_input_decoder_Flush(), and vlc_input_decoder_FrameNext().

vlc_fifo_Size()

static size_t vlc_fifo_Size ( vlc_fifo_t *  fifo )

inlinestatic

References vlc_fifo_GetBytes(), vlc_fifo_Lock(), and vlc_fifo_Unlock().

vlc_fifo_Unlock()

static void vlc_fifo_Unlock ( vlc_fifo_t *  fifo )

inlinestatic

Unlocks a block FIFO.

The calling thread must have locked the FIFO previously with vlc_fifo_Lock(). Otherwise, the behaviour is undefined.

Note

This function is not a cancellation point.

References vlc_fifo_queue(), and vlc_queue_Unlock().

Referenced by CreateVoutIfNeeded(), DecoderPlayCc(), DecoderThread(), DecoderThread_ProcessInput(), ModuleThread_GetDecoderDevice(), ModuleThread_GetDisplayDate(), ModuleThread_GetDisplayRate(), ModuleThread_NewSpuBuffer(), ModuleThread_PlaySpu(), ModuleThread_QueueAudio(), ModuleThread_QueueSpu(), ModuleThread_QueueThumbnail(), ModuleThread_QueueVideo(), ModuleThread_UpdateAudioFormat(), ModuleThread_UpdateVideoFormat(), thumbnailer_buffer_new(), vlc_fifo_Cleanup(), vlc_fifo_Count(), vlc_fifo_Empty(), vlc_fifo_Get(), vlc_fifo_Put(), vlc_fifo_Show(), vlc_fifo_Size(), vlc_input_decoder_AddVoutOverlay(), vlc_input_decoder_ChangeDelay(), vlc_input_decoder_ChangePause(), vlc_input_decoder_ChangeRate(), vlc_input_decoder_Decode(), vlc_input_decoder_Delete(), vlc_input_decoder_DelVoutOverlay(), vlc_input_decoder_Drain(), vlc_input_decoder_Flush(), vlc_input_decoder_FrameNext(), vlc_input_decoder_GetStatus(), vlc_input_decoder_IsEmpty(), vlc_input_decoder_SetSpuHighlight(), vlc_input_decoder_StartWait(), vlc_input_decoder_StopWait(), and vlc_input_decoder_Wait().

vlc_fifo_Wait()

static void vlc_fifo_Wait ( vlc_fifo_t *  fifo )

inlinestatic

Waits on the FIFO.

Atomically unlocks the FIFO and waits until one thread signals the FIFO, then locks the FIFO again. A signal can be sent by queueing a block to the previously empty FIFO or by calling vlc_fifo_Signal() directly. This function may also return spuriously at any moment.

Note

This function is a cancellation point. In case of cancellation, the the FIFO will be locked before cancellation cleanup handlers are processed.

References vlc_fifo_queue(), and vlc_queue_Wait().

Referenced by DecoderThread(), and vlc_fifo_Get().

vlc_fifo_WaitCond()

static void vlc_fifo_WaitCond ( vlc_fifo_t *  fifo, vlc_cond_t *  condvar  )

inlinestatic

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

Referenced by DecoderWaitUnblock(), vlc_input_decoder_Decode(), and vlc_input_decoder_Wait().