[vlc-commits] [Git][videolan/vlc][master] 2 commits: vlc_block: Fix typo in documentation
Hugo Beauzée-Luyssen (@chouquette)
gitlab at videolan.org
Sat Nov 6 10:32:58 UTC 2021
Hugo Beauzée-Luyssen pushed to branch master at VideoLAN / VLC
Commits:
7e20b505 by Marvin Scholz at 2021-11-06T10:17:59+00:00
vlc_block: Fix typo in documentation
The function does _not_ copy the data.
- - - - -
06a222e3 by Marvin Scholz at 2021-11-06T10:17:59+00:00
vlc_block: Properly document the block chain helpers
- - - - -
1 changed file:
- include/vlc_block.h
Changes:
=====================================
include/vlc_block.h
=====================================
@@ -136,7 +136,7 @@ struct block_t
* Initializes a custom block.
*
* This function initialize a block of timed data allocated by custom means.
- * This allows passing data with copying even if the data has been allocated
+ * This allows passing data without copying even if the data has been allocated
* with unusual means or outside of LibVLC.
*
* Normally, blocks are allocated and initialized by block_Alloc() instead.
@@ -317,18 +317,29 @@ static inline void block_Cleanup (void *block)
* @{
*/
-/****************************************************************************
- * Chains of blocks functions helper
- ****************************************************************************
- * - block_ChainAppend : append a block to the last block of a chain. Try to
- * avoid using with a lot of data as it's really slow, prefer
- * block_ChainLastAppend, p_block can be NULL
- * - 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
- * - block_ChainGather : gather a chain, free it and return one block.
- ****************************************************************************/
+/**
+ * Appends a @ref block_t to the chain
+ *
+ * The given block is appended to the last block of the given chain.
+ *
+ * @attention
+ * Using this function on long chains or repeatedly calling it
+ * to append a lot of blocks can be slow, as it has to iterate the
+ * whole chain to append the block.
+ * In these cases @ref block_ChainLastAppend should be used.
+ *
+ * @param pp_list Pointer to the block_t chain
+ * @param p_block The block_t to append (can be NULL)
+ *
+ * @see block_ChainLastAppend()
+ *
+ * Example:
+ * @code{.c}
+ * block_t *p_chain = NULL;
+ *
+ * block_ChainAppend(&p_chain, p_block);
+ * @endcode
+ */
static inline void block_ChainAppend( block_t **pp_list, block_t *p_block )
{
if( *pp_list == NULL )
@@ -344,6 +355,26 @@ static inline void block_ChainAppend( block_t **pp_list, block_t *p_block )
}
}
+/**
+ * Appends a @ref block_t to the last block pointer and update it
+ *
+ * Uses a pointer over a pointer to p_next of the last block of the block chain
+ * to append a block at the end of the chain and updates the pointer to the new
+ * last block's @c p_next. If the appended block is itself a chain, it is iterated
+ * till the end to correctly update @c ppp_last.
+ *
+ * @param[in,out] ppp_last Pointer to pointer to the end of the chain
+ * (The block_t::p_next of the last block_t in the chain)
+ * @param p_block The block_t to append
+ *
+ * Example:
+ * @code{.c}
+ * block_t *p_block = NULL;
+ * block_t **pp_block_last = &p_block;
+ *
+ * block_ChainLastAppend(&pp_block_last, p_other_block);
+ * @endcode
+ */
static inline void block_ChainLastAppend( block_t ***ppp_last, block_t *p_block )
{
block_t *p_last = p_block;
@@ -354,6 +385,16 @@ static inline void block_ChainLastAppend( block_t ***ppp_last, block_t *p_block
*ppp_last = &p_last->p_next;
}
+/**
+ * Releases a chain of blocks
+ *
+ * The block pointed to by p_block and all following blocks in the
+ * chain are released.
+ *
+ * @param p_block Pointer to first block_t of the chain to release
+ *
+ * @see block_Release()
+ */
static inline void block_ChainRelease( block_t *p_block )
{
while( p_block )
@@ -364,6 +405,20 @@ static inline void block_ChainRelease( block_t *p_block )
}
}
+/**
+ * Extracts data from a chain of blocks
+ *
+ * Copies the specified amount of data from the chain into the given buffer.
+ * If the data in the chain is less than the maximum amount given, the remainder
+ * of the buffer is not modified.
+ *
+ * @param p_list Pointer to the first block_t of the chain to copy from
+ * @param[out] p_data Destination buffer to copy the data to
+ * @param i_max Number of bytes to copy
+ * @return Number of bytes actually copied
+ *
+ * @see block_ChainGather()
+ */
static size_t block_ChainExtract( block_t *p_list, void *p_data, size_t i_max )
{
size_t i_total = 0;
@@ -382,6 +437,17 @@ static size_t block_ChainExtract( block_t *p_list, void *p_data, size_t i_max )
return i_total;
}
+/**
+ * Retrives chain properties
+ *
+ * Can be used to retrieve count of blocks, number of bytes and the duration
+ * of the chain.
+ *
+ * @param p_list Pointer to the first block_t of the chain
+ * @param[out] pi_count Pointer to count of blocks in the chain (may be NULL)
+ * @param[out] pi_size Pointer to number of bytes in the chain (may be NULL)
+ * @param[out] pi_length Pointer to length (duration) of the chain (may be NULL)
+ */
static inline void block_ChainProperties( block_t *p_list, int *pi_count, size_t *pi_size, vlc_tick_t *pi_length )
{
size_t i_size = 0;
@@ -405,6 +471,20 @@ static inline void block_ChainProperties( block_t *p_list, int *pi_count, size_t
*pi_count = i_count;
}
+/**
+ * Gathers a chain into a single block_t
+ *
+ * All blocks in the chain are gathered into a single block_t and the
+ * original chain is released.
+ *
+ * @param p_list Pointer to the first block_t of the chain to gather
+ * @return Returns a pointer to a new block_t or NULL if the block can not
+ * be allocated, in which case the original chain is not released.
+ * If the chain pointed to by p_list is already gathered, a pointer
+ * to it is returned and no new block will be allocated.
+ *
+ * @see block_ChainExtract()
+ */
static inline block_t *block_ChainGather( block_t *p_list )
{
size_t i_total = 0;
View it on GitLab: https://code.videolan.org/videolan/vlc/-/compare/aa6509f84a7e9a474bf67f601b69658e25691d41...06a222e3b6366f391b1183641e3c88627ac16242
--
View it on GitLab: https://code.videolan.org/videolan/vlc/-/compare/aa6509f84a7e9a474bf67f601b69658e25691d41...06a222e3b6366f391b1183641e3c88627ac16242
You're receiving this email because of your account on code.videolan.org.
More information about the vlc-commits
mailing list