vlc_block.h 19.6 KB
 Laurent Aimar committed Aug 23, 2003 1 /*****************************************************************************  Gildas Bazin committed Sep 02, 2003 2  * vlc_block.h: Data blocks management functions  Laurent Aimar committed Aug 23, 2003 3  *****************************************************************************  Jean-Baptiste Kempf committed Nov 27, 2011 4  * Copyright (C) 2003 VLC authors and VideoLAN  Laurent Aimar committed Mar 11, 2004 5  * $Id$  Laurent Aimar committed Aug 23, 2003 6 7 8  * * Authors: Laurent Aimar *  Jean-Baptiste Kempf committed Nov 27, 2011 9 10 11  * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation; either version 2.1 of the License, or  Laurent Aimar committed Aug 23, 2003 12 13 14 15  * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of  Jean-Baptiste Kempf committed Nov 27, 2011 16 17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details.  Laurent Aimar committed Aug 23, 2003 18  *  Jean-Baptiste Kempf committed Nov 27, 2011 19 20 21  * You should have received a copy of the GNU Lesser General Public License * along with this program; if not, write to the Free Software Foundation, * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.  Laurent Aimar committed Aug 23, 2003 22 23  *****************************************************************************/  Rémi Denis-Courmont committed Aug 11, 2008 24 25 #ifndef VLC_BLOCK_H #define VLC_BLOCK_H 1  Laurent Aimar committed Aug 23, 2003 26   Jean-Paul Saman committed Aug 13, 2008 27 /**  Rémi Denis-Courmont committed Oct 26, 2016 28 29 30 31 32 33 34 35 36 37  * \defgroup block Data blocks * \ingroup input * * Blocks of binary data. * * @ref block_t is a generic structure to represent a binary blob within VLC. * The primary goal of the structure is to avoid memory copying as data is * passed around. It is notably used between the \ref demux, the packetizer * (if present) and the \ref decoder, and for audio, between the \ref decoder, * the audio filters, and the \ref audio_output.  Jean-Paul Saman committed Aug 13, 2008 38  *  Rémi Denis-Courmont committed Oct 26, 2016 39 40 41  * @{ * \file * Data block definition and functions  Jean-Paul Saman committed Aug 13, 2008 42 43  */  KO Myung-Hun committed Feb 04, 2012 44 45 #include /* for ssize_t */  Laurent Aimar committed Jul 05, 2004 46 47 48 49 50 51 /**************************************************************************** * block: **************************************************************************** * - i_flags may not always be set (ie could be 0, even for a key frame * it depends where you receive the buffer (before/after a packetizer * and the demux/packetizer implementations.  Laurent Aimar committed Apr 25, 2009 52  * - i_dts/i_pts could be VLC_TS_INVALID, it means no pts/dts  Laurent Aimar committed Jul 05, 2004 53 54 55 56 57 58 59 60 61  * - i_length: length in microseond of the packet, can be null except in the * sout where it is mandatory. * * - i_buffer number of valid data pointed by p_buffer * you can freely decrease it but never increase it yourself * (use block_Realloc) * - p_buffer: pointer over datas. You should never overwrite it, you can * only incremment it to skip datas, in others cases use block_Realloc * (don't duplicate yourself in a bigger buffer, block_Realloc is  Jean-Paul Saman committed Jul 07, 2010 62  * optimised for preheader/postdatas increase)  Laurent Aimar committed Jul 05, 2004 63  ****************************************************************************/  Laurent Aimar committed Aug 23, 2003 64   Ilkka Ollakka committed Nov 05, 2015 65 66 /** The content doesn't follow the last block, possible some blocks in between * have been lost */  Laurent Aimar committed Feb 25, 2004 67 #define BLOCK_FLAG_DISCONTINUITY 0x0001  Sigmund Augdal Helberg committed Apr 15, 2004 68 /** Intra frame */  Laurent Aimar committed Feb 25, 2004 69 #define BLOCK_FLAG_TYPE_I 0x0002  Sigmund Augdal Helberg committed Apr 15, 2004 70 /** Inter frame with backward reference only */  Laurent Aimar committed Feb 25, 2004 71 #define BLOCK_FLAG_TYPE_P 0x0004  Sigmund Augdal Helberg committed Apr 15, 2004 72 /** Inter frame with backward and forward reference */  Laurent Aimar committed Feb 25, 2004 73 #define BLOCK_FLAG_TYPE_B 0x0008  Sigmund Augdal Helberg committed Apr 15, 2004 74 /** For inter frame when you don't know the real type */  Laurent Aimar committed Feb 25, 2004 75 #define BLOCK_FLAG_TYPE_PB 0x0010  Antoine Cellerier committed Nov 06, 2006 76 /** Warn that this block is a header one */  Laurent Aimar committed Mar 11, 2004 77 #define BLOCK_FLAG_HEADER 0x0020  Laurent Aimar committed Aug 21, 2008 78 /** This block contains the last part of a sequence */  François Cartegnie committed Apr 27, 2017 79 #define BLOCK_FLAG_END_OF_SEQUENCE 0x0040  Christophe Massiot committed Jan 07, 2005 80 /** This block contains a clock reference */  François Cartegnie committed Apr 27, 2017 81 #define BLOCK_FLAG_CLOCK 0x0080  Christophe Massiot committed Jan 07, 2005 82 /** This block is scrambled */  François Cartegnie committed Apr 27, 2017 83 #define BLOCK_FLAG_SCRAMBLED 0x0100  Laurent Aimar committed Feb 21, 2005 84 /** This block has to be decoded but not be displayed */  François Cartegnie committed Apr 27, 2017 85 #define BLOCK_FLAG_PREROLL 0x0200  Laurent Aimar committed Feb 21, 2005 86 /** This block is corrupted and/or there is data loss */  François Cartegnie committed Apr 27, 2017 87 #define BLOCK_FLAG_CORRUPTED 0x0400  François Cartegnie committed Apr 27, 2017 88 /** This block contains an interlaced picture with top field stored first */  François Cartegnie committed Apr 27, 2017 89 #define BLOCK_FLAG_TOP_FIELD_FIRST 0x0800  François Cartegnie committed Apr 27, 2017 90 /** This block contains an interlaced picture with bottom field stored first */  François Cartegnie committed Apr 27, 2017 91 #define BLOCK_FLAG_BOTTOM_FIELD_FIRST 0x1000  François Cartegnie committed Apr 27, 2017 92 /** This block contains a single field from interlaced picture. */  François Cartegnie committed Apr 27, 2017 93 #define BLOCK_FLAG_SINGLE_FIELD 0x2000  Antoine Cellerier committed Oct 03, 2009 94 95 96  /** This block contains an interlaced picture */ #define BLOCK_FLAG_INTERLACED_MASK \  François Cartegnie committed Apr 27, 2017 97  (BLOCK_FLAG_TOP_FIELD_FIRST|BLOCK_FLAG_BOTTOM_FIELD_FIRST|BLOCK_FLAG_SINGLE_FIELD)  Laurent Aimar committed Mar 11, 2004 98   Laurent Aimar committed Aug 27, 2008 99 100 101 #define BLOCK_FLAG_TYPE_MASK \ (BLOCK_FLAG_TYPE_I|BLOCK_FLAG_TYPE_P|BLOCK_FLAG_TYPE_B|BLOCK_FLAG_TYPE_PB)  Laurent Aimar committed Sep 18, 2008 102 103 104 105 106 107 108 /* These are for input core private usage only */ #define BLOCK_FLAG_CORE_PRIVATE_MASK 0x00ff0000 #define BLOCK_FLAG_CORE_PRIVATE_SHIFT 16 /* These are for module private usage only */ #define BLOCK_FLAG_PRIVATE_MASK 0xff000000 #define BLOCK_FLAG_PRIVATE_SHIFT 24  Laurent Aimar committed Feb 25, 2004 109   Rémi Denis-Courmont committed Nov 26, 2007 110 111 typedef void (*block_free_t) (block_t *);  Laurent Aimar committed Aug 23, 2003 112 113 struct block_t {  Rémi Denis-Courmont committed Apr 12, 2012 114  block_t *p_next;  Laurent Aimar committed Aug 23, 2003 115   Rémi Denis-Courmont committed Apr 12, 2012 116 117 118 119  uint8_t *p_buffer; /**< Payload start */ size_t i_buffer; /**< Payload length */ uint8_t *p_start; /**< Buffer start */ size_t i_size; /**< Buffer total size */  Rémi Denis-Courmont committed Aug 29, 2011 120   Laurent Aimar committed Feb 25, 2004 121  uint32_t i_flags;  Rémi Denis-Courmont committed Aug 29, 2011 122  unsigned i_nb_samples; /* Used for audio */  Laurent Aimar committed Feb 25, 2004 123   Laurent Aimar committed Aug 23, 2003 124 125  mtime_t i_pts; mtime_t i_dts;  Gildas Bazin committed Oct 27, 2003 126  mtime_t i_length;  Laurent Aimar committed Aug 23, 2003 127   Rémi Denis-Courmont committed Nov 26, 2007 128 129  /* Rudimentary support for overloading block (de)allocation. */ block_free_t pf_release;  Laurent Aimar committed Aug 23, 2003 130 131 };  Rémi Denis-Courmont committed May 07, 2011 132 VLC_API void block_Init( block_t *, void *, size_t );  Rémi Denis-Courmont committed Oct 26, 2016 133 134 135 136 137 138 139 140 141 142 143 144  /** * Allocates a block. * * Creates a new block with the requested size. * The block must be released with block_Release(). * * @param size size in bytes (possibly zero) * @return the created block, or NULL on memory error. */ VLC_API block_t *block_Alloc(size_t size) VLC_USED VLC_MALLOC;  Thomas Guillem committed Mar 29, 2017 145 VLC_API block_t *block_TryRealloc(block_t *, ssize_t pre, size_t body) VLC_USED;  Rémi Denis-Courmont committed Oct 26, 2016 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160  /** * Reallocates a block. * * This function expands, shrinks or moves a data block. * In many cases, this function can return without any memory allocation by * reusing spare buffer space. Otherwise, a new block is created and data is * copied. * * @param pre count of bytes to prepend if positive, * count of leading bytes to discard if negative * @param body new bytes size of the block * * @return the reallocated block on succes, NULL on error. *  Sebastian Ramacher committed Sep 27, 2017 161  * @note Skipping leading bytes can be achieved directly by subtracting from  Rémi Denis-Courmont committed Oct 26, 2016 162  * block_t.i_buffer and adding block_t.p_buffer.  Sebastian Ramacher committed Sep 27, 2017 163  * @note Discard trailing bytes can be achieved directly by subtracting from  Rémi Denis-Courmont committed Oct 26, 2016 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185  * block_t.i_buffer. * @note On error, the block is discarded. * To avoid that, use block_TryRealloc() instead. */ VLC_API block_t *block_Realloc(block_t *, ssize_t pre, size_t body) VLC_USED; /** * Releases a block. * * This function works for any @ref block_t block, regardless of the way it was * allocated. * * @note * If the block is in a chain, this function does not release any * subsequent block in the chain. Use block_ChainRelease() for that purpose. * * @param block block to release (cannot be NULL) */ static inline void block_Release(block_t *block) { block->pf_release(block); }  Rémi Denis-Courmont committed Nov 26, 2007 186   Rafaël Carré committed Dec 25, 2012 187 188 189 190 191 192 193 194 195 static inline void block_CopyProperties( block_t *dst, block_t *src ) { dst->i_flags = src->i_flags; dst->i_nb_samples = src->i_nb_samples; dst->i_dts = src->i_dts; dst->i_pts = src->i_pts; dst->i_length = src->i_length; }  Rémi Denis-Courmont committed Oct 26, 2016 196 197 198 199 200 201 202 /** * Duplicates a block. * * Creates a writeable duplicate of a block. * * @return the duplicate on success, NULL on error. */  Rémi Denis-Courmont committed May 07, 2011 203 VLC_USED  Laurent Aimar committed Jul 05, 2004 204 static inline block_t *block_Duplicate( block_t *p_block )  Laurent Aimar committed Aug 23, 2003 205 {  Rémi Denis-Courmont committed Jun 11, 2008 206  block_t *p_dup = block_Alloc( p_block->i_buffer );  Rémi Denis-Courmont committed Jan 19, 2007 207 208  if( p_dup == NULL ) return NULL;  Laurent Aimar committed Aug 23, 2003 209   Rafaël Carré committed Dec 25, 2012 210  block_CopyProperties( p_dup, p_block );  Rémi Denis-Courmont committed Jan 19, 2007 211  memcpy( p_dup->p_buffer, p_block->p_buffer, p_block->i_buffer );  Laurent Aimar committed Aug 23, 2003 212   Laurent Aimar committed Jul 05, 2004 213 214  return p_dup; }  Jean-Paul Saman committed Aug 11, 2008 215   Rémi Denis-Courmont committed Oct 26, 2016 216 217 218 219 220 221 222 223 224 225 226 227 228 229 /** * Wraps heap in a block. * * Creates a @ref block_t out of an existing heap allocation. * This is provided by LibVLC so that manually heap-allocated blocks can safely * be deallocated even after the origin plugin has been unloaded from memory. * * When block_Release() is called, VLC will free() the specified pointer. * * @param addr base address of the heap allocation (will be free()'d) * @param length bytes length of the heap allocation * @return NULL in case of error (ptr free()'d in that case), or a valid * block_t pointer. */  Rémi Denis-Courmont committed Sep 29, 2012 230 VLC_API block_t *block_heap_Alloc(void *, size_t) VLC_USED VLC_MALLOC;  Rémi Denis-Courmont committed Oct 26, 2016 231 232 233 234 235 236 237 238 239 240 241 242 243  /** * Wraps a memory mapping in a block * * Creates a @ref block_t from a virtual address memory mapping (mmap). * This is provided by LibVLC so that mmap blocks can safely be deallocated * even after the allocating plugin has been unloaded from memory. * * @param addr base address of the mapping (as returned by mmap) * @param length length (bytes) of the mapping (as passed to mmap) * @return NULL if addr is MAP_FAILED, or an error occurred (in the later * case, munmap(addr, length) is invoked before returning). */  Rémi Denis-Courmont committed Sep 29, 2012 244 VLC_API block_t *block_mmap_Alloc(void *addr, size_t length) VLC_USED VLC_MALLOC;  Rémi Denis-Courmont committed Oct 26, 2016 245 246 247 248 249 250 251 252 253 254 255 256 257  /** * Wraps a System V memory segment in a block * * Creates a @ref block_t from a System V shared memory segment (shmget()). * This is provided by LibVLC so that segments can safely be deallocated * even after the allocating plugin has been unloaded from memory. * * @param addr base address of the segment (as returned by shmat()) * @param length length (bytes) of the segment (as passed to shmget()) * @return NULL if an error occurred (in that case, shmdt(addr) is invoked * before returning NULL). */  Rémi Denis-Courmont committed Jan 12, 2013 258 VLC_API block_t * block_shm_Alloc(void *addr, size_t length) VLC_USED VLC_MALLOC;  Rémi Denis-Courmont committed Oct 26, 2016 259 260 261 262 263 264 265 266 267 268 269 270 271  /** * Maps a file handle in memory. * * Loads a file into a block of memory through a file descriptor. * If possible a private file mapping is created. Otherwise, the file is read * normally. This function is a cancellation point. * * @note On 32-bits platforms, * this function will not work for very large files, * due to memory space constraints. * * @param fd file descriptor to load from  Rémi Denis-Courmont committed Oct 26, 2016 272 273  * @param write If true, request a read/write private mapping. * If false, request a read-only potentially shared mapping.  Rémi Denis-Courmont committed Oct 26, 2016 274 275 276 277  * * @return a new block with the file content at p_buffer, and file length at * i_buffer (release it with block_Release()), or NULL upon error (see errno). */  Rémi Denis-Courmont committed Oct 26, 2016 278 VLC_API block_t *block_File(int fd, bool write) VLC_USED VLC_MALLOC;  Rémi Denis-Courmont committed Oct 26, 2016 279 280 281 282 283 284  /** * Maps a file in memory. * * Loads a file into a block of memory from a path to the file. * See also block_File().  Rémi Denis-Courmont committed Oct 26, 2016 285 286 287  * * @param write If true, request a read/write private mapping. * If false, request a read-only potentially shared mapping.  Rémi Denis-Courmont committed Oct 26, 2016 288  */  Rémi Denis-Courmont committed Oct 26, 2016 289 VLC_API block_t *block_FilePath(const char *, bool write) VLC_USED VLC_MALLOC;  Rémi Denis-Courmont committed Dec 28, 2007 290   Rémi Denis-Courmont committed Aug 27, 2008 291 292 293 294 295 296 static inline void block_Cleanup (void *block) { block_Release ((block_t *)block); } #define block_cleanup_push( block ) vlc_cleanup_push (block_Cleanup, block)  Rémi Denis-Courmont committed Oct 26, 2016 297 298 299 300 301 /** * \defgroup block_fifo Block chain * @{ */  Laurent Aimar committed Jul 05, 2004 302 303 304 /**************************************************************************** * Chains of blocks functions helper ****************************************************************************  Jean-Paul Saman committed Aug 11, 2008 305  * - block_ChainAppend : append a block to the last block of a chain. Try to  Laurent Aimar committed Jul 05, 2004 306  * avoid using with a lot of data as it's really slow, prefer  307  * block_ChainLastAppend, p_block can be NULL  Laurent Aimar committed Jul 05, 2004 308 309 310 311  * - block_ChainLastAppend : use a pointer over a pointer to the next blocks, * and update it. * - block_ChainRelease : release a chain of block * - block_ChainExtract : extract data from a chain, return real bytes counts  Jean-Paul Saman committed Aug 11, 2008 312  * - block_ChainGather : gather a chain, free it and return one block.  Laurent Aimar committed Jul 05, 2004 313 314  ****************************************************************************/ static inline void block_ChainAppend( block_t **pp_list, block_t *p_block )  Laurent Aimar committed Aug 23, 2003 315 {  Laurent Aimar committed Jul 05, 2004 316 317 318 319 320 321 322 323 324 325 326  if( *pp_list == NULL ) { *pp_list = p_block; } else { block_t *p = *pp_list; while( p->p_next ) p = p->p_next; p->p_next = p_block; }  Laurent Aimar committed Aug 23, 2003 327 }  Laurent Aimar committed Jul 05, 2004 328   Jean-Paul Saman committed Aug 11, 2008 329 static inline void block_ChainLastAppend( block_t ***ppp_last, block_t *p_block )  Laurent Aimar committed Aug 23, 2003 330 {  Laurent Aimar committed Jul 05, 2004 331 332 333 334 335 336  block_t *p_last = p_block; **ppp_last = p_block; while( p_last->p_next ) p_last = p_last->p_next; *ppp_last = &p_last->p_next;  Laurent Aimar committed Aug 23, 2003 337 }  Laurent Aimar committed Jul 05, 2004 338 339  static inline void block_ChainRelease( block_t *p_block )  Laurent Aimar committed Aug 23, 2003 340 {  Laurent Aimar committed Jul 05, 2004 341 342 343 344 345 346 347  while( p_block ) { block_t *p_next = p_block->p_next; block_Release( p_block ); p_block = p_next; } }  Rémi Denis-Courmont committed Nov 26, 2007 348 349  static size_t block_ChainExtract( block_t *p_list, void *p_data, size_t i_max )  Laurent Aimar committed Jul 05, 2004 350 {  Rémi Denis-Courmont committed Nov 26, 2007 351  size_t i_total = 0;  Laurent Aimar committed Jul 05, 2004 352 353  uint8_t *p = (uint8_t*)p_data;  Rémi Denis-Courmont committed Nov 26, 2007 354  while( p_list && i_max )  Laurent Aimar committed Jul 05, 2004 355  {  Rémi Denis-Courmont committed Nov 26, 2007 356 357 358 359 360 361 362  size_t i_copy = __MIN( i_max, p_list->i_buffer ); memcpy( p, p_list->p_buffer, i_copy ); i_max -= i_copy; i_total += i_copy; p += i_copy; p_list = p_list->p_next;  Laurent Aimar committed Jul 05, 2004 363 364  } return i_total;  Laurent Aimar committed Aug 23, 2003 365 }  Laurent Aimar committed Jul 05, 2004 366   Laurent Aimar committed Aug 26, 2008 367 368 369 370 static inline void block_ChainProperties( block_t *p_list, int *pi_count, size_t *pi_size, mtime_t *pi_length ) { size_t i_size = 0; mtime_t i_length = 0;  Rémi Duraffort committed Oct 01, 2008 371  int i_count = 0;  Laurent Aimar committed Aug 26, 2008 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389  while( p_list ) { i_size += p_list->i_buffer; i_length += p_list->i_length; i_count++; p_list = p_list->p_next; } if( pi_size ) *pi_size = i_size; if( pi_length ) *pi_length = i_length; if( pi_count ) *pi_count = i_count; }  Laurent Aimar committed Jul 05, 2004 390 391 static inline block_t *block_ChainGather( block_t *p_list ) {  Rémi Denis-Courmont committed Nov 26, 2007 392  size_t i_total = 0;  Christophe Massiot committed Apr 08, 2005 393  mtime_t i_length = 0;  Laurent Aimar committed Aug 26, 2008 394  block_t *g;  Laurent Aimar committed Jul 05, 2004 395 396 397 398  if( p_list->p_next == NULL ) return p_list; /* Already gathered */  Laurent Aimar committed Aug 26, 2008 399  block_ChainProperties( p_list, NULL, &i_total, &i_length );  Laurent Aimar committed Jul 05, 2004 400   Rémi Denis-Courmont committed Jun 11, 2008 401  g = block_Alloc( i_total );  François Cartegnie committed Mar 17, 2015 402 403  if( !g ) return NULL;  Laurent Aimar committed Jul 05, 2004 404 405 406 407 408  block_ChainExtract( p_list, g->p_buffer, g->i_buffer ); g->i_flags = p_list->i_flags; g->i_pts = p_list->i_pts; g->i_dts = p_list->i_dts;  Christophe Massiot committed Apr 08, 2005 409  g->i_length = i_length;  Laurent Aimar committed Jul 05, 2004 410 411 412 413 414 415  /* free p_list */ block_ChainRelease( p_list ); return g; }  Rémi Denis-Courmont committed Oct 26, 2016 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 /** * @} * \defgroup fifo Block FIFO * Thread-safe block queue functions * @{ */ /** * Creates a thread-safe FIFO queue of blocks. * * See also block_FifoPut() and block_FifoGet(). * The created queue must be released with block_FifoRelease(). * * @return the FIFO or NULL on memory error */ VLC_API block_fifo_t *block_FifoNew(void) VLC_USED VLC_MALLOC; /** * Destroys a FIFO created by block_FifoNew(). * * @note Any queued blocks are also destroyed. * @warning No other threads may be using the FIFO when this function is * called. Otherwise, undefined behaviour will occur. */ VLC_API void block_FifoRelease(block_fifo_t *);  Laurent Aimar committed Jul 05, 2004 441   Rémi Denis-Courmont committed Oct 26, 2016 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 /** * Clears all blocks in a FIFO. */ VLC_API void block_FifoEmpty(block_fifo_t *); /** * Immediately queue one block at the end of a FIFO. * * @param fifo queue * @param block head of a block list to queue (may be NULL) */ VLC_API void block_FifoPut(block_fifo_t *fifo, block_t *block); /** * Dequeue the first block from the FIFO. If necessary, wait until there is * one block in the queue. This function is (always) cancellation point. * * @return a valid block */ VLC_API block_t *block_FifoGet(block_fifo_t *) VLC_USED; /** * 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. * * @warning This function is undefined if the FIFO is empty. * * @return a valid block. */ VLC_API block_t *block_FifoShow(block_fifo_t *); size_t block_FifoSize(block_fifo_t *) VLC_USED VLC_DEPRECATED; VLC_API size_t block_FifoCount(block_fifo_t *) VLC_USED VLC_DEPRECATED;  Laurent Aimar committed Aug 23, 2003 478   Rémi Denis-Courmont committed Mar 19, 2015 479 480 typedef struct block_fifo_t vlc_fifo_t;  Rémi Denis-Courmont committed Oct 26, 2016 481 482 483 484 485 486 487 488 489 490 491 492 493 /** * 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. */  Rémi Denis-Courmont committed Mar 19, 2015 494 VLC_API void vlc_fifo_Lock(vlc_fifo_t *);  Rémi Denis-Courmont committed Oct 26, 2016 495 496 497 498 499 500 501 502 503  /** * 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. */  Rémi Denis-Courmont committed Mar 19, 2015 504 VLC_API void vlc_fifo_Unlock(vlc_fifo_t *);  Rémi Denis-Courmont committed Oct 26, 2016 505 506 507 508 509 510 511 512 513  /** * 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. */  Rémi Denis-Courmont committed Mar 19, 2015 514 VLC_API void vlc_fifo_Signal(vlc_fifo_t *);  Rémi Denis-Courmont committed Oct 26, 2016 515 516 517 518 519 520 521 522 523 524 525 526  /** * 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. */  Rémi Denis-Courmont committed Mar 19, 2015 527 VLC_API void vlc_fifo_Wait(vlc_fifo_t *);  Rémi Denis-Courmont committed Oct 26, 2016 528   Rémi Denis-Courmont committed Mar 19, 2015 529 VLC_API void vlc_fifo_WaitCond(vlc_fifo_t *, vlc_cond_t *);  Rémi Denis-Courmont committed Oct 26, 2016 530 531 532 533 534 535 536  /** * Timed variant of vlc_fifo_WaitCond(). * * Atomically unlocks the FIFO and waits until one thread signals the FIFO up * to a certain date, then locks the FIFO again. See vlc_fifo_Wait(). */  Thomas Guillem committed Dec 05, 2015 537 int vlc_fifo_TimedWaitCond(vlc_fifo_t *, vlc_cond_t *, mtime_t);  Rémi Denis-Courmont committed Oct 26, 2016 538 539 540 541 542 543 544 545 546 547 548 549  /** * Queues a linked-list of blocks into a locked FIFO. * * @param 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. */  Rémi Denis-Courmont committed Mar 19, 2015 550 VLC_API void vlc_fifo_QueueUnlocked(vlc_fifo_t *, block_t *);  Rémi Denis-Courmont committed Oct 26, 2016 551 552 553 554 555 556 557 558 559 560 561  /** * 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. * * @return the first block in the FIFO or NULL if the FIFO is empty */  Rémi Denis-Courmont committed Mar 19, 2015 562 VLC_API block_t *vlc_fifo_DequeueUnlocked(vlc_fifo_t *) VLC_USED;  Rémi Denis-Courmont committed Oct 26, 2016 563 564 565 566 567 568 569 570 571 572 573 574 575 576  /** * 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. * * @return a linked-list of all blocks in the FIFO (possibly NULL) */  Rémi Denis-Courmont committed Mar 19, 2015 577 VLC_API block_t *vlc_fifo_DequeueAllUnlocked(vlc_fifo_t *) VLC_USED;  Rémi Denis-Courmont committed Oct 26, 2016 578 579 580 581 582 583 584 585 586 587 588 589 590  /** * 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. * * @return the number of blocks in the FIFO (zero if it is empty) */  Rémi Denis-Courmont committed Mar 19, 2015 591 VLC_API size_t vlc_fifo_GetCount(const vlc_fifo_t *) VLC_USED;  Rémi Denis-Courmont committed Oct 26, 2016 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608  /** * 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. * * @return 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. */  Rémi Denis-Courmont committed Mar 19, 2015 609 610 611 612 613 614 615 616 617 618 619 620 621 VLC_API size_t vlc_fifo_GetBytes(const vlc_fifo_t *) VLC_USED; VLC_USED static inline bool vlc_fifo_IsEmpty(const vlc_fifo_t *fifo) { return vlc_fifo_GetCount(fifo) == 0; } static inline void vlc_fifo_Cleanup(void *fifo) { vlc_fifo_Unlock((vlc_fifo_t *)fifo); } #define vlc_fifo_CleanupPush(fifo) vlc_cleanup_push(vlc_fifo_Cleanup, fifo)  Rémi Denis-Courmont committed Oct 26, 2016 622 623 624 625 /** @} */ /** @} */  Gildas Bazin committed Sep 02, 2003 626 #endif /* VLC_BLOCK_H */