1 /*****************************************************************************
2 * vlc_block.h: Data blocks management functions
3 *****************************************************************************
4 * Copyright (C) 2003 VLC authors and VideoLAN
6 * Authors: Laurent Aimar <fenrir@via.ecp.fr>
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation; either version 2.1 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program; if not, write to the Free Software Foundation,
20 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21 *****************************************************************************/
27 * \defgroup block Data blocks
30 * Blocks of binary data.
32 * @ref block_t is a generic structure to represent a binary blob within VLC.
33 * The primary goal of the structure is to avoid memory copying as data is
34 * passed around. It is notably used between the \ref demux, the packetizer
35 * (if present) and the \ref decoder, and for audio, between the \ref decoder,
36 * the audio filters, and the \ref audio_output.
40 * Data block definition and functions
43 #include <sys/types.h> /* for ssize_t */
45 /****************************************************************************
47 ****************************************************************************
48 * - i_flags may not always be set (ie could be 0, even for a key frame
49 * it depends where you receive the buffer (before/after a packetizer
50 * and the demux/packetizer implementations.
51 * - i_dts/i_pts could be VLC_TICK_INVALID, it means no pts/dts
52 * - i_length: length in microseond of the packet, can be null except in the
53 * sout where it is mandatory.
55 * - i_buffer number of valid data pointed by p_buffer
56 * you can freely decrease it but never increase it yourself
58 * - p_buffer: pointer over datas. You should never overwrite it, you can
59 * only incremment it to skip datas, in others cases use block_Realloc
60 * (don't duplicate yourself in a bigger buffer, block_Realloc is
61 * optimised for preheader/postdatas increase)
62 ****************************************************************************/
64 /** The content doesn't follow the last block, possible some blocks in between
66 #define BLOCK_FLAG_DISCONTINUITY 0x0001
68 #define BLOCK_FLAG_TYPE_I 0x0002
69 /** Inter frame with backward reference only */
70 #define BLOCK_FLAG_TYPE_P 0x0004
71 /** Inter frame with backward and forward reference */
72 #define BLOCK_FLAG_TYPE_B 0x0008
73 /** For inter frame when you don't know the real type */
74 #define BLOCK_FLAG_TYPE_PB 0x0010
75 /** Warn that this block is a header one */
76 #define BLOCK_FLAG_HEADER 0x0020
77 /** This block contains the last part of a sequence */
78 #define BLOCK_FLAG_END_OF_SEQUENCE 0x0040
79 /** This block contains a clock reference */
80 #define BLOCK_FLAG_CLOCK 0x0080
81 /** This block is scrambled */
82 #define BLOCK_FLAG_SCRAMBLED 0x0100
83 /** This block has to be decoded but not be displayed */
84 #define BLOCK_FLAG_PREROLL 0x0200
85 /** This block is corrupted and/or there is data loss */
86 #define BLOCK_FLAG_CORRUPTED 0x0400
87 /** This block contains an interlaced picture with top field stored first */
88 #define BLOCK_FLAG_TOP_FIELD_FIRST 0x0800
89 /** This block contains an interlaced picture with bottom field stored first */
90 #define BLOCK_FLAG_BOTTOM_FIELD_FIRST 0x1000
91 /** This block contains a single field from interlaced picture. */
92 #define BLOCK_FLAG_SINGLE_FIELD 0x2000
94 /** This block contains an interlaced picture */
95 #define BLOCK_FLAG_INTERLACED_MASK \
96 (BLOCK_FLAG_TOP_FIELD_FIRST|BLOCK_FLAG_BOTTOM_FIELD_FIRST|BLOCK_FLAG_SINGLE_FIELD)
98 #define BLOCK_FLAG_TYPE_MASK \
99 (BLOCK_FLAG_TYPE_I|BLOCK_FLAG_TYPE_P|BLOCK_FLAG_TYPE_B|BLOCK_FLAG_TYPE_PB)
101 /* These are for input core private usage only */
102 #define BLOCK_FLAG_CORE_PRIVATE_MASK 0x00ff0000
103 #define BLOCK_FLAG_CORE_PRIVATE_SHIFT 16
105 /* These are for module private usage only */
106 #define BLOCK_FLAG_PRIVATE_MASK 0xff000000
107 #define BLOCK_FLAG_PRIVATE_SHIFT 24
109 struct vlc_block_callbacks
111 void (*free
)(block_t
*);
118 uint8_t *p_buffer
; /**< Payload start */
119 size_t i_buffer
; /**< Payload length */
120 uint8_t *p_start
; /**< Buffer start */
121 size_t i_size
; /**< Buffer total size */
124 unsigned i_nb_samples
; /* Used for audio */
130 const struct vlc_block_callbacks
*cbs
;
134 * Initializes a custom block.
136 * This function initialize a block of timed data allocated by custom means.
137 * This allows passing data with copying even if the data has been allocated
138 * with unusual means or outside of LibVLC.
140 * Normally, blocks are allocated and initialized by block_Alloc() instead.
142 * @param block allocated block structure to initialize
143 * @param cbs structure of custom callbacks to handle the block [IN]
144 * @param base start address of the block data
145 * @param length byte length of the block data
147 * @return @c block (this function cannot fail)
149 VLC_API block_t
*block_Init(block_t
*block
,
150 const struct vlc_block_callbacks
*cbs
,
151 void *base
, size_t length
);
156 * Creates a new block with the requested size.
157 * The block must be released with block_Release().
159 * @param size size in bytes (possibly zero)
160 * @return the created block, or NULL on memory error.
162 VLC_API block_t
*block_Alloc(size_t size
) VLC_USED VLC_MALLOC
;
164 VLC_API block_t
*block_TryRealloc(block_t
*, ssize_t pre
, size_t body
) VLC_USED
;
167 * Reallocates a block.
169 * This function expands, shrinks or moves a data block.
170 * In many cases, this function can return without any memory allocation by
171 * reusing spare buffer space. Otherwise, a new block is created and data is
174 * @param pre count of bytes to prepend if positive,
175 * count of leading bytes to discard if negative
176 * @param body new bytes size of the block
178 * @return the reallocated block on succes, NULL on error.
180 * @note Skipping leading bytes can be achieved directly by subtracting from
181 * block_t.i_buffer and adding block_t.p_buffer.
182 * @note Discard trailing bytes can be achieved directly by subtracting from
184 * @note On error, the block is discarded.
185 * To avoid that, use block_TryRealloc() instead.
187 VLC_API block_t
*block_Realloc(block_t
*, ssize_t pre
, size_t body
) VLC_USED
;
192 * This function works for any @ref block_t block, regardless of the way it was
196 * If the block is in a chain, this function does <b>not</b> release any
197 * subsequent block in the chain. Use block_ChainRelease() for that purpose.
199 * @param block block to release (cannot be NULL)
201 VLC_API
void block_Release(block_t
*block
);
203 static inline void block_CopyProperties( block_t
*dst
, const block_t
*src
)
205 dst
->i_flags
= src
->i_flags
;
206 dst
->i_nb_samples
= src
->i_nb_samples
;
207 dst
->i_dts
= src
->i_dts
;
208 dst
->i_pts
= src
->i_pts
;
209 dst
->i_length
= src
->i_length
;
213 * Duplicates a block.
215 * Creates a writeable duplicate of a block.
217 * @return the duplicate on success, NULL on error.
220 static inline block_t
*block_Duplicate( const block_t
*p_block
)
222 block_t
*p_dup
= block_Alloc( p_block
->i_buffer
);
226 block_CopyProperties( p_dup
, p_block
);
227 memcpy( p_dup
->p_buffer
, p_block
->p_buffer
, p_block
->i_buffer
);
233 * Wraps heap in a block.
235 * Creates a @ref block_t out of an existing heap allocation.
236 * This is provided by LibVLC so that manually heap-allocated blocks can safely
237 * be deallocated even after the origin plugin has been unloaded from memory.
239 * When block_Release() is called, VLC will free() the specified pointer.
241 * @param addr base address of the heap allocation (will be free()'d)
242 * @param length bytes length of the heap allocation
243 * @return NULL in case of error (ptr free()'d in that case), or a valid
246 VLC_API block_t
*block_heap_Alloc(void *, size_t) VLC_USED VLC_MALLOC
;
249 * Wraps a memory mapping in a block
251 * Creates a @ref block_t from a virtual address memory mapping (mmap).
252 * This is provided by LibVLC so that mmap blocks can safely be deallocated
253 * even after the allocating plugin has been unloaded from memory.
255 * @param addr base address of the mapping (as returned by mmap)
256 * @param length length (bytes) of the mapping (as passed to mmap)
257 * @return NULL if addr is MAP_FAILED, or an error occurred (in the later
258 * case, munmap(addr, length) is invoked before returning).
260 VLC_API block_t
*block_mmap_Alloc(void *addr
, size_t length
) VLC_USED VLC_MALLOC
;
263 * Wraps a System V memory segment in a block
265 * Creates a @ref block_t from a System V shared memory segment (shmget()).
266 * This is provided by LibVLC so that segments can safely be deallocated
267 * even after the allocating plugin has been unloaded from memory.
269 * @param addr base address of the segment (as returned by shmat())
270 * @param length length (bytes) of the segment (as passed to shmget())
271 * @return NULL if an error occurred (in that case, shmdt(addr) is invoked
272 * before returning NULL).
274 VLC_API block_t
* block_shm_Alloc(void *addr
, size_t length
) VLC_USED VLC_MALLOC
;
277 * Maps a file handle in memory.
279 * Loads a file into a block of memory through a file descriptor.
280 * If possible a private file mapping is created. Otherwise, the file is read
281 * normally. This function is a cancellation point.
283 * @note On 32-bits platforms,
284 * this function will not work for very large files,
285 * due to memory space constraints.
287 * @param fd file descriptor to load from
288 * @param write If true, request a read/write private mapping.
289 * If false, request a read-only potentially shared mapping.
291 * @return a new block with the file content at p_buffer, and file length at
292 * i_buffer (release it with block_Release()), or NULL upon error (see errno).
294 VLC_API block_t
*block_File(int fd
, bool write
) VLC_USED VLC_MALLOC
;
297 * Maps a file in memory.
299 * Loads a file into a block of memory from a path to the file.
300 * See also block_File().
302 * @param write If true, request a read/write private mapping.
303 * If false, request a read-only potentially shared mapping.
305 VLC_API block_t
*block_FilePath(const char *, bool write
) VLC_USED VLC_MALLOC
;
307 static inline void block_Cleanup (void *block
)
309 block_Release ((block_t
*)block
);
311 #define block_cleanup_push( block ) vlc_cleanup_push (block_Cleanup, block)
314 * \defgroup block_fifo Block chain
318 /****************************************************************************
319 * Chains of blocks functions helper
320 ****************************************************************************
321 * - block_ChainAppend : append a block to the last block of a chain. Try to
322 * avoid using with a lot of data as it's really slow, prefer
323 * block_ChainLastAppend, p_block can be NULL
324 * - block_ChainLastAppend : use a pointer over a pointer to the next blocks,
326 * - block_ChainRelease : release a chain of block
327 * - block_ChainExtract : extract data from a chain, return real bytes counts
328 * - block_ChainGather : gather a chain, free it and return one block.
329 ****************************************************************************/
330 static inline void block_ChainAppend( block_t
**pp_list
, block_t
*p_block
)
332 if( *pp_list
== NULL
)
338 block_t
*p
= *pp_list
;
340 while( p
->p_next
) p
= p
->p_next
;
345 static inline void block_ChainLastAppend( block_t
***ppp_last
, block_t
*p_block
)
347 block_t
*p_last
= p_block
;
349 **ppp_last
= p_block
;
351 while( p_last
->p_next
) p_last
= p_last
->p_next
;
352 *ppp_last
= &p_last
->p_next
;
355 static inline void block_ChainRelease( block_t
*p_block
)
359 block_t
*p_next
= p_block
->p_next
;
360 block_Release( p_block
);
365 static size_t block_ChainExtract( block_t
*p_list
, void *p_data
, size_t i_max
)
368 uint8_t *p
= (uint8_t*)p_data
;
370 while( p_list
&& i_max
)
372 size_t i_copy
= __MIN( i_max
, p_list
->i_buffer
);
373 memcpy( p
, p_list
->p_buffer
, i_copy
);
378 p_list
= p_list
->p_next
;
383 static inline void block_ChainProperties( block_t
*p_list
, int *pi_count
, size_t *pi_size
, vlc_tick_t
*pi_length
)
386 vlc_tick_t i_length
= 0;
391 i_size
+= p_list
->i_buffer
;
392 i_length
+= p_list
->i_length
;
395 p_list
= p_list
->p_next
;
401 *pi_length
= i_length
;
406 static inline block_t
*block_ChainGather( block_t
*p_list
)
409 vlc_tick_t i_length
= 0;
412 if( p_list
->p_next
== NULL
)
413 return p_list
; /* Already gathered */
415 block_ChainProperties( p_list
, NULL
, &i_total
, &i_length
);
417 g
= block_Alloc( i_total
);
420 block_ChainExtract( p_list
, g
->p_buffer
, g
->i_buffer
);
422 g
->i_flags
= p_list
->i_flags
;
423 g
->i_pts
= p_list
->i_pts
;
424 g
->i_dts
= p_list
->i_dts
;
425 g
->i_length
= i_length
;
428 block_ChainRelease( p_list
);
434 * \defgroup fifo Block FIFO
435 * Thread-safe block queue functions
440 * Creates a thread-safe FIFO queue of blocks.
442 * See also block_FifoPut() and block_FifoGet().
443 * The created queue must be released with block_FifoRelease().
445 * @return the FIFO or NULL on memory error
447 VLC_API block_fifo_t
*block_FifoNew(void) VLC_USED VLC_MALLOC
;
450 * Destroys a FIFO created by block_FifoNew().
452 * @note Any queued blocks are also destroyed.
453 * @warning No other threads may be using the FIFO when this function is
454 * called. Otherwise, undefined behaviour will occur.
456 VLC_API
void block_FifoRelease(block_fifo_t
*);
459 * Clears all blocks in a FIFO.
461 VLC_API
void block_FifoEmpty(block_fifo_t
*);
464 * Immediately queue one block at the end of a FIFO.
467 * @param block head of a block list to queue (may be NULL)
469 VLC_API
void block_FifoPut(block_fifo_t
*fifo
, block_t
*block
);
472 * Dequeue the first block from the FIFO. If necessary, wait until there is
473 * one block in the queue. This function is (always) cancellation point.
475 * @return a valid block
477 VLC_API block_t
*block_FifoGet(block_fifo_t
*) VLC_USED
;
480 * Peeks the first block in the FIFO.
482 * @warning This function leaves the block in the FIFO.
483 * You need to protect against concurrent threads who could dequeue the block.
484 * Preferably, there should be only one thread reading from the FIFO.
486 * @warning This function is undefined if the FIFO is empty.
488 * @return a valid block.
490 VLC_API block_t
*block_FifoShow(block_fifo_t
*);
492 size_t block_FifoSize(block_fifo_t
*) VLC_USED VLC_DEPRECATED
;
493 VLC_API
size_t block_FifoCount(block_fifo_t
*) VLC_USED VLC_DEPRECATED
;
495 typedef struct block_fifo_t vlc_fifo_t
;
498 * Locks a block FIFO.
500 * No more than one thread can lock the FIFO at any given
501 * time, and no other thread can modify the FIFO while it is locked.
502 * vlc_fifo_Unlock() releases the lock.
504 * @note If the FIFO is already locked by another thread, this function waits.
505 * This function is not a cancellation point.
507 * @warning Recursively locking a single FIFO is undefined. Locking more than
508 * one FIFO at a time may lead to lock inversion; mind the locking order.
510 VLC_API
void vlc_fifo_Lock(vlc_fifo_t
*);
513 * Unlocks a block FIFO.
515 * The calling thread must have locked the FIFO previously with
516 * vlc_fifo_Lock(). Otherwise, the behaviour is undefined.
518 * @note This function is not a cancellation point.
520 VLC_API
void vlc_fifo_Unlock(vlc_fifo_t
*);
523 * Wakes up one thread waiting on the FIFO, if any.
525 * @note This function is not a cancellation point.
527 * @warning For race-free operations, the FIFO should be locked by the calling
528 * thread. The function can be called on a unlocked FIFO however.
530 VLC_API
void vlc_fifo_Signal(vlc_fifo_t
*);
535 * Atomically unlocks the FIFO and waits until one thread signals the FIFO,
536 * then locks the FIFO again. A signal can be sent by queueing a block to the
537 * previously empty FIFO or by calling vlc_fifo_Signal() directly.
538 * This function may also return spuriously at any moment.
540 * @note This function is a cancellation point. In case of cancellation, the
541 * the FIFO will be locked before cancellation cleanup handlers are processed.
543 VLC_API
void vlc_fifo_Wait(vlc_fifo_t
*);
545 VLC_API
void vlc_fifo_WaitCond(vlc_fifo_t
*, vlc_cond_t
*);
548 * Timed variant of vlc_fifo_WaitCond().
550 * Atomically unlocks the FIFO and waits until one thread signals the FIFO up
551 * to a certain date, then locks the FIFO again. See vlc_fifo_Wait().
553 int vlc_fifo_TimedWaitCond(vlc_fifo_t
*, vlc_cond_t
*, vlc_tick_t
);
556 * Queues a linked-list of blocks into a locked FIFO.
558 * @param block the head of the list of blocks
559 * (if NULL, this function has no effects)
561 * @note This function is not a cancellation point.
563 * @warning The FIFO must be locked by the calling thread using
564 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
566 VLC_API
void vlc_fifo_QueueUnlocked(vlc_fifo_t
*, block_t
*);
569 * Dequeues the first block from a locked FIFO, if any.
571 * @note This function is not a cancellation point.
573 * @warning The FIFO must be locked by the calling thread using
574 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
576 * @return the first block in the FIFO or NULL if the FIFO is empty
578 VLC_API block_t
*vlc_fifo_DequeueUnlocked(vlc_fifo_t
*) VLC_USED
;
581 * Dequeues the all blocks from a locked FIFO.
583 * This is equivalent to calling vlc_fifo_DequeueUnlocked() repeatedly until
584 * the FIFO is emptied, but this function is much faster.
586 * @note This function is not a cancellation point.
588 * @warning The FIFO must be locked by the calling thread using
589 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
591 * @return a linked-list of all blocks in the FIFO (possibly NULL)
593 VLC_API block_t
*vlc_fifo_DequeueAllUnlocked(vlc_fifo_t
*) VLC_USED
;
596 * Counts blocks in a FIFO.
598 * Checks how many blocks are queued in a locked FIFO.
600 * @note This function is not cancellation point.
602 * @warning The FIFO must be locked by the calling thread using
603 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
605 * @return the number of blocks in the FIFO (zero if it is empty)
607 VLC_API
size_t vlc_fifo_GetCount(const vlc_fifo_t
*) VLC_USED
;
610 * Counts bytes in a FIFO.
612 * Checks how many bytes are queued in a locked FIFO.
614 * @note This function is not cancellation point.
616 * @warning The FIFO must be locked by the calling thread using
617 * vlc_fifo_Lock(). Otherwise behaviour is undefined.
619 * @return the total number of bytes
621 * @note Zero bytes does not necessarily mean that the FIFO is empty since
622 * a block could contain zero bytes. Use vlc_fifo_GetCount() to determine if
625 VLC_API
size_t vlc_fifo_GetBytes(const vlc_fifo_t
*) VLC_USED
;
627 VLC_USED
static inline bool vlc_fifo_IsEmpty(const vlc_fifo_t
*fifo
)
629 return vlc_fifo_GetCount(fifo
) == 0;
632 static inline void vlc_fifo_Cleanup(void *fifo
)
634 vlc_fifo_Unlock((vlc_fifo_t
*)fifo
);
636 #define vlc_fifo_CleanupPush(fifo) vlc_cleanup_push(vlc_fifo_Cleanup, fifo)
642 #endif /* VLC_BLOCK_H */