Memory management and reference counting

Due to the nature of its domain libcbor will need to work with heap memory. The stateless decoder and encoder don’t allocate any memory.

If you have specific requirements, you should consider rolling your own driver for the stateless API.

Using custom allocator

libcbor gives you with the ability to provide your own implementations of malloc, realloc, and free. This can be useful if you are using a custom allocator throughout your application, or if you want to implement custom policies (e.g. tighter restrictions on the amount of allocated memory).

In order to use this feature, libcbor has to be compiled with the appropriate flags. You can verify the configuration using the CBOR_CUSTOM_ALLOC macro. A simple usage might be as follows:

#if CBOR_CUSTOM_ALLOC
    cbor_set_allocs(malloc, realloc, free);
#else
   #error "libcbor built with support for custom allocation is required"
#endif

Warning

doxygenfunction: Cannot find function “cbor_set_allocs” in doxygen xml output for project “libcbor” from directory: ../build/doxygen/xml

Reference counting

As CBOR items may require complex cleanups at the end of their lifetime, there is a reference counting mechanism in place. This also enables very simple GC when integrating libcbor into 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.

Items containing nested items will be destroyed recursively - refcount of every nested item will be decreased by one.

The destruction is synchronous and renders any pointers to items with refcount zero invalid immediately after calling the cbor_decref().

Warning

doxygenfunction: Cannot find function “cbor_incref” in doxygen xml output for project “libcbor” from directory: ../build/doxygen/xml

Warning

doxygenfunction: Cannot find function “cbor_decref” in doxygen xml output for project “libcbor” from directory: ../build/doxygen/xml

Warning

doxygenfunction: Cannot find function “cbor_intermediate_decref” in doxygen xml output for project “libcbor” from directory: ../build/doxygen/xml

Warning

doxygenfunction: Cannot find function “cbor_refcount” in doxygen xml output for project “libcbor” from directory: ../build/doxygen/xml

Warning

doxygenfunction: Cannot find function “cbor_move” in doxygen xml output for project “libcbor” from directory: ../build/doxygen/xml

cbor_item_t *cbor_copy(cbor_item_t *item)

Deep copy of an item.

All the reference counts in the new structure are set to one.

Return

new CBOR deep copy

Parameters

• item[borrow]: item to copy