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