Debian Codegraph @

Doc/data/threadsafety.dat

raw
1 # Thread safety annotations for C API functions.
2 #
3 # Each line has the form:
4 # function_name : level
5 #
6 # Where level is one of:
7 # incompatible -- not safe even with external locking
8 # compatible -- safe if the caller serializes all access with external locks
9 # distinct -- safe on distinct objects without external synchronization
10 # shared -- safe for concurrent use on the same object
11 # atomic -- atomic
12 #
13 # Lines beginning with '#' are ignored.
14 # The function name must match the C domain identifier used in the documentation.
15
16 # Synchronization primitives (Doc/c-api/synchronization.rst)
17 PyMutex_Lock:atomic:
18 PyMutex_Unlock:atomic:
19 PyMutex_IsLocked:atomic:
20
21
22 # Dictionary objects (Doc/c-api/dict.rst)
23
24 # Type checks - read ob_type pointer, always safe
25 PyDict_Check:atomic:
26 PyDict_CheckExact:atomic:
27
28 # Creation - pure allocation, no shared state
29 PyDict_New:atomic:
30
31 # Lock-free lookups - use _Py_dict_lookup_threadsafe(), no locking.
32 # Atomic with simple types.
33 PyDict_Contains:shared:
34 PyDict_ContainsString:atomic:
35 PyDict_GetItemRef:shared:
36 PyDict_GetItemStringRef:atomic:
37 PyDict_Size:atomic:
38 PyDict_GET_SIZE:atomic:
39
40 # Borrowed-reference lookups - lock-free dict access but returned
41 # borrowed reference is unsafe in free-threaded builds without
42 # external synchronization
43 PyDict_GetItem:compatible:
44 PyDict_GetItemWithError:compatible:
45 PyDict_GetItemString:compatible:
46 PyDict_SetDefault:compatible:
47
48 # Iteration - no locking; returns borrowed refs
49 PyDict_Next:compatible:
50
51 # Single-item mutations - protected by per-object critical section
52 PyDict_SetItem:shared:
53 PyDict_SetItemString:atomic:
54 PyDict_DelItem:shared:
55 PyDict_DelItemString:atomic:
56 PyDict_SetDefaultRef:shared:
57 PyDict_Pop:shared:
58 PyDict_PopString:atomic:
59
60 # Bulk reads - hold per-object lock for duration
61 PyDict_Clear:atomic:
62 PyDict_Copy:atomic:
63 PyDict_Keys:atomic:
64 PyDict_Values:atomic:
65 PyDict_Items:atomic:
66
67 # Merge/update - lock target dict; also lock source when it is a dict
68 PyDict_Update:shared:
69 PyDict_Merge:shared:
70 PyDict_MergeFromSeq2:shared:
71
72 # Watcher registration - no synchronization on interpreter state
73 PyDict_AddWatcher:compatible:
74 PyDict_ClearWatcher:compatible:
75
76 # Per-dict watcher tags - non-atomic RMW on _ma_watcher_tag;
77 # safe on distinct dicts only
78 PyDict_Watch:distinct:
79 PyDict_Unwatch:distinct:
80
81
82 # List objects (Doc/c-api/list.rst)
83
84 # Type checks - read ob_type pointer, always safe
85 PyList_Check:atomic:
86 PyList_CheckExact:atomic:
87
88 # Creation - pure allocation, no shared state
89 PyList_New:atomic:
90
91 # Size - uses atomic load on free-threaded builds
92 PyList_Size:atomic:
93 PyList_GET_SIZE:atomic:
94
95 # Strong-reference lookup - lock-free with atomic ops
96 PyList_GetItemRef:atomic:
97
98 # Borrowed-reference lookups - no locking; returned borrowed
99 # reference is unsafe in free-threaded builds without
100 # external synchronization
101 PyList_GetItem:compatible:
102 PyList_GET_ITEM:compatible:
103
104 # Single-item mutations - hold per-object lock for duration;
105 # appear atomic to lock-free readers
106 PyList_SetItem:atomic:
107 PyList_Append:atomic:
108
109 # Insert - protected by per-object critical section; shifts
110 # elements so lock-free readers may observe intermediate states
111 PyList_Insert:shared:
112
113 # Initialization macro - no synchronization; normally only used
114 # to fill in new lists where there is no previous content
115 PyList_SET_ITEM:compatible:
116
117 # Bulk operations - hold per-object lock for duration
118 PyList_GetSlice:atomic:
119 PyList_AsTuple:atomic:
120 PyList_Clear:atomic:
121
122 # Reverse - protected by per-object critical section; swaps
123 # elements so lock-free readers may observe intermediate states
124 PyList_Reverse:shared:
125
126 # Slice assignment - lock target list; also lock source when it
127 # is a list
128 PyList_SetSlice:shared:
129
130 # Sort - per-object lock held; the list is emptied before sorting
131 # so other threads may observe an empty list, but they won't see the
132 # intermediate states of the sort
133 PyList_Sort:shared:
134
135 # Extend - lock target list; also lock source when it is a
136 # list, set, or dict
137 PyList_Extend:shared:
138
139 # Creation - pure allocation, no shared state
140 PyBytes_FromString:atomic:
141 PyBytes_FromStringAndSize:atomic:
142 PyBytes_DecodeEscape:atomic:
143
144 # Creation from formatting C primitives - pure allocation, no shared state
145 PyBytes_FromFormat:atomic:
146 PyBytes_FromFormatV:atomic:
147
148 # Creation from object - uses buffer protocol so may call arbitrary code;
149 # safe as long as the buffer is not mutated by another thread during the operation
150 PyBytes_FromObject:shared:
151
152 # Size - uses atomic load on free-threaded builds
153 PyBytes_Size:atomic:
154 PyBytes_GET_SIZE:atomic:
155
156 # Raw data - no locking; mutating it is unsafe if the bytes object is shared between threads
157 PyBytes_AsString:compatible:
158 PyBytes_AS_STRING:compatible:
159 PyBytes_AsStringAndSize:compatible:
160
161 # Concatenation - uses buffer protocol; safe as long as buffer is not mutated by another thread during the operation
162 PyBytes_Concat:shared:
163 PyBytes_ConcatAndDel:shared:
164 PyBytes_Join:shared:
165
166 # Resizing - safe if the object is unique
167 _PyBytes_Resize:distinct:
168
169 # Repr - atomic as bytes are immutable
170 PyBytes_Repr:atomic:
171
172 # Creation from object - may call arbitrary code
173 PyByteArray_FromObject:shared:
174
175 # Creation - pure allocation, no shared state
176 PyByteArray_FromStringAndSize:atomic:
177
178 # Concatenation - uses buffer protocol; safe as long as buffer is not mutated by another thread during the operation
179 PyByteArray_Concat:shared:
180
181 # Size - uses atomic load on free-threaded builds
182 PyByteArray_Size:atomic:
183 PyByteArray_GET_SIZE:atomic:
184
185 # Raw data - no locking; mutating it is unsafe if the bytearray object is shared between threads
186 PyByteArray_AsString:compatible:
187 PyByteArray_AS_STRING:compatible:
188
189 # Creation - may iterate the iterable argument, calling arbitrary code.
190 # Atomic for sets, frozensets, dicts, and frozendicts.
191 PySet_New:shared:
192 PyFrozenSet_New:shared:
193
194 # Size - uses atomic load on free-threaded builds
195 PySet_Size:atomic:
196 PySet_GET_SIZE:atomic:
197
198 # Contains - lock-free, atomic with simple types
199 PySet_Contains:shared:
200
201 # Mutations - hold per-object lock for duration
202 # atomic with simple types
203 PySet_Add:shared:
204 PySet_Discard:shared:
205
206 # Pop - hold per-object lock for duration
207 PySet_Pop:atomic:
208
209 # Clear - empties the set before clearing
210 PySet_Clear:atomic:
211
212 # Capsule objects (Doc/c-api/capsule.rst)
213
214 # Type check - read ob_type pointer, always safe
215 PyCapsule_CheckExact:atomic:
216
217 # Creation - pure allocation, no shared state
218 PyCapsule_New:atomic:
219
220 # Validation - reads pointer and name fields; safe on distinct objects
221 PyCapsule_IsValid:distinct:
222
223 # Getters - read struct fields; safe on distinct objects but
224 # concurrent access to the same capsule requires external synchronization
225 PyCapsule_GetPointer:distinct:
226 PyCapsule_GetName:distinct:
227 PyCapsule_GetDestructor:distinct:
228 PyCapsule_GetContext:distinct:
229
230 # Setters - write struct fields; safe on distinct objects but
231 # concurrent access to the same capsule requires external synchronization
232 PyCapsule_SetPointer:distinct:
233 PyCapsule_SetName:distinct:
234 PyCapsule_SetDestructor:distinct:
235 PyCapsule_SetContext:distinct:
236
237 # Import - looks up a capsule from a module attribute and
238 # calls PyCapsule_GetPointer; may call arbitrary code
239 PyCapsule_Import:compatible: