libcoap 4.3.5-develop-ea01661
Loading...
Searching...
No Matches
coap_threadsafe_internal.h
Go to the documentation of this file.
1/*
2 * coap_threadsafe_internal.h -- Mapping of threadsafe functions
3 *
4 * Copyright (C) 2023-2025 Jon Shallow <supjps-libcoap@jpshallow.com>
5 *
6 * SPDX-License-Identifier: BSD-2-Clause
7 *
8 * This file is part of the CoAP library libcoap. Please see README for terms
9 * of use.
10 */
11
24#ifndef COAP_THREADSAFE_INTERNAL_H_
25#define COAP_THREADSAFE_INTERNAL_H_
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31/*
32 * Support thread safe access into libcoap
33 *
34 * Locking at different component levels (i.e context and session) is
35 * problematic in that coap_process_io() needs to lock the context as
36 * it scans for all the sessions and then could lock the session being
37 * processed as well - but context needs to remain locked as a list is
38 * being scanned.
39 *
40 * Then if the session process needs to update context ( e.g. delayqueue),
41 * context needs to be locked. So, if coap_send() is done on a session,
42 * it has to be locked, but a retransmission of a PDU by coap_process_io()
43 * has the context already locked.
44 *
45 * However, when the context is going away (coap_free_context()), other
46 * threads may still be access the lock in what is now freed memory.
47 * A solution (by flagging being freed), worked, but still with a timing
48 * window wen the context was finally de-allocated. Coverity Scan did
49 * not like the solution.
50 *
51 * So the initial support for thread safe is done at global lock level
52 * using global_lock.
53 *
54 * Any public API call needs to potentially lock global_lock.
55 *
56 * If a public API needs thread safe protection, the coap_X() function
57 * locks the global_lock lock, calls the coap_X_lkd() function
58 * that does all the work and on return unlocks the global_lock before
59 * returning to the caller of coap_X(). These coap_X() functions
60 * need COAP_API in their definitions.
61 *
62 * Any internal libcoap calls that are to the public API coap_X() must call
63 * coap_X_lkd() if the calling code is already locked.
64 * [The compiler will throw out a deprecation warning against any internal
65 * libcoap call to a COAP_API labelled function]
66 *
67 * Any call-back into app space must be done by using the coap_lock_callback()
68 * (or coap_lock_callback_ret()) wrapper where the global_lock remains locked.
69 *
70 * Note:
71 * libcoap may call a handler, which may in turn call into libcoap, which may
72 * then call a handler. global_lock will remain locked thoughout this process
73 * by the same thread.
74 *
75 * Alternatively, coap_lock_callback_release() (or
76 * coap_lock_callback_ret_release()), is used where the global_lock is unlocked
77 * for the duration of the call-back. Used for things like a request
78 * handler which could be busy for some time.
79 *
80 * Note: On return from the call-back, the code has to be careful not to
81 * use memory locations that may have been updated in the call-back by
82 * calling a Public API.
83 *
84 * Any wait on select() or equivalent when a thread is waiting on an event
85 * must be preceded by unlock global_lock, and then global_lock re-locked after
86 * return;
87 *
88 * To check for recursive deadlock coding errors, COAP_THREAD_RECURSIVE_CHECK
89 * needs to be defined.
90 *
91 * If thread safe is not enabled, then locking of the global_lock does not take
92 * place.
93 */
94
95#if COAP_THREAD_SAFE
96
97# if COAP_THREAD_RECURSIVE_CHECK
98
99/*
100 * Locking, with deadlock detection
101 */
102typedef struct coap_lock_t {
103 coap_mutex_t mutex;
105 const char *lock_file;
106 unsigned int lock_line;
107 unsigned int unlock_line;
108 const char *unlock_file;
109 const char *callback_file;
110 unsigned int callback_line;
111 unsigned int in_callback;
112 unsigned int lock_count;
114
126void coap_lock_unlock_func(const char *file, int line);
127
141int coap_lock_lock_func(const char *file, int line);
142
159#define coap_lock_lock(failed) do { \
160 if (!coap_lock_lock_func(__FILE__, __LINE__)) { \
161 failed; \
162 } \
163 } while (0)
164
174#define coap_lock_unlock() do { \
175 coap_lock_unlock_func(__FILE__, __LINE__); \
176 } while (0)
177
187#define coap_lock_callback(func) do { \
188 coap_lock_check_locked(); \
189 global_lock.in_callback++; \
190 global_lock.callback_file = __FILE__; \
191 global_lock.callback_line = __LINE__; \
192 func; \
193 global_lock.in_callback--; \
194 } while (0)
195
207#define coap_lock_callback_ret(r,func) do { \
208 coap_lock_check_locked(); \
209 global_lock.in_callback++; \
210 global_lock.callback_file = __FILE__; \
211 global_lock.callback_line = __LINE__; \
212 (r) = func; \
213 global_lock.in_callback--; \
214 } while (0)
215
226#define coap_lock_callback_release(func,failed) do { \
227 coap_lock_check_locked(); \
228 coap_lock_unlock(); \
229 func; \
230 coap_lock_lock(failed); \
231 } while (0)
232
245#define coap_lock_callback_ret_release(r,func,failed) do { \
246 coap_lock_check_locked(); \
247 coap_lock_unlock(); \
248 (r) = func; \
249 coap_lock_lock(failed); \
250 } while (0)
251
252extern coap_lock_t global_lock;
253
254# else /* ! COAP_THREAD_RECURSIVE_CHECK */
255
256/*
257 * Locking, but no deadlock detection
258 */
259typedef struct coap_lock_t {
260 coap_mutex_t mutex;
262 uint32_t in_callback;
263 volatile uint32_t lock_count;
265
275void coap_lock_unlock_func(void);
276
287int coap_lock_lock_func(void);
288
305#define coap_lock_lock(failed) do { \
306 if (!coap_lock_lock_func()) { \
307 failed; \
308 } \
309 } while (0)
310
320#define coap_lock_unlock() do { \
321 coap_lock_unlock_func(); \
322 } while (0)
323
333#define coap_lock_callback(func) do { \
334 coap_lock_check_locked(); \
335 global_lock.in_callback++; \
336 func; \
337 global_lock.in_callback--; \
338 } while (0)
339
351#define coap_lock_callback_ret(r,func) do { \
352 coap_lock_check_locked(); \
353 global_lock.in_callback++; \
354 global_lock.in_callback++; \
355 (r) = func; \
356 global_lock.in_callback--; \
357 } while (0)
358
369#define coap_lock_callback_release(func,failed) do { \
370 coap_lock_check_locked(); \
371 coap_lock_unlock(); \
372 func; \
373 coap_lock_lock(failed); \
374 } while (0)
375
388#define coap_lock_callback_ret_release(r,func,failed) do { \
389 coap_lock_check_locked(); \
390 coap_lock_unlock(); \
391 (r) = func; \
392 coap_lock_lock(failed); \
393 } while (0)
394
395# endif /* ! COAP_THREAD_RECURSIVE_CHECK */
396
400#define coap_lock_init() do { \
401 memset(&global_lock.mutex, 0, sizeof(global_lock.mutex)); \
402 coap_mutex_init(&global_lock.mutex); \
403 } while (0)
404
408#define coap_lock_check_locked() do { \
409 assert(coap_thread_pid == global_lock.pid); \
410 } while (0)
411
424#define coap_lock_invert(alt_lock,failed) do { \
425 coap_lock_check_locked(); \
426 coap_lock_unlock(); \
427 alt_lock; \
428 coap_lock_lock(failed); \
429 } while (0)
430
431extern coap_lock_t global_lock;
432
433#else /* ! COAP_THREAD_SAFE */
434
435/*
436 * No locking - single thread
437 */
439
457#define coap_lock_lock(failed)
458
467#define coap_lock_unlock()
468
474#define coap_lock_init()
475
481#define coap_lock_check_locked() {}
482
494#define coap_lock_callback(func) func
495
509#define coap_lock_callback_ret(r,func) (r) = func
510
523#define coap_lock_callback_release(func,failed) func
524
540#define coap_lock_callback_ret_release(r,func,failed) (r) = func
541
556#define coap_lock_invert(alt_lock,failed) alt_lock
557
558#endif /* ! COAP_THREAD_SAFE */
559
562#ifdef __cplusplus
563}
564#endif
565
566#endif /* COAP_THREADSAFE_INTERNAL_H_ */
int coap_mutex_t
#define coap_thread_pid_t
coap_mutex_t coap_lock_t