110ff414cSEd MasteMemory management and reference counting 210ff414cSEd Maste=============================================== 310ff414cSEd Maste 4*5d3e7166SEd MasteDue to the nature of its domain, *libcbor* will need to work with heap memory. The stateless decoder and encoder doesn't allocate any memory. 510ff414cSEd Maste 610ff414cSEd MasteIf you have specific requirements, you should consider rolling your own driver for the stateless API. 710ff414cSEd Maste 810ff414cSEd MasteUsing custom allocator 910ff414cSEd Maste^^^^^^^^^^^^^^^^^^^^^^^^ 1010ff414cSEd Maste 11*5d3e7166SEd Maste*libcbor* gives you with the ability to provide your own implementations of ``malloc``, ``realloc``, and ``free``. 12*5d3e7166SEd MasteThis can be useful if you are using a custom allocator throughout your application, 13*5d3e7166SEd Masteor if you want to implement custom policies (e.g. tighter restrictions on the amount of allocated memory). 1410ff414cSEd Maste 1510ff414cSEd Maste 1610ff414cSEd Maste.. code-block:: c 1710ff414cSEd Maste 1810ff414cSEd Maste cbor_set_allocs(malloc, realloc, free); 1910ff414cSEd Maste 2010ff414cSEd Maste.. doxygenfunction:: cbor_set_allocs 2110ff414cSEd Maste 2210ff414cSEd Maste 2310ff414cSEd MasteReference counting 2410ff414cSEd Maste^^^^^^^^^^^^^^^^^^^^^ 2510ff414cSEd Maste 26*5d3e7166SEd MasteAs 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. 2710ff414cSEd Maste 28*5d3e7166SEd MasteItems containing nested items will be destroyed recursively - the refcount of every nested item will be decreased by one. 2910ff414cSEd Maste 30*5d3e7166SEd MasteThe destruction is synchronous and renders any pointers to items with refcount zero invalid immediately after calling :func:`cbor_decref`. 3110ff414cSEd Maste 3210ff414cSEd Maste 3310ff414cSEd Maste.. doxygenfunction:: cbor_incref 3410ff414cSEd Maste.. doxygenfunction:: cbor_decref 3510ff414cSEd Maste.. doxygenfunction:: cbor_intermediate_decref 3610ff414cSEd Maste.. doxygenfunction:: cbor_refcount 3710ff414cSEd Maste.. doxygenfunction:: cbor_move 3810ff414cSEd Maste.. doxygenfunction:: cbor_copy 39