threadsafety.dat

# Thread safety annotations for C API functions.
#
# Each line has the form:
#   function_name : level
#
# Where level is one of:
#   incompatible -- not safe even with external locking
#   compatible   -- safe if the caller serializes all access with external locks
#   distinct     -- safe on distinct objects without external synchronization
#   shared       -- safe for concurrent use on the same object
#   atomic       -- atomic
#
# Lines beginning with '#' are ignored.
# The function name must match the C domain identifier used in the documentation.

# Synchronization primitives (Doc/c-api/synchronization.rst)
PyMutex_Lock:atomic:
PyMutex_Unlock:atomic:
PyMutex_IsLocked:atomic:

# Dictionary objects (Doc/c-api/dict.rst)

# Type checks - read ob_type pointer, always safe
PyDict_Check:atomic:
PyDict_CheckExact:atomic:

# Creation - pure allocation, no shared state
PyDict_New:atomic:

# Lock-free lookups - use _Py_dict_lookup_threadsafe(), no locking
PyDict_Contains:atomic:
PyDict_ContainsString:atomic:
PyDict_GetItemRef:atomic:
PyDict_GetItemStringRef:atomic:
PyDict_Size:atomic:
PyDict_GET_SIZE:atomic:

# Borrowed-reference lookups - lock-free dict access but returned
# borrowed reference is unsafe in free-threaded builds without
# external synchronization
PyDict_GetItem:compatible:
PyDict_GetItemWithError:compatible:
PyDict_GetItemString:compatible:
PyDict_SetDefault:compatible:

# Iteration - no locking; returns borrowed refs
PyDict_Next:compatible:

# Single-item mutations - protected by per-object critical section
PyDict_SetItem:shared:
PyDict_SetItemString:shared:
PyDict_DelItem:shared:
PyDict_DelItemString:shared:
PyDict_SetDefaultRef:shared:
PyDict_Pop:shared:
PyDict_PopString:shared:

# Bulk reads - hold per-object lock for duration
PyDict_Clear:atomic:
PyDict_Copy:atomic:
PyDict_Keys:atomic:
PyDict_Values:atomic:
PyDict_Items:atomic:

# Merge/update - lock target dict; also lock source when it is a dict
PyDict_Update:shared:
PyDict_Merge:shared:
PyDict_MergeFromSeq2:shared:

# Watcher registration - no synchronization on interpreter state
PyDict_AddWatcher:compatible:
PyDict_ClearWatcher:compatible:

# Per-dict watcher tags - non-atomic RMW on _ma_watcher_tag;
# safe on distinct dicts only
PyDict_Watch:distinct:
PyDict_Unwatch:distinct: