Thread-safeness and global initialization

neon itself is implemented to be thread-safe (avoiding any use of global state), but relies on the operating system providing a thread-safe resolver interface. Modern operating systems offer the thread-safe getaddrinfo interface, which neon supports; some others implement gethostbyname using thread-local storage.

To allow thread-safe use of the OpenSSL library, the application must register some locking callbacks in accordance with the OpenSSL documentation.

Some platforms and libraries used by neon require global initialization before use; notably:

The ne_sock_init function should be called before any other use of neon to perform any necessary initialization needed for the particular platform.

Namespaces

To avoid possible collisions between names used for symbols and preprocessor macros by an application and the libraries it uses, it is good practice for each library to reserve a particular namespace prefix. An application which ensures it uses no names with these prefixes is then guaranteed to avoid such collisions.

The neon library reserves the use of the namespace prefixes ne_ and NE_. The libraries used by neon may also reserve certain namespaces; collisions between these libraries and a neon-based application will not be detected at compile time, since the underlying library interfaces are not exposed through the neon header files. Such collisions can only be detected at link time, when the linker attempts to resolve symbols. The following list documents some of the namespaces claimed by libraries used by neon; this list may be incomplete.

Argument validation

neon does not attempt to validate that the parameters passed to functions conform to the API (for instance, checking that pointer arguments are not NULL). Any use of the neon API which is not documented to produce a certain behaviour results is said to produce undefined behaviour; it is likely that neon will segfault under these conditions.

URI paths, WebDAV metadata

The path strings passed to any function must be URI-encoded by the application; neon never performs any URI encoding or decoding internally. WebDAV property names and values must be valid UTF-8 encoded Unicode strings.

User interaction

As a pure library interface, neon will never produce output on stdout or stderr; all user interaction is the responsibilty of the application.

Memory handling

neon does not attempt to cope gracefully with an out-of-memory situation; instead, by default, the abort function is called to immediately terminate the process. An application may register a custom function which will be called before abort in such a situation; see ne_oom_callback.

Callbacks and userdata

Whenever a callback is registered, a userdata pointer is also used to allow the application to associate a context with the callback. The userdata is of type void *, allowing any pointer to be used.