LCOV - code coverage report
Current view: top level - libavutil - mem.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 5 6 83.3 %
Date: 2017-12-15 02:19:58 Functions: 1 1 100.0 %

          Line data    Source code
       1             : /*
       2             :  * copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at>
       3             :  *
       4             :  * This file is part of FFmpeg.
       5             :  *
       6             :  * FFmpeg is free software; you can redistribute it and/or
       7             :  * modify it under the terms of the GNU Lesser General Public
       8             :  * License as published by the Free Software Foundation; either
       9             :  * version 2.1 of the License, or (at your option) any later version.
      10             :  *
      11             :  * FFmpeg is distributed in the hope that it will be useful,
      12             :  * but WITHOUT ANY WARRANTY; without even the implied warranty of
      13             :  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      14             :  * Lesser General Public License for more details.
      15             :  *
      16             :  * You should have received a copy of the GNU Lesser General Public
      17             :  * License along with FFmpeg; if not, write to the Free Software
      18             :  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
      19             :  */
      20             : 
      21             : /**
      22             :  * @file
      23             :  * @ingroup lavu_mem
      24             :  * Memory handling functions
      25             :  */
      26             : 
      27             : #ifndef AVUTIL_MEM_H
      28             : #define AVUTIL_MEM_H
      29             : 
      30             : #include <limits.h>
      31             : #include <stdint.h>
      32             : 
      33             : #include "attributes.h"
      34             : #include "error.h"
      35             : #include "avutil.h"
      36             : 
      37             : /**
      38             :  * @addtogroup lavu_mem
      39             :  * Utilities for manipulating memory.
      40             :  *
      41             :  * FFmpeg has several applications of memory that are not required of a typical
      42             :  * program. For example, the computing-heavy components like video decoding and
      43             :  * encoding can be sped up significantly through the use of aligned memory.
      44             :  *
      45             :  * However, for each of FFmpeg's applications of memory, there might not be a
      46             :  * recognized or standardized API for that specific use. Memory alignment, for
      47             :  * instance, varies wildly depending on operating systems, architectures, and
      48             :  * compilers. Hence, this component of @ref libavutil is created to make
      49             :  * dealing with memory consistently possible on all platforms.
      50             :  *
      51             :  * @{
      52             :  *
      53             :  * @defgroup lavu_mem_macros Alignment Macros
      54             :  * Helper macros for declaring aligned variables.
      55             :  * @{
      56             :  */
      57             : 
      58             : /**
      59             :  * @def DECLARE_ALIGNED(n,t,v)
      60             :  * Declare a variable that is aligned in memory.
      61             :  *
      62             :  * @code{.c}
      63             :  * DECLARE_ALIGNED(16, uint16_t, aligned_int) = 42;
      64             :  * DECLARE_ALIGNED(32, uint8_t, aligned_array)[128];
      65             :  *
      66             :  * // The default-alignment equivalent would be
      67             :  * uint16_t aligned_int = 42;
      68             :  * uint8_t aligned_array[128];
      69             :  * @endcode
      70             :  *
      71             :  * @param n Minimum alignment in bytes
      72             :  * @param t Type of the variable (or array element)
      73             :  * @param v Name of the variable
      74             :  */
      75             : 
      76             : /**
      77             :  * @def DECLARE_ASM_ALIGNED(n,t,v)
      78             :  * Declare an aligned variable appropriate for use in inline assembly code.
      79             :  *
      80             :  * @code{.c}
      81             :  * DECLARE_ASM_ALIGNED(16, uint64_t, pw_08) = UINT64_C(0x0008000800080008);
      82             :  * @endcode
      83             :  *
      84             :  * @param n Minimum alignment in bytes
      85             :  * @param t Type of the variable (or array element)
      86             :  * @param v Name of the variable
      87             :  */
      88             : 
      89             : /**
      90             :  * @def DECLARE_ASM_CONST(n,t,v)
      91             :  * Declare a static constant aligned variable appropriate for use in inline
      92             :  * assembly code.
      93             :  *
      94             :  * @code{.c}
      95             :  * DECLARE_ASM_CONST(16, uint64_t, pw_08) = UINT64_C(0x0008000800080008);
      96             :  * @endcode
      97             :  *
      98             :  * @param n Minimum alignment in bytes
      99             :  * @param t Type of the variable (or array element)
     100             :  * @param v Name of the variable
     101             :  */
     102             : 
     103             : #if defined(__INTEL_COMPILER) && __INTEL_COMPILER < 1110 || defined(__SUNPRO_C)
     104             :     #define DECLARE_ALIGNED(n,t,v)      t __attribute__ ((aligned (n))) v
     105             :     #define DECLARE_ASM_ALIGNED(n,t,v)  t __attribute__ ((aligned (n))) v
     106             :     #define DECLARE_ASM_CONST(n,t,v)    const t __attribute__ ((aligned (n))) v
     107             : #elif defined(__DJGPP__)
     108             :     #define DECLARE_ALIGNED(n,t,v)      t __attribute__ ((aligned (FFMIN(n, 16)))) v
     109             :     #define DECLARE_ASM_ALIGNED(n,t,v)  t av_used __attribute__ ((aligned (FFMIN(n, 16)))) v
     110             :     #define DECLARE_ASM_CONST(n,t,v)    static const t av_used __attribute__ ((aligned (FFMIN(n, 16)))) v
     111             : #elif defined(__GNUC__) || defined(__clang__)
     112             :     #define DECLARE_ALIGNED(n,t,v)      t __attribute__ ((aligned (n))) v
     113             :     #define DECLARE_ASM_ALIGNED(n,t,v)  t av_used __attribute__ ((aligned (n))) v
     114             :     #define DECLARE_ASM_CONST(n,t,v)    static const t av_used __attribute__ ((aligned (n))) v
     115             : #elif defined(_MSC_VER)
     116             :     #define DECLARE_ALIGNED(n,t,v)      __declspec(align(n)) t v
     117             :     #define DECLARE_ASM_ALIGNED(n,t,v)  __declspec(align(n)) t v
     118             :     #define DECLARE_ASM_CONST(n,t,v)    __declspec(align(n)) static const t v
     119             : #else
     120             :     #define DECLARE_ALIGNED(n,t,v)      t v
     121             :     #define DECLARE_ASM_ALIGNED(n,t,v)  t v
     122             :     #define DECLARE_ASM_CONST(n,t,v)    static const t v
     123             : #endif
     124             : 
     125             : /**
     126             :  * @}
     127             :  */
     128             : 
     129             : /**
     130             :  * @defgroup lavu_mem_attrs Function Attributes
     131             :  * Function attributes applicable to memory handling functions.
     132             :  *
     133             :  * These function attributes can help compilers emit more useful warnings, or
     134             :  * generate better code.
     135             :  * @{
     136             :  */
     137             : 
     138             : /**
     139             :  * @def av_malloc_attrib
     140             :  * Function attribute denoting a malloc-like function.
     141             :  *
     142             :  * @see <a href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-g_t_0040code_007bmalloc_007d-function-attribute-3251">Function attribute `malloc` in GCC's documentation</a>
     143             :  */
     144             : 
     145             : #if AV_GCC_VERSION_AT_LEAST(3,1)
     146             :     #define av_malloc_attrib __attribute__((__malloc__))
     147             : #else
     148             :     #define av_malloc_attrib
     149             : #endif
     150             : 
     151             : /**
     152             :  * @def av_alloc_size(...)
     153             :  * Function attribute used on a function that allocates memory, whose size is
     154             :  * given by the specified parameter(s).
     155             :  *
     156             :  * @code{.c}
     157             :  * void *av_malloc(size_t size) av_alloc_size(1);
     158             :  * void *av_calloc(size_t nmemb, size_t size) av_alloc_size(1, 2);
     159             :  * @endcode
     160             :  *
     161             :  * @param ... One or two parameter indexes, separated by a comma
     162             :  *
     163             :  * @see <a href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-g_t_0040code_007balloc_005fsize_007d-function-attribute-3220">Function attribute `alloc_size` in GCC's documentation</a>
     164             :  */
     165             : 
     166             : #if AV_GCC_VERSION_AT_LEAST(4,3)
     167             :     #define av_alloc_size(...) __attribute__((alloc_size(__VA_ARGS__)))
     168             : #else
     169             :     #define av_alloc_size(...)
     170             : #endif
     171             : 
     172             : /**
     173             :  * @}
     174             :  */
     175             : 
     176             : /**
     177             :  * @defgroup lavu_mem_funcs Heap Management
     178             :  * Functions responsible for allocating, freeing, and copying memory.
     179             :  *
     180             :  * All memory allocation functions have a built-in upper limit of `INT_MAX`
     181             :  * bytes. This may be changed with av_max_alloc(), although exercise extreme
     182             :  * caution when doing so.
     183             :  *
     184             :  * @{
     185             :  */
     186             : 
     187             : /**
     188             :  * Allocate a memory block with alignment suitable for all memory accesses
     189             :  * (including vectors if available on the CPU).
     190             :  *
     191             :  * @param size Size in bytes for the memory block to be allocated
     192             :  * @return Pointer to the allocated block, or `NULL` if the block cannot
     193             :  *         be allocated
     194             :  * @see av_mallocz()
     195             :  */
     196             : void *av_malloc(size_t size) av_malloc_attrib av_alloc_size(1);
     197             : 
     198             : /**
     199             :  * Allocate a memory block with alignment suitable for all memory accesses
     200             :  * (including vectors if available on the CPU) and zero all the bytes of the
     201             :  * block.
     202             :  *
     203             :  * @param size Size in bytes for the memory block to be allocated
     204             :  * @return Pointer to the allocated block, or `NULL` if it cannot be allocated
     205             :  * @see av_malloc()
     206             :  */
     207             : void *av_mallocz(size_t size) av_malloc_attrib av_alloc_size(1);
     208             : 
     209             : /**
     210             :  * Allocate a memory block for an array with av_malloc().
     211             :  *
     212             :  * The allocated memory will have size `size * nmemb` bytes.
     213             :  *
     214             :  * @param nmemb Number of element
     215             :  * @param size  Size of a single element
     216             :  * @return Pointer to the allocated block, or `NULL` if the block cannot
     217             :  *         be allocated
     218             :  * @see av_malloc()
     219             :  */
     220             : av_alloc_size(1, 2) void *av_malloc_array(size_t nmemb, size_t size);
     221             : 
     222             : /**
     223             :  * Allocate a memory block for an array with av_mallocz().
     224             :  *
     225             :  * The allocated memory will have size `size * nmemb` bytes.
     226             :  *
     227             :  * @param nmemb Number of elements
     228             :  * @param size  Size of the single element
     229             :  * @return Pointer to the allocated block, or `NULL` if the block cannot
     230             :  *         be allocated
     231             :  *
     232             :  * @see av_mallocz()
     233             :  * @see av_malloc_array()
     234             :  */
     235             : av_alloc_size(1, 2) void *av_mallocz_array(size_t nmemb, size_t size);
     236             : 
     237             : /**
     238             :  * Non-inlined equivalent of av_mallocz_array().
     239             :  *
     240             :  * Created for symmetry with the calloc() C function.
     241             :  */
     242             : void *av_calloc(size_t nmemb, size_t size) av_malloc_attrib;
     243             : 
     244             : /**
     245             :  * Allocate, reallocate, or free a block of memory.
     246             :  *
     247             :  * If `ptr` is `NULL` and `size` > 0, allocate a new block. If `size` is
     248             :  * zero, free the memory block pointed to by `ptr`. Otherwise, expand or
     249             :  * shrink that block of memory according to `size`.
     250             :  *
     251             :  * @param ptr  Pointer to a memory block already allocated with
     252             :  *             av_realloc() or `NULL`
     253             :  * @param size Size in bytes of the memory block to be allocated or
     254             :  *             reallocated
     255             :  *
     256             :  * @return Pointer to a newly-reallocated block or `NULL` if the block
     257             :  *         cannot be reallocated or the function is used to free the memory block
     258             :  *
     259             :  * @warning Unlike av_malloc(), the returned pointer is not guaranteed to be
     260             :  *          correctly aligned.
     261             :  * @see av_fast_realloc()
     262             :  * @see av_reallocp()
     263             :  */
     264             : void *av_realloc(void *ptr, size_t size) av_alloc_size(2);
     265             : 
     266             : /**
     267             :  * Allocate, reallocate, or free a block of memory through a pointer to a
     268             :  * pointer.
     269             :  *
     270             :  * If `*ptr` is `NULL` and `size` > 0, allocate a new block. If `size` is
     271             :  * zero, free the memory block pointed to by `*ptr`. Otherwise, expand or
     272             :  * shrink that block of memory according to `size`.
     273             :  *
     274             :  * @param[in,out] ptr  Pointer to a pointer to a memory block already allocated
     275             :  *                     with av_realloc(), or a pointer to `NULL`. The pointer
     276             :  *                     is updated on success, or freed on failure.
     277             :  * @param[in]     size Size in bytes for the memory block to be allocated or
     278             :  *                     reallocated
     279             :  *
     280             :  * @return Zero on success, an AVERROR error code on failure
     281             :  *
     282             :  * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
     283             :  *          correctly aligned.
     284             :  */
     285             : av_warn_unused_result
     286             : int av_reallocp(void *ptr, size_t size);
     287             : 
     288             : /**
     289             :  * Allocate, reallocate, or free a block of memory.
     290             :  *
     291             :  * This function does the same thing as av_realloc(), except:
     292             :  * - It takes two size arguments and allocates `nelem * elsize` bytes,
     293             :  *   after checking the result of the multiplication for integer overflow.
     294             :  * - It frees the input block in case of failure, thus avoiding the memory
     295             :  *   leak with the classic
     296             :  *   @code{.c}
     297             :  *   buf = realloc(buf);
     298             :  *   if (!buf)
     299             :  *       return -1;
     300             :  *   @endcode
     301             :  *   pattern.
     302             :  */
     303             : void *av_realloc_f(void *ptr, size_t nelem, size_t elsize);
     304             : 
     305             : /**
     306             :  * Allocate, reallocate, or free an array.
     307             :  *
     308             :  * If `ptr` is `NULL` and `nmemb` > 0, allocate a new block. If
     309             :  * `nmemb` is zero, free the memory block pointed to by `ptr`.
     310             :  *
     311             :  * @param ptr   Pointer to a memory block already allocated with
     312             :  *              av_realloc() or `NULL`
     313             :  * @param nmemb Number of elements in the array
     314             :  * @param size  Size of the single element of the array
     315             :  *
     316             :  * @return Pointer to a newly-reallocated block or NULL if the block
     317             :  *         cannot be reallocated or the function is used to free the memory block
     318             :  *
     319             :  * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
     320             :  *          correctly aligned.
     321             :  * @see av_reallocp_array()
     322             :  */
     323             : av_alloc_size(2, 3) void *av_realloc_array(void *ptr, size_t nmemb, size_t size);
     324             : 
     325             : /**
     326             :  * Allocate, reallocate, or free an array through a pointer to a pointer.
     327             :  *
     328             :  * If `*ptr` is `NULL` and `nmemb` > 0, allocate a new block. If `nmemb` is
     329             :  * zero, free the memory block pointed to by `*ptr`.
     330             :  *
     331             :  * @param[in,out] ptr   Pointer to a pointer to a memory block already
     332             :  *                      allocated with av_realloc(), or a pointer to `NULL`.
     333             :  *                      The pointer is updated on success, or freed on failure.
     334             :  * @param[in]     nmemb Number of elements
     335             :  * @param[in]     size  Size of the single element
     336             :  *
     337             :  * @return Zero on success, an AVERROR error code on failure
     338             :  *
     339             :  * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
     340             :  *          correctly aligned.
     341             :  */
     342             : av_alloc_size(2, 3) int av_reallocp_array(void *ptr, size_t nmemb, size_t size);
     343             : 
     344             : /**
     345             :  * Reallocate the given buffer if it is not large enough, otherwise do nothing.
     346             :  *
     347             :  * If the given buffer is `NULL`, then a new uninitialized buffer is allocated.
     348             :  *
     349             :  * If the given buffer is not large enough, and reallocation fails, `NULL` is
     350             :  * returned and `*size` is set to 0, but the original buffer is not changed or
     351             :  * freed.
     352             :  *
     353             :  * A typical use pattern follows:
     354             :  *
     355             :  * @code{.c}
     356             :  * uint8_t *buf = ...;
     357             :  * uint8_t *new_buf = av_fast_realloc(buf, &current_size, size_needed);
     358             :  * if (!new_buf) {
     359             :  *     // Allocation failed; clean up original buffer
     360             :  *     av_freep(&buf);
     361             :  *     return AVERROR(ENOMEM);
     362             :  * }
     363             :  * @endcode
     364             :  *
     365             :  * @param[in,out] ptr      Already allocated buffer, or `NULL`
     366             :  * @param[in,out] size     Pointer to current size of buffer `ptr`. `*size` is
     367             :  *                         changed to `min_size` in case of success or 0 in
     368             :  *                         case of failure
     369             :  * @param[in]     min_size New size of buffer `ptr`
     370             :  * @return `ptr` if the buffer is large enough, a pointer to newly reallocated
     371             :  *         buffer if the buffer was not large enough, or `NULL` in case of
     372             :  *         error
     373             :  * @see av_realloc()
     374             :  * @see av_fast_malloc()
     375             :  */
     376             : void *av_fast_realloc(void *ptr, unsigned int *size, size_t min_size);
     377             : 
     378             : /**
     379             :  * Allocate a buffer, reusing the given one if large enough.
     380             :  *
     381             :  * Contrary to av_fast_realloc(), the current buffer contents might not be
     382             :  * preserved and on error the old buffer is freed, thus no special handling to
     383             :  * avoid memleaks is necessary.
     384             :  *
     385             :  * `*ptr` is allowed to be `NULL`, in which case allocation always happens if
     386             :  * `size_needed` is greater than 0.
     387             :  *
     388             :  * @code{.c}
     389             :  * uint8_t *buf = ...;
     390             :  * av_fast_malloc(&buf, &current_size, size_needed);
     391             :  * if (!buf) {
     392             :  *     // Allocation failed; buf already freed
     393             :  *     return AVERROR(ENOMEM);
     394             :  * }
     395             :  * @endcode
     396             :  *
     397             :  * @param[in,out] ptr      Pointer to pointer to an already allocated buffer.
     398             :  *                         `*ptr` will be overwritten with pointer to new
     399             :  *                         buffer on success or `NULL` on failure
     400             :  * @param[in,out] size     Pointer to current size of buffer `*ptr`. `*size` is
     401             :  *                         changed to `min_size` in case of success or 0 in
     402             :  *                         case of failure
     403             :  * @param[in]     min_size New size of buffer `*ptr`
     404             :  * @see av_realloc()
     405             :  * @see av_fast_mallocz()
     406             :  */
     407             : void av_fast_malloc(void *ptr, unsigned int *size, size_t min_size);
     408             : 
     409             : /**
     410             :  * Allocate and clear a buffer, reusing the given one if large enough.
     411             :  *
     412             :  * Like av_fast_malloc(), but all newly allocated space is initially cleared.
     413             :  * Reused buffer is not cleared.
     414             :  *
     415             :  * `*ptr` is allowed to be `NULL`, in which case allocation always happens if
     416             :  * `size_needed` is greater than 0.
     417             :  *
     418             :  * @param[in,out] ptr      Pointer to pointer to an already allocated buffer.
     419             :  *                         `*ptr` will be overwritten with pointer to new
     420             :  *                         buffer on success or `NULL` on failure
     421             :  * @param[in,out] size     Pointer to current size of buffer `*ptr`. `*size` is
     422             :  *                         changed to `min_size` in case of success or 0 in
     423             :  *                         case of failure
     424             :  * @param[in]     min_size New size of buffer `*ptr`
     425             :  * @see av_fast_malloc()
     426             :  */
     427             : void av_fast_mallocz(void *ptr, unsigned int *size, size_t min_size);
     428             : 
     429             : /**
     430             :  * Free a memory block which has been allocated with a function of av_malloc()
     431             :  * or av_realloc() family.
     432             :  *
     433             :  * @param ptr Pointer to the memory block which should be freed.
     434             :  *
     435             :  * @note `ptr = NULL` is explicitly allowed.
     436             :  * @note It is recommended that you use av_freep() instead, to prevent leaving
     437             :  *       behind dangling pointers.
     438             :  * @see av_freep()
     439             :  */
     440             : void av_free(void *ptr);
     441             : 
     442             : /**
     443             :  * Free a memory block which has been allocated with a function of av_malloc()
     444             :  * or av_realloc() family, and set the pointer pointing to it to `NULL`.
     445             :  *
     446             :  * @code{.c}
     447             :  * uint8_t *buf = av_malloc(16);
     448             :  * av_free(buf);
     449             :  * // buf now contains a dangling pointer to freed memory, and accidental
     450             :  * // dereference of buf will result in a use-after-free, which may be a
     451             :  * // security risk.
     452             :  *
     453             :  * uint8_t *buf = av_malloc(16);
     454             :  * av_freep(&buf);
     455             :  * // buf is now NULL, and accidental dereference will only result in a
     456             :  * // NULL-pointer dereference.
     457             :  * @endcode
     458             :  *
     459             :  * @param ptr Pointer to the pointer to the memory block which should be freed
     460             :  * @note `*ptr = NULL` is safe and leads to no action.
     461             :  * @see av_free()
     462             :  */
     463             : void av_freep(void *ptr);
     464             : 
     465             : /**
     466             :  * Duplicate a string.
     467             :  *
     468             :  * @param s String to be duplicated
     469             :  * @return Pointer to a newly-allocated string containing a
     470             :  *         copy of `s` or `NULL` if the string cannot be allocated
     471             :  * @see av_strndup()
     472             :  */
     473             : char *av_strdup(const char *s) av_malloc_attrib;
     474             : 
     475             : /**
     476             :  * Duplicate a substring of a string.
     477             :  *
     478             :  * @param s   String to be duplicated
     479             :  * @param len Maximum length of the resulting string (not counting the
     480             :  *            terminating byte)
     481             :  * @return Pointer to a newly-allocated string containing a
     482             :  *         substring of `s` or `NULL` if the string cannot be allocated
     483             :  */
     484             : char *av_strndup(const char *s, size_t len) av_malloc_attrib;
     485             : 
     486             : /**
     487             :  * Duplicate a buffer with av_malloc().
     488             :  *
     489             :  * @param p    Buffer to be duplicated
     490             :  * @param size Size in bytes of the buffer copied
     491             :  * @return Pointer to a newly allocated buffer containing a
     492             :  *         copy of `p` or `NULL` if the buffer cannot be allocated
     493             :  */
     494             : void *av_memdup(const void *p, size_t size);
     495             : 
     496             : /**
     497             :  * Overlapping memcpy() implementation.
     498             :  *
     499             :  * @param dst  Destination buffer
     500             :  * @param back Number of bytes back to start copying (i.e. the initial size of
     501             :  *             the overlapping window); must be > 0
     502             :  * @param cnt  Number of bytes to copy; must be >= 0
     503             :  *
     504             :  * @note `cnt > back` is valid, this will copy the bytes we just copied,
     505             :  *       thus creating a repeating pattern with a period length of `back`.
     506             :  */
     507             : void av_memcpy_backptr(uint8_t *dst, int back, int cnt);
     508             : 
     509             : /**
     510             :  * @}
     511             :  */
     512             : 
     513             : /**
     514             :  * @defgroup lavu_mem_dynarray Dynamic Array
     515             :  *
     516             :  * Utilities to make an array grow when needed.
     517             :  *
     518             :  * Sometimes, the programmer would want to have an array that can grow when
     519             :  * needed. The libavutil dynamic array utilities fill that need.
     520             :  *
     521             :  * libavutil supports two systems of appending elements onto a dynamically
     522             :  * allocated array, the first one storing the pointer to the value in the
     523             :  * array, and the second storing the value directly. In both systems, the
     524             :  * caller is responsible for maintaining a variable containing the length of
     525             :  * the array, as well as freeing of the array after use.
     526             :  *
     527             :  * The first system stores pointers to values in a block of dynamically
     528             :  * allocated memory. Since only pointers are stored, the function does not need
     529             :  * to know the size of the type. Both av_dynarray_add() and
     530             :  * av_dynarray_add_nofree() implement this system.
     531             :  *
     532             :  * @code
     533             :  * type **array = NULL; //< an array of pointers to values
     534             :  * int    nb    = 0;    //< a variable to keep track of the length of the array
     535             :  *
     536             :  * type to_be_added  = ...;
     537             :  * type to_be_added2 = ...;
     538             :  *
     539             :  * av_dynarray_add(&array, &nb, &to_be_added);
     540             :  * if (nb == 0)
     541             :  *     return AVERROR(ENOMEM);
     542             :  *
     543             :  * av_dynarray_add(&array, &nb, &to_be_added2);
     544             :  * if (nb == 0)
     545             :  *     return AVERROR(ENOMEM);
     546             :  *
     547             :  * // Now:
     548             :  * //  nb           == 2
     549             :  * // &to_be_added  == array[0]
     550             :  * // &to_be_added2 == array[1]
     551             :  *
     552             :  * av_freep(&array);
     553             :  * @endcode
     554             :  *
     555             :  * The second system stores the value directly in a block of memory. As a
     556             :  * result, the function has to know the size of the type. av_dynarray2_add()
     557             :  * implements this mechanism.
     558             :  *
     559             :  * @code
     560             :  * type *array = NULL; //< an array of values
     561             :  * int   nb    = 0;    //< a variable to keep track of the length of the array
     562             :  *
     563             :  * type to_be_added  = ...;
     564             :  * type to_be_added2 = ...;
     565             :  *
     566             :  * type *addr = av_dynarray2_add((void **)&array, &nb, sizeof(*array), NULL);
     567             :  * if (!addr)
     568             :  *     return AVERROR(ENOMEM);
     569             :  * memcpy(addr, &to_be_added, sizeof(to_be_added));
     570             :  *
     571             :  * // Shortcut of the above.
     572             :  * type *addr = av_dynarray2_add((void **)&array, &nb, sizeof(*array),
     573             :  *                               (const void *)&to_be_added2);
     574             :  * if (!addr)
     575             :  *     return AVERROR(ENOMEM);
     576             :  *
     577             :  * // Now:
     578             :  * //  nb           == 2
     579             :  * //  to_be_added  == array[0]
     580             :  * //  to_be_added2 == array[1]
     581             :  *
     582             :  * av_freep(&array);
     583             :  * @endcode
     584             :  *
     585             :  * @{
     586             :  */
     587             : 
     588             : /**
     589             :  * Add the pointer to an element to a dynamic array.
     590             :  *
     591             :  * The array to grow is supposed to be an array of pointers to
     592             :  * structures, and the element to add must be a pointer to an already
     593             :  * allocated structure.
     594             :  *
     595             :  * The array is reallocated when its size reaches powers of 2.
     596             :  * Therefore, the amortized cost of adding an element is constant.
     597             :  *
     598             :  * In case of success, the pointer to the array is updated in order to
     599             :  * point to the new grown array, and the number pointed to by `nb_ptr`
     600             :  * is incremented.
     601             :  * In case of failure, the array is freed, `*tab_ptr` is set to `NULL` and
     602             :  * `*nb_ptr` is set to 0.
     603             :  *
     604             :  * @param[in,out] tab_ptr Pointer to the array to grow
     605             :  * @param[in,out] nb_ptr  Pointer to the number of elements in the array
     606             :  * @param[in]     elem    Element to add
     607             :  * @see av_dynarray_add_nofree(), av_dynarray2_add()
     608             :  */
     609             : void av_dynarray_add(void *tab_ptr, int *nb_ptr, void *elem);
     610             : 
     611             : /**
     612             :  * Add an element to a dynamic array.
     613             :  *
     614             :  * Function has the same functionality as av_dynarray_add(),
     615             :  * but it doesn't free memory on fails. It returns error code
     616             :  * instead and leave current buffer untouched.
     617             :  *
     618             :  * @return >=0 on success, negative otherwise
     619             :  * @see av_dynarray_add(), av_dynarray2_add()
     620             :  */
     621             : av_warn_unused_result
     622             : int av_dynarray_add_nofree(void *tab_ptr, int *nb_ptr, void *elem);
     623             : 
     624             : /**
     625             :  * Add an element of size `elem_size` to a dynamic array.
     626             :  *
     627             :  * The array is reallocated when its number of elements reaches powers of 2.
     628             :  * Therefore, the amortized cost of adding an element is constant.
     629             :  *
     630             :  * In case of success, the pointer to the array is updated in order to
     631             :  * point to the new grown array, and the number pointed to by `nb_ptr`
     632             :  * is incremented.
     633             :  * In case of failure, the array is freed, `*tab_ptr` is set to `NULL` and
     634             :  * `*nb_ptr` is set to 0.
     635             :  *
     636             :  * @param[in,out] tab_ptr   Pointer to the array to grow
     637             :  * @param[in,out] nb_ptr    Pointer to the number of elements in the array
     638             :  * @param[in]     elem_size Size in bytes of an element in the array
     639             :  * @param[in]     elem_data Pointer to the data of the element to add. If
     640             :  *                          `NULL`, the space of the newly added element is
     641             :  *                          allocated but left uninitialized.
     642             :  *
     643             :  * @return Pointer to the data of the element to copy in the newly allocated
     644             :  *         space
     645             :  * @see av_dynarray_add(), av_dynarray_add_nofree()
     646             :  */
     647             : void *av_dynarray2_add(void **tab_ptr, int *nb_ptr, size_t elem_size,
     648             :                        const uint8_t *elem_data);
     649             : 
     650             : /**
     651             :  * @}
     652             :  */
     653             : 
     654             : /**
     655             :  * @defgroup lavu_mem_misc Miscellaneous Functions
     656             :  *
     657             :  * Other functions related to memory allocation.
     658             :  *
     659             :  * @{
     660             :  */
     661             : 
     662             : /**
     663             :  * Multiply two `size_t` values checking for overflow.
     664             :  *
     665             :  * @param[in]  a,b Operands of multiplication
     666             :  * @param[out] r   Pointer to the result of the operation
     667             :  * @return 0 on success, AVERROR(EINVAL) on overflow
     668             :  */
     669       54681 : static inline int av_size_mult(size_t a, size_t b, size_t *r)
     670             : {
     671       54681 :     size_t t = a * b;
     672             :     /* Hack inspired from glibc: don't try the division if nelem and elsize
     673             :      * are both less than sqrt(SIZE_MAX). */
     674       54681 :     if ((a | b) >= ((size_t)1 << (sizeof(size_t) * 4)) && a && t / a != b)
     675           0 :         return AVERROR(EINVAL);
     676       54681 :     *r = t;
     677       54681 :     return 0;
     678             : }
     679             : 
     680             : /**
     681             :  * Set the maximum size that may be allocated in one block.
     682             :  *
     683             :  * The value specified with this function is effective for all libavutil's @ref
     684             :  * lavu_mem_funcs "heap management functions."
     685             :  *
     686             :  * By default, the max value is defined as `INT_MAX`.
     687             :  *
     688             :  * @param max Value to be set as the new maximum size
     689             :  *
     690             :  * @warning Exercise extreme caution when using this function. Don't touch
     691             :  *          this if you do not understand the full consequence of doing so.
     692             :  */
     693             : void av_max_alloc(size_t max);
     694             : 
     695             : /**
     696             :  * @}
     697             :  * @}
     698             :  */
     699             : 
     700             : #endif /* AVUTIL_MEM_H */

Generated by: LCOV version 1.13