1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
# Locking in Picolibc
Picolibc uses locking and atomics to protect global state between
re-entrant calls. The amount of global state protected by locks has
been minimized so that applications can avoid needing them for
most common operations.
## Where Picolibc uses locking
Picolibc has a single global lock for APIs that share global
data. That includes:
* malloc family
* onexit/atexit
* arc4random
* getenv/setenv
* functions using timezones (localtime, et al)
* legacy stdio globals
Tinystdio (the default stdio) uses per-file locks for the buffered
POSIX file backend, but it doesn't require any locks for the bulk of
the implementation. You can enable POSIX-compliant locking in
tinystdio with -Dstdio-locking-true. That will prevent I/O from stdio
operations from interleaving between threads.
The legacy stdio implementation is full of locking, and has per-file
locks for every operation.
## Where Picolibc uses atomics
Picolibc also uses atomics to protect other data structures while
avoiding the need for locking:
* getc/ungetc in tinystdio
* signal handling
## Configuration options controlling locking
There is only one configuration option related to locking:
* single-thread. When 'true', all locking operations are elided from
the library. Re-entrant usage of the library will result in
undefined behavior.
Atomics will still be used as defined above, so disabling locking
will still allow safe re-entrancy for those parts of the library.
## Retargetable locking API
When -Dsingle-thread is not selected, Picolibc uses the following
interface. Picolibc provides stubs for all of these functions that do
not perform locking, so a single threaded application can still use a
library compiled to enable locking. An application needing locking
would provide a real implementation of the API.
This API requires recursive mutexes; if the underlying implementation
only provides non-recursive mutexes, a suitable wrapper implementing
recursive mutexes will be required for the recursive APIs. All APIs
involving recursive mutexes contain `recursive` in their names.
In this section, *the locking implementation* refers to the external
implementation of this API.
When implementing this API every function and variable must be
defined. If not, the application will fail to link as the default
implementation will be used to satisfy any missing symbol and other
symbols will collide with the application versions.
### `struct __lock; typedef struct __lock *_LOCK_T;`
This struct is only referenced by picolibc, not defined. The
locking implementation may define it as necessary.
### `extern struct __lock __libc_recursive_mutex;`
This is the single global lock used for most libc locking. It must be
defined in the locking implementation in such a way as to not require
any runtime initialization.
### `void __retarget_lock_init(_LOCK_T *lock)`
This is used by tinystdio to initialize the lock in a newly allocated
FILE.
### `void __retarget_lock_acquire(_LOCK_T lock)`
Acquire a non-recursive mutex. A thread will only acquire the mutex once.
### `void __retarget_lock_release(_LOCK_T lock)`
Release a non-recursive mutex.
### `void __retarget_lock_close(_LOCK_T lock)`
This is used by tinystdio to de-initialize a lock from a FILE which is
being closed.
### `void __retarget_lock_init_recursive(_LOCK_T *lock)`
This is used by the legacy stdio code to initialize the lock in a
newly allocated FILE.
### `void __retarget_lock_acquire_recursive(_LOCK_T lock)`
Acquire a recursive mutex. A thread may acquire a recursive
mutex multiple times.
### `void __retarget_lock_release_recursive(_LOCK_T lock)`
Release a recursive mutex. A thread thread must release the mutex as
many times as it has acquired it before the mutex is unlocked.
### `void __retarget_lock_close_recursive(_LOCK_T lock)`
This is used by the legacy stdio code to de-initialize a lock from a
FILE which is being closed.
|
