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