Concepts

Error Handling

The API handles errors using return codes. Valid return codes are defined JaniceError. In general, it is assumed that new memory is only allocated if a function returns JANICE_SUCCESS. Therefore, implementors are REQUIRED to deallocate any memory allocated during a function call if that function returns an error.

Memory Allocation

The API often passes unallocated pointers to functions for the implementor to allocate appropriately. This is indicated if the type of a function input is JaniceObject**, or in the case of a utility typedef JaniceTypedef*. It is considered a best practice for unallocated pointers to be initialized to NULL before they are passed to a function, but this is not guaranteed. It is the responsibility of the users of the API to ensure that pointers do not point to valid data before they are passed to functions in which they are modified, as this would cause memory leaks.

Thread Safety

All functions are marked one of:

Thread Safe

Can be called simultaneously from multiple threads, even when the invocations use shared data.

Reentrant

Can be called simultaneously from multiple threads, but only if each invocation uses its own data.

Thread Unsafe

Can not be called simultaneously from multiple threads.

Compiling

Define JANICE_LIBRARY during compilation to export JanICE symbols.

Versioning

This API follows the semantic versioning paradigm. Each released iteration is tagged with a major.minor.patch version. A change in the major version indicates a breaking change. A change in the minor version indicates a backwards-compatible change. A change in the patch version indicates a backwards-compatible bug fix.