mem.h 23 KB

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