Memory management¶

This section describes heap memory management used by the TrulyNatural SDK C language binding. The Java binding uses the standard garbage collecting approach.

SDK handles (Session, Stream, Callback) are reference-counted. Manage the lifetime of these objects with retain and release.

Objects are created with a reference count of zero. This makes it cleaner to use a new object as a function argument without having to keep a handle to it just to be able to release it afterwards.

This library uses a small amount of heap memory to keep track of library-wide configuration options. You can use tearDown to free these allocations.

Best practices¶

If you keep a reference to a handle, call retain on it to increment the reference count.
Call release before giving up the reference. This will decrease the reference count and deallocate the object one the reference count is <= 0.
Functions that take reference-counted objects as arguments must
- Call retain on function entry for each of these arguments.
- Call release on function exit for each of these arguments, except for the ones where long-running references were kept.
- Follow this retain/release procedure even when the function returns an error condition, as it allows for convenient function composition without memory leaks.

Reference counting¶

release¶

C/C++Java

SNSR_API void
snsrRelease(const void *handle);

Parameters and return value

handle: A reference-counted object, or NULL.

Releases an object reference.

Decrements the reference count on handle. If the reference count drops to zero (or below), this will deallocate handle.

When this function returns handle will no longer be valid. Accessing a released handle in any way will lead to undefined behavior.

Note

handle must be NULL, or a valid reference-counted object returned by this library, such as Session, Stream, or Callback handle, or a const char * returned by getString.

Behavior on any other pointer is undefined and will likely lead to the process calling abort().

release, Callback, Session, Stream, getString

The Java language binding does not require or support explicit memory management.

retain¶

C/C++Java

SNSR_API void
snsrRetain(const void *handle);

Parameters and return value

handle: A reference-counted object.

Retains a reference to an object.

Increments the reference count on handle. The handle will remain valid until you call release on it.

To avoid memory leaks, be sure to match each call to retain with exactly one call to release.

Note

handle must be a valid reference-counted object returned by this library, such as Session, Stream, or Callback handle, or a const char * returned by getString.

Behavior on any other pointer (including NULL) is undefined and will likely lead to the process calling abort().

release, Callback, Session, Stream, getString

The Java language binding does not require or support explicit memory management.

Heap allocation¶

You can replace the standard library heap allocator used by the TrulyNatural SDK with one of the provided heap allocators, or one of your own design.

The functions in this section provide replacements for malloc(), realloc(), and free() that use this heap allocator. These are for convenience only, they're not used or required by the TrulyNatural SDK API.

malloc¶

C/C++Java

SNSR_API void *
snsrMalloc(size_t size);

Parameters and return value

size: Number of bytes to allocate on the heap.
: Pointer to the start of a memory block at least size bytes long.

Allocate memory with TrulyNatural SDK allocator.

This function works like malloc(), but uses this SDK's dynamic memory allocator instead.

This is provided for convenience only, it is not used or required by the library API.

Note

snsrMalloc() will never return NULL. A failed memory allocation results in a library-wide panic. You can provide a custom panic function with PANIC_FUNC.

heap allocators, free, realloc

The Java language binding does not require or support explicit memory management.

free¶

C/C++Java

SNSR_API void
snsrFree(void *ptr);

Parameters and return value

ptr: NULL, or an allocation previously returned by malloc or realloc.

Free heap memory allocated on the TrulyNatural SDK heap.

This function works like free(), but uses this library's dynamic memory allocator.

The ptr parameter must be NULL or be an allocation returned by either snsrMalloc() or snsrRealloc(). Any other value will result in undefined behavior.

This is provided for convenience only, it is not used or required by the library API.

heap allocators, malloc, realloc

The Java language binding does not require or support explicit memory management.

realloc¶

C/C++Java

SNSR_API void *
snsrRealloc(void *ptr, size_t size);

Parameters and return value

ptr: Allocation returned by malloc or realloc, or NULL.
size: Number of bytes to allocate on the heap.
: Pointer to the start of a memory block at least size bytes long.

Resize a heap block allocated on the TrulyNatural SDK heap.

This function works like realloc(), but uses this library's dynamic memory allocator.

The ptr parameter must NULL, or contain a value returned by snsrMalloc() or snsrRealloc(). Any other value will result in undefined behavior.

This is provided for convenience only, it is not used or required by the library API.

Note

snsrRealloc() will never return NULL. A failed memory allocation results in a library-wide panic. You can provide a custom panic function with PANIC_FUNC.

heap allocators, free, malloc

The Java language binding does not require or support explicit memory management.

Free library resources¶

tearDown¶

C/C++

SNSR_API SnsrRC
snsrTearDown(void);

Parameters and return value

: OK for success, any other value indicates failure.

Releases library-wide resources.

Resets the TrulyNatural SDK library to the initial defaults and releases all library-wide resources.

Calling this function is optional. It is most useful to suppress false positives when tracking down heap leaks with a tool such as Valgrind.

Warning

Do not call this function unless all SDK handles have been released. Doing so will lead to undefined behavior.

config