1Memory management and reference counting 2=============================================== 3 4Due to the nature of its domain, *libcbor* will need to work with heap memory. The stateless decoder and encoder doesn't allocate any memory. 5 6If you have specific requirements, you should consider rolling your own driver for the stateless API. 7 8Using custom allocator 9^^^^^^^^^^^^^^^^^^^^^^^^ 10 11*libcbor* gives you with the ability to provide your own implementations of ``malloc``, ``realloc``, and ``free``. 12This can be useful if you are using a custom allocator throughout your application, 13or if you want to implement custom policies (e.g. tighter restrictions on the amount of allocated memory). 14 15 16.. code-block:: c 17 18 cbor_set_allocs(malloc, realloc, free); 19 20.. doxygenfunction:: cbor_set_allocs 21 22 23Reference counting 24^^^^^^^^^^^^^^^^^^^^^ 25 26As CBOR items may require complex cleanups at the end of their lifetime, there is a reference counting mechanism in place. This also enables a very simple GC when integrating *libcbor* into a managed environment. Every item starts its life (by either explicit creation, or as a result of parsing) with reference count set to 1. When the refcount reaches zero, it will be destroyed. 27 28Items containing nested items will be destroyed recursively - the refcount of every nested item will be decreased by one. 29 30The destruction is synchronous and renders any pointers to items with refcount zero invalid immediately after calling :func:`cbor_decref`. 31 32 33.. doxygenfunction:: cbor_incref 34.. doxygenfunction:: cbor_decref 35.. doxygenfunction:: cbor_intermediate_decref 36.. doxygenfunction:: cbor_refcount 37.. doxygenfunction:: cbor_move 38.. doxygenfunction:: cbor_copy 39