coap_locking

NAME

coap_locking, coap_lock_init, coap_lock_lock, coap_lock_unlock, coap_lock_being_freed, coap_lock_check_locked, coap_lock_callback, coap_lock_callback_release, coap_lock_callback_ret, coap_lock_callback_ret_release, coap_lock_invert - Work with CoAP thread safe locking

SYNOPSIS

#include <coap3/coap.h>

void coap_lock_init(coap_context_t *context);

void coap_lock_lock(coap_context_t *context, coap_code_t failed_statement);

void coap_lock_unlock(coap_context_t *context);

void coap_lock_being_freed(coap_context_t *context, coap_code_t failed_statement);

void coap_lock_check_locked(coap_context_t *context);

void coap_lock_callback(coap_context_t *context, coap_func_t callback_function);

void coap_lock_callback_ret(void *return_value, coap_context_t *context, coap_func_t callback_function, coap_code_t failed_statement);

void coap_lock_callback_release(coap_context_t *context, coap_func_t callback_function_, coap_code_t failed_statement);

void coap_lock_callback_ret_release(void *return_value, coap_context_t *context, coap_func_t callback_function, coap_code_t failed_statement);

void coap_lock_invert(coap_context_t *context, coap_func_t locking_function, coap_code_t failed_statement);

For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls, -lcoap-3-wolfssl or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default (D)TLS library support.

DESCRIPTION

This man page focuses on the locking support provided for making libcoap thread safe. Usage is internal to libcoap.

The functions are actually macros which create different code depending on what levels of locking has been configured. Locking uses coap_mutex_() functions.

So, failed_statement is the C code to execute if the locking fails for any reason. This should only happen when an another thread has called coap_free_context(3). This code should prevent execution of the following code that would have been under the lock protection and certainly not cause the corresponding coap_lock_unlock() function to be called.

Likewise, callback_function is the callback handler function with all of its parameters.

Several definitions can be defined with configure or cmake. These are

COAP_THREAD_SAFE If set, simply does locking at the appropriate places. If not set, then no locking takes place, the code is faster (no locking code), but not multi-thread access safe.

COAP_THREAD_RECURSIVE_CHECK If set, and COAP_THREAD_SAFE is set, checks that if a lock is locked, it reports that the same lock is being (re-)locked.

Currently, locking is only done at the context level for the Public API functions where appropriate. Per session was also considered, but things became complicated with one thread locking context / session and another thread trying to lock session / context in a different order.

In principal, libcoap code internally should only unlock context when waiting on a select() or equivalent, or when calling a request handler, and then lock up again on function return. Any other unlock - app call-back - lock needs to be carefully analyzed as to any potential issues being created by the app call-back if it calls any Public API, updating any data that is relied on after lock takes place.

coap_lock_callback() (or coap_lock_callback_ret()) wrapper leaves the context locked when calling app call-back, but allows the app call-back to call a Public API when in the locked state.

coap_lock_callback_release() (or coap_lock_callback_ret_release()) unlocks context when calling app call-back. The allows the app call-back to go off and do other slow/blocking activity. Any calls to a Public API then locks up context before preceding.

Any libcoap code that runs with context locked should not call a Public API, but call the _lkd equivalent (if available).

FUNCTIONS

Function: coap_lock_init()

The coap_lock_init() function is used to initialize the lock structure in the context structure.

Function: coap_lock_lock()

The coap_lock_lock() function is used to lock context from multiple thread access. If the locking fails for any reason, then failed_statement will get executed.

Function: coap_lock_unlock()

The coap_lock_unlock() function is used to unlock context so that another thread can access context and the underlying structures.

Function: coap_lock_being_freed()

The coap_lock_being_freed() function is used to lock context when context and all the underlying structures are going to be released (called from coap_free_context(3)). Any subsequent call to coap_lock_lock() by another thread will fail. If this locking fails for any reason, then failed_statement will get executed.

Function: coap_lock_check_lock()

The coap_lock_check_lock() function is used to check the internal version (potentially has _locked appended in the name) of a public AP is getting called with context locked.

Function: coap_lock_callback()

The coap_lock_callback() function is used whenever a callback handler is getting called, instead of calling the function directly. The lock information in context is updated so that if a public API is called from within the handler, recursive locking is enabled for that particular thread. On return from the callback, the lock in context is suitably restored. callback_function is the callback handler to be called, along with all of the appropriate parameters.

Function: coap_lock_callback_ret()

The coap_lock_callback_ret() function is similar to coap_lock_callback(), but in addition, it updates the return value from the callback handler function in return_value.

Function: coap_lock_callback_release()

The coap_lock_callback_release() function is used whenever a callback handler is getting called, instead of calling the function directly. The lock information in context is released so that if a public API is called from within the handler, it can do its own lock. The intent here is to reduce lock contention. On return from the callback, the lock in context is re-locked, but if there is a failure in re-locking, failed_statement is executed. callback_function is the callback handler to be called, along with all of the appropriate parameters.

Function: coap_lock_callback_ret_release()

The coap_lock_callback_ret_release() function is similar to coap_lock_callback_release(), but in addition, it updates the return value from the callback handler function in return_value.

Function: coap_lock_invert()

The coap_lock_invert() function is used where there are other locking mechanisms external to libcoap and the locking order needs to be external lock, then libcoap code locked. context already needs to be locked before calling coap_lock_invert(). If coap_lock_invert() is called, then context will get unlocked, locking_function with all of its parameters called, and then context re-locked. If for any reason locking fails, then failed_statement will get executed.

FURTHER INFORMATION

See

"RFC7252: The Constrained Application Protocol (CoAP)"

for further information.

BUGS

Please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs.

Please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes.

AUTHORS

The libcoap project <libcoap-developers@lists.sourceforge.net>

coap_lock_being_freed(3)