2 * copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at>
4 * This file is part of FFmpeg.
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.
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.
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
24 * Memory handling functions
33 #include "attributes.h"
38 * @addtogroup lavu_mem
39 * Utilities for manipulating memory.
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.
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.
53 * @defgroup lavu_mem_macros Alignment Macros
54 * Helper macros for declaring aligned variables.
59 * @def DECLARE_ALIGNED(n,t,v)
60 * Declare a variable that is aligned in memory.
63 * DECLARE_ALIGNED(16, uint16_t, aligned_int) = 42;
64 * DECLARE_ALIGNED(32, uint8_t, aligned_array)[128];
66 * // The default-alignment equivalent would be
67 * uint16_t aligned_int = 42;
68 * uint8_t aligned_array[128];
71 * @param n Minimum alignment in bytes
72 * @param t Type of the variable (or array element)
73 * @param v Name of the variable
77 * @def DECLARE_ASM_CONST(n,t,v)
78 * Declare a static constant aligned variable appropriate for use in inline
82 * DECLARE_ASM_CONST(16, uint64_t, pw_08) = UINT64_C(0x0008000800080008);
85 * @param n Minimum alignment in bytes
86 * @param t Type of the variable (or array element)
87 * @param v Name of the variable
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(__DJGPP__)
94 #define DECLARE_ALIGNED(n,t,v) t __attribute__ ((aligned (FFMIN(n, 16)))) v
95 #define DECLARE_ASM_CONST(n,t,v) static const t av_used __attribute__ ((aligned (FFMIN(n, 16)))) v
96 #elif defined(__GNUC__) || defined(__clang__)
97 #define DECLARE_ALIGNED(n,t,v) t __attribute__ ((aligned (n))) v
98 #define DECLARE_ASM_CONST(n,t,v) static const t av_used __attribute__ ((aligned (n))) v
99 #elif defined(_MSC_VER)
100 #define DECLARE_ALIGNED(n,t,v) __declspec(align(n)) t v
101 #define DECLARE_ASM_CONST(n,t,v) __declspec(align(n)) static const t v
103 #define DECLARE_ALIGNED(n,t,v) t v
104 #define DECLARE_ASM_CONST(n,t,v) static const t v
112 * @defgroup lavu_mem_attrs Function Attributes
113 * Function attributes applicable to memory handling functions.
115 * These function attributes can help compilers emit more useful warnings, or
116 * generate better code.
121 * @def av_malloc_attrib
122 * Function attribute denoting a malloc-like function.
124 * @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>
127 #if AV_GCC_VERSION_AT_LEAST(3,1)
128 #define av_malloc_attrib __attribute__((__malloc__))
130 #define av_malloc_attrib
134 * @def av_alloc_size(...)
135 * Function attribute used on a function that allocates memory, whose size is
136 * given by the specified parameter(s).
139 * void *av_malloc(size_t size) av_alloc_size(1);
140 * void *av_calloc(size_t nmemb, size_t size) av_alloc_size(1, 2);
143 * @param ... One or two parameter indexes, separated by a comma
145 * @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>
148 #if AV_GCC_VERSION_AT_LEAST(4,3)
149 #define av_alloc_size(...) __attribute__((alloc_size(__VA_ARGS__)))
151 #define av_alloc_size(...)
159 * @defgroup lavu_mem_funcs Heap Management
160 * Functions responsible for allocating, freeing, and copying memory.
162 * All memory allocation functions have a built-in upper limit of `INT_MAX`
163 * bytes. This may be changed with av_max_alloc(), although exercise extreme
164 * caution when doing so.
170 * Allocate a memory block with alignment suitable for all memory accesses
171 * (including vectors if available on the CPU).
173 * @param size Size in bytes for the memory block to be allocated
174 * @return Pointer to the allocated block, or `NULL` if the block cannot
178 void *av_malloc(size_t size) av_malloc_attrib av_alloc_size(1);
181 * Allocate a memory block with alignment suitable for all memory accesses
182 * (including vectors if available on the CPU) and zero all the bytes of the
185 * @param size Size in bytes for the memory block to be allocated
186 * @return Pointer to the allocated block, or `NULL` if it cannot be allocated
189 void *av_mallocz(size_t size) av_malloc_attrib av_alloc_size(1);
192 * Allocate a memory block for an array with av_malloc().
194 * The allocated memory will have size `size * nmemb` bytes.
196 * @param nmemb Number of element
197 * @param size Size of a single element
198 * @return Pointer to the allocated block, or `NULL` if the block cannot
202 av_alloc_size(1, 2) void *av_malloc_array(size_t nmemb, size_t size);
205 * Allocate a memory block for an array with av_mallocz().
207 * The allocated memory will have size `size * nmemb` bytes.
209 * @param nmemb Number of elements
210 * @param size Size of the single element
211 * @return Pointer to the allocated block, or `NULL` if the block cannot
215 * @see av_malloc_array()
217 av_alloc_size(1, 2) void *av_mallocz_array(size_t nmemb, size_t size);
220 * Non-inlined equivalent of av_mallocz_array().
222 * Created for symmetry with the calloc() C function.
224 void *av_calloc(size_t nmemb, size_t size) av_malloc_attrib;
227 * Allocate, reallocate, or free a block of memory.
229 * If `ptr` is `NULL` and `size` > 0, allocate a new block. If `size` is
230 * zero, free the memory block pointed to by `ptr`. Otherwise, expand or
231 * shrink that block of memory according to `size`.
233 * @param ptr Pointer to a memory block already allocated with
234 * av_realloc() or `NULL`
235 * @param size Size in bytes of the memory block to be allocated or
238 * @return Pointer to a newly-reallocated block or `NULL` if the block
239 * cannot be reallocated or the function is used to free the memory block
241 * @warning Unlike av_malloc(), the returned pointer is not guaranteed to be
243 * @see av_fast_realloc()
246 void *av_realloc(void *ptr, size_t size) av_alloc_size(2);
249 * Allocate, reallocate, or free a block of memory through a pointer to a
252 * If `*ptr` is `NULL` and `size` > 0, allocate a new block. If `size` is
253 * zero, free the memory block pointed to by `*ptr`. Otherwise, expand or
254 * shrink that block of memory according to `size`.
256 * @param[in,out] ptr Pointer to a pointer to a memory block already allocated
257 * with av_realloc(), or a pointer to `NULL`. The pointer
258 * is updated on success, or freed on failure.
259 * @param[in] size Size in bytes for the memory block to be allocated or
262 * @return Zero on success, an AVERROR error code on failure
264 * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
267 av_warn_unused_result
268 int av_reallocp(void *ptr, size_t size);
271 * Allocate, reallocate, or free a block of memory.
273 * This function does the same thing as av_realloc(), except:
274 * - It takes two size arguments and allocates `nelem * elsize` bytes,
275 * after checking the result of the multiplication for integer overflow.
276 * - It frees the input block in case of failure, thus avoiding the memory
277 * leak with the classic
279 * buf = realloc(buf);
285 void *av_realloc_f(void *ptr, size_t nelem, size_t elsize);
288 * Allocate, reallocate, or free an array.
290 * If `ptr` is `NULL` and `nmemb` > 0, allocate a new block. If
291 * `nmemb` is zero, free the memory block pointed to by `ptr`.
293 * @param ptr Pointer to a memory block already allocated with
294 * av_realloc() or `NULL`
295 * @param nmemb Number of elements in the array
296 * @param size Size of the single element of the array
298 * @return Pointer to a newly-reallocated block or NULL if the block
299 * cannot be reallocated or the function is used to free the memory block
301 * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
303 * @see av_reallocp_array()
305 av_alloc_size(2, 3) void *av_realloc_array(void *ptr, size_t nmemb, size_t size);
308 * Allocate, reallocate, or free an array through a pointer to a pointer.
310 * If `*ptr` is `NULL` and `nmemb` > 0, allocate a new block. If `nmemb` is
311 * zero, free the memory block pointed to by `*ptr`.
313 * @param[in,out] ptr Pointer to a pointer to a memory block already
314 * allocated with av_realloc(), or a pointer to `NULL`.
315 * The pointer is updated on success, or freed on failure.
316 * @param[in] nmemb Number of elements
317 * @param[in] size Size of the single element
319 * @return Zero on success, an AVERROR error code on failure
321 * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
324 av_alloc_size(2, 3) int av_reallocp_array(void *ptr, size_t nmemb, size_t size);
327 * Reallocate the given buffer if it is not large enough, otherwise do nothing.
329 * If the given buffer is `NULL`, then a new uninitialized buffer is allocated.
331 * If the given buffer is not large enough, and reallocation fails, `NULL` is
332 * returned and `*size` is set to 0, but the original buffer is not changed or
335 * A typical use pattern follows:
338 * uint8_t *buf = ...;
339 * uint8_t *new_buf = av_fast_realloc(buf, ¤t_size, size_needed);
341 * // Allocation failed; clean up original buffer
343 * return AVERROR(ENOMEM);
347 * @param[in,out] ptr Already allocated buffer, or `NULL`
348 * @param[in,out] size Pointer to current size of buffer `ptr`. `*size` is
349 * changed to `min_size` in case of success or 0 in
351 * @param[in] min_size New size of buffer `ptr`
352 * @return `ptr` if the buffer is large enough, a pointer to newly reallocated
353 * buffer if the buffer was not large enough, or `NULL` in case of
356 * @see av_fast_malloc()
358 void *av_fast_realloc(void *ptr, unsigned int *size, size_t min_size);
361 * Allocate a buffer, reusing the given one if large enough.
363 * Contrary to av_fast_realloc(), the current buffer contents might not be
364 * preserved and on error the old buffer is freed, thus no special handling to
365 * avoid memleaks is necessary.
367 * `*ptr` is allowed to be `NULL`, in which case allocation always happens if
368 * `size_needed` is greater than 0.
371 * uint8_t *buf = ...;
372 * av_fast_malloc(&buf, ¤t_size, size_needed);
374 * // Allocation failed; buf already freed
375 * return AVERROR(ENOMEM);
379 * @param[in,out] ptr Pointer to pointer to an already allocated buffer.
380 * `*ptr` will be overwritten with pointer to new
381 * buffer on success or `NULL` on failure
382 * @param[in,out] size Pointer to current size of buffer `*ptr`. `*size` is
383 * changed to `min_size` in case of success or 0 in
385 * @param[in] min_size New size of buffer `*ptr`
387 * @see av_fast_mallocz()
389 void av_fast_malloc(void *ptr, unsigned int *size, size_t min_size);
392 * Allocate and clear a buffer, reusing the given one if large enough.
394 * Like av_fast_malloc(), but all newly allocated space is initially cleared.
395 * Reused buffer is not cleared.
397 * `*ptr` is allowed to be `NULL`, in which case allocation always happens if
398 * `size_needed` is greater than 0.
400 * @param[in,out] ptr Pointer to pointer to an already allocated buffer.
401 * `*ptr` will be overwritten with pointer to new
402 * buffer on success or `NULL` on failure
403 * @param[in,out] size Pointer to current size of buffer `*ptr`. `*size` is
404 * changed to `min_size` in case of success or 0 in
406 * @param[in] min_size New size of buffer `*ptr`
407 * @see av_fast_malloc()
409 void av_fast_mallocz(void *ptr, unsigned int *size, size_t min_size);
412 * Free a memory block which has been allocated with a function of av_malloc()
413 * or av_realloc() family.
415 * @param ptr Pointer to the memory block which should be freed.
417 * @note `ptr = NULL` is explicitly allowed.
418 * @note It is recommended that you use av_freep() instead, to prevent leaving
419 * behind dangling pointers.
422 void av_free(void *ptr);
425 * Free a memory block which has been allocated with a function of av_malloc()
426 * or av_realloc() family, and set the pointer pointing to it to `NULL`.
429 * uint8_t *buf = av_malloc(16);
431 * // buf now contains a dangling pointer to freed memory, and accidental
432 * // dereference of buf will result in a use-after-free, which may be a
435 * uint8_t *buf = av_malloc(16);
437 * // buf is now NULL, and accidental dereference will only result in a
438 * // NULL-pointer dereference.
441 * @param ptr Pointer to the pointer to the memory block which should be freed
442 * @note `*ptr = NULL` is safe and leads to no action.
445 void av_freep(void *ptr);
448 * Duplicate a string.
450 * @param s String to be duplicated
451 * @return Pointer to a newly-allocated string containing a
452 * copy of `s` or `NULL` if the string cannot be allocated
455 char *av_strdup(const char *s) av_malloc_attrib;
458 * Duplicate a substring of a string.
460 * @param s String to be duplicated
461 * @param len Maximum length of the resulting string (not counting the
463 * @return Pointer to a newly-allocated string containing a
464 * substring of `s` or `NULL` if the string cannot be allocated
466 char *av_strndup(const char *s, size_t len) av_malloc_attrib;
469 * Duplicate a buffer with av_malloc().
471 * @param p Buffer to be duplicated
472 * @param size Size in bytes of the buffer copied
473 * @return Pointer to a newly allocated buffer containing a
474 * copy of `p` or `NULL` if the buffer cannot be allocated
476 void *av_memdup(const void *p, size_t size);
479 * Overlapping memcpy() implementation.
481 * @param dst Destination buffer
482 * @param back Number of bytes back to start copying (i.e. the initial size of
483 * the overlapping window); must be > 0
484 * @param cnt Number of bytes to copy; must be >= 0
486 * @note `cnt > back` is valid, this will copy the bytes we just copied,
487 * thus creating a repeating pattern with a period length of `back`.
489 void av_memcpy_backptr(uint8_t *dst, int back, int cnt);
496 * @defgroup lavu_mem_dynarray Dynamic Array
498 * Utilities to make an array grow when needed.
500 * Sometimes, the programmer would want to have an array that can grow when
501 * needed. The libavutil dynamic array utilities fill that need.
503 * libavutil supports two systems of appending elements onto a dynamically
504 * allocated array, the first one storing the pointer to the value in the
505 * array, and the second storing the value directly. In both systems, the
506 * caller is responsible for maintaining a variable containing the length of
507 * the array, as well as freeing of the array after use.
509 * The first system stores pointers to values in a block of dynamically
510 * allocated memory. Since only pointers are stored, the function does not need
511 * to know the size of the type. Both av_dynarray_add() and
512 * av_dynarray_add_nofree() implement this system.
515 * type **array = NULL; //< an array of pointers to values
516 * int nb = 0; //< a variable to keep track of the length of the array
518 * type to_be_added = ...;
519 * type to_be_added2 = ...;
521 * av_dynarray_add(&array, &nb, &to_be_added);
523 * return AVERROR(ENOMEM);
525 * av_dynarray_add(&array, &nb, &to_be_added2);
527 * return AVERROR(ENOMEM);
531 * // &to_be_added == array[0]
532 * // &to_be_added2 == array[1]
537 * The second system stores the value directly in a block of memory. As a
538 * result, the function has to know the size of the type. av_dynarray2_add()
539 * implements this mechanism.
542 * type *array = NULL; //< an array of values
543 * int nb = 0; //< a variable to keep track of the length of the array
545 * type to_be_added = ...;
546 * type to_be_added2 = ...;
548 * type *addr = av_dynarray2_add((void **)&array, &nb, sizeof(*array), NULL);
550 * return AVERROR(ENOMEM);
551 * memcpy(addr, &to_be_added, sizeof(to_be_added));
553 * // Shortcut of the above.
554 * type *addr = av_dynarray2_add((void **)&array, &nb, sizeof(*array),
555 * (const void *)&to_be_added2);
557 * return AVERROR(ENOMEM);
561 * // to_be_added == array[0]
562 * // to_be_added2 == array[1]
571 * Add the pointer to an element to a dynamic array.
573 * The array to grow is supposed to be an array of pointers to
574 * structures, and the element to add must be a pointer to an already
575 * allocated structure.
577 * The array is reallocated when its size reaches powers of 2.
578 * Therefore, the amortized cost of adding an element is constant.
580 * In case of success, the pointer to the array is updated in order to
581 * point to the new grown array, and the number pointed to by `nb_ptr`
583 * In case of failure, the array is freed, `*tab_ptr` is set to `NULL` and
584 * `*nb_ptr` is set to 0.
586 * @param[in,out] tab_ptr Pointer to the array to grow
587 * @param[in,out] nb_ptr Pointer to the number of elements in the array
588 * @param[in] elem Element to add
589 * @see av_dynarray_add_nofree(), av_dynarray2_add()
591 void av_dynarray_add(void *tab_ptr, int *nb_ptr, void *elem);
594 * Add an element to a dynamic array.
596 * Function has the same functionality as av_dynarray_add(),
597 * but it doesn't free memory on fails. It returns error code
598 * instead and leave current buffer untouched.
600 * @return >=0 on success, negative otherwise
601 * @see av_dynarray_add(), av_dynarray2_add()
603 av_warn_unused_result
604 int av_dynarray_add_nofree(void *tab_ptr, int *nb_ptr, void *elem);
607 * Add an element of size `elem_size` to a dynamic array.
609 * The array is reallocated when its number of elements reaches powers of 2.
610 * Therefore, the amortized cost of adding an element is constant.
612 * In case of success, the pointer to the array is updated in order to
613 * point to the new grown array, and the number pointed to by `nb_ptr`
615 * In case of failure, the array is freed, `*tab_ptr` is set to `NULL` and
616 * `*nb_ptr` is set to 0.
618 * @param[in,out] tab_ptr Pointer to the array to grow
619 * @param[in,out] nb_ptr Pointer to the number of elements in the array
620 * @param[in] elem_size Size in bytes of an element in the array
621 * @param[in] elem_data Pointer to the data of the element to add. If
622 * `NULL`, the space of the newly added element is
623 * allocated but left uninitialized.
625 * @return Pointer to the data of the element to copy in the newly allocated
627 * @see av_dynarray_add(), av_dynarray_add_nofree()
629 void *av_dynarray2_add(void **tab_ptr, int *nb_ptr, size_t elem_size,
630 const uint8_t *elem_data);
637 * @defgroup lavu_mem_misc Miscellaneous Functions
639 * Other functions related to memory allocation.
645 * Multiply two `size_t` values checking for overflow.
647 * @param[in] a,b Operands of multiplication
648 * @param[out] r Pointer to the result of the operation
649 * @return 0 on success, AVERROR(EINVAL) on overflow
651 static inline int av_size_mult(size_t a, size_t b, size_t *r)
654 /* Hack inspired from glibc: don't try the division if nelem and elsize
655 * are both less than sqrt(SIZE_MAX). */
656 if ((a | b) >= ((size_t)1 << (sizeof(size_t) * 4)) && a && t / a != b)
657 return AVERROR(EINVAL);
663 * Set the maximum size that may be allocated in one block.
665 * The value specified with this function is effective for all libavutil's @ref
666 * lavu_mem_funcs "heap management functions."
668 * By default, the max value is defined as `INT_MAX`.
670 * @param max Value to be set as the new maximum size
672 * @warning Exercise extreme caution when using this function. Don't touch
673 * this if you do not understand the full consequence of doing so.
675 void av_max_alloc(size_t max);
682 #endif /* AVUTIL_MEM_H */