NAME

       coap_locking, coap_lock_init, coap_lock_lock, coap_lock_unlock, 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(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.

SEE ALSO

       coap_supported(3)

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_locking 4.3.5                                 08/25/2025                                    COAP_LOCKING(3)