SYNOPSIS
#include <coap3/coap.h>
void coap_lock_init(void);
void coap_lock_lock(coap_context_t *context, coap_code_t failed_statement);
void coap_lock_unlock(coap_context_t *context);
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 library.
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 coap_cleanup(3)
has been called, or coap_startup(3) has not been called. 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 global_lock level for the Public API
functions where appropriate.
In principal, libcoap code internally should only unlock global_lock 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
global_lock 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
global_lock 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
global_lock before preceding.
Any libcoap code that runs with global_lock 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 global_lock lock
structure.
Function: coap_lock_lock()
The coap_lock_lock() function is used to lock global_lock 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 global_lock so that another
thread can access libcoap and the underlying structures.
Function: coap_lock_check_lock()
The coap_lock_check_lock() function is used to check the internal version
(potentially has _lkd appended in the name) of a public AP is getting called
with global_lock 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 global_lock 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 global_lock 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 global_lock 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 global_lock 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. global_lock already needs to be locked before calling
coap_lock_invert(). If coap_lock_invert() is called, then global_lock will
get unlocked, locking_function with all of its parameters called, and then
global_lock re-locked. If for any reason locking fails, then failed_statement
will get executed.
