COAP_LOCKING(3)

📦
version 4.3.5b · 3 versions
, in alpine 3.24

COAP_LOCKING(3) 💅

okay so this is the libcoap Manual page for coap_locking, and bestie, we're about to get deep into thread-safe locking. buckle up 🎀

✨ 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, coap_lock_specific_lock, coap_lock_specific_unlock, coap_lock_specific_callback_release — literally all the ways to work with CoAP thread safe locking 🫶

🌸 SYNOPSIS 🌸

#include <coap3/coap.h>

void coap_lock_init(coap_lock_t *lock);

void coap_lock_lock(coap_code_t failed_statement);

void coap_lock_unlock(void);

void coap_lock_check_locked(void);

void coap_lock_callback(coap_func_t callback_function);

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

void coap_lock_callback_release( coap_func_t callback_function_,
coap_code_t failed_statement);

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

void coap_lock_invert(coap_func_t locking_function, coap_code_t
failed_statement);

void coap_lock_specific_lock(coap_lock_t *lock, coap_code_t
failed_statement);

void coap_lock_specific_unlock(coap_lock_t *lock);

void coap_lock_specific_callback_release(coap_lock_t *lock, coap_func_t
callback_function_, coap_code_t failed_statement);

so about the (D)TLS situation 👀 for specific (D)TLS library support, you 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 and you get the default (D)TLS library support. slay 💅

💖 DESCRIPTION 💖

this man page is all about the locking support that makes libcoap thread safe. heads up bestie: usage is internal to the libcoap library. it's giving backstage pass only 🎟️

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

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. like, do not do that. periodt 💀

likewise, callback_function is the call-back handler function with all of its parameters. all of them. every single one 🙈

several definitions can be defined with configure or cmake. these are:

  • COAP_THREAD_SAFE — if set, libcoap does internal 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. trade-offs, bestie 😭
  • 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. it's giving self-awareness ✨

normally locking is done at the global_lock level for the Public API functions where appropriate, apart from call-backs to request handler functions where specific structures may get locked to make the call-back thread safe. iykyk 🔥

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. be so serious about this one 🧚

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. cozy 🫶

coap_lock_callback_release() (or coap_lock_callback_ret_release()) unlocks global_lock when calling app call-back. this allows the app call-back to go off and do other slow/blocking activity. any app call-back calls to a Public API then locks up global_lock before proceding. go take your little break, you've earned it 💅

coap_lock_specific_callback_release() acts as coap_lock_callback_release(), but allows additional locks to be set before doing the call-back, and then unlocking them after the call-back return. extra ✨

any libcoap code that runs with global_lock locked should not call a Public API, but call the _lkd equivalent (if available). this is the rule and we do not break it 🚨

🔥 FUNCTIONS 🔥

Function: coap_lock_init()

the coap_lock_init() function is used to initialize the specified lock structure. setting the stage, main character energy 👑

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. no pressure 🔒

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. sharing is caring 💖

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 API is getting called with global_lock locked. vibe check on the lock 🔍

Function: coap_lock_callback()

the coap_lock_callback() function is used whenever a call-back 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 call-back, the lock in global_lock is suitably restored. callback_function is the call-back handler to be called, along with all of the appropriate parameters. it's giving ✨controlled chaos✨

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 call-back handler function in return_value. and it returns something. obsessed 🎀

Function: coap_lock_callback_release()

the coap_lock_callback_release() function is used whenever a call-back 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 call-back, 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 call-back handler to be called, along with all of the appropriate parameters. watch that re-lock 👀

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 call-back handler function in return_value. two-for-one 🍓

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. it's giving upside-down, but make it threads 🙃

Function: coap_lock_specific_lock()

the coap_lock_specific_lock() function is used to lock the specified lock in the appropriate structure from multiple thread access. if the locking fails for any reason, then failed_statement will get executed. specific lock, specific vibe 🔐

Function: coap_lock_specific_unlock()

the coap_lock_specific_unlock() function is used to unlock the specified lock so that another thread can access the appropriate structure. releasing it back into the wild 🦋

Function: coap_lock_specific_callback_release()

the coap_lock_specific_callback_release() function is used whenever a call-back 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 call-back, 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 call-back handler to be called, along with all of the appropriate parameters. lock will get locked before entry to the call-back and unlocked on return. lock can be recursively locked by the same thread. go off, same thread 👑

🦋 SEE ALSO 🦋

🌈 FURTHER INFORMATION 🌈

see

"RFC7252: The Constrained Application Protocol (CoAP)"

for further information. required reading, ngl 📚

💀 BUGS 💀

please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs. we wanna know 😭

please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. fixes are iconic, send them in 🫶

👑 AUTHORS 👑

the libcoap project <libcoap-developers@lists.sourceforge.net> 💌

and that's the whole page bestie!! this was coap_locking 4.3.5b, dated 04/28/2026 — go forth and lock responsibly, ily, mwah 💅✨🎀

📦 where this page comes from