Debian Codegraph @

Include/cpython/dictobject.h

raw
1 #ifndef Py_CPYTHON_DICTOBJECT_H
2 # error "this header file must not be included directly"
3 #endif
4
5 typedef struct _dictkeysobject PyDictKeysObject;
6 typedef struct _dictvalues PyDictValues;
7
8 /* The ma_values pointer is NULL for a combined table
9 * or points to an array of PyObject* for a split table
10 */
11 typedef struct {
12 PyObject_HEAD
13
14 /* Number of items in the dictionary */
15 Py_ssize_t ma_used;
16
17 /* This is a private field for CPython's internal use.
18 * Bits 0-7 are for dict watchers.
19 * Bits 8-11 are for the watched mutation counter (used by tier2 optimization)
20 * Bits 12-31 are currently unused
21 * Bits 32-63 are a unique id in the free threading build (used for per-thread refcounting)
22 */
23 uint64_t _ma_watcher_tag;
24
25 PyDictKeysObject *ma_keys;
26
27 /* If ma_values is NULL, the table is "combined": keys and values
28 are stored in ma_keys.
29
30 If ma_values is not NULL, the table is split:
31 keys are stored in ma_keys and values are stored in ma_values */
32 PyDictValues *ma_values;
33 } PyDictObject;
34
35 PyAPI_FUNC(PyObject *) _PyDict_GetItem_KnownHash(PyObject *mp, PyObject *key,
36 Py_hash_t hash);
37 // PyDict_GetItemStringRef() can be used instead
38 Py_DEPRECATED(3.14) PyAPI_FUNC(PyObject *) _PyDict_GetItemStringWithError(PyObject *, const char *);
39 PyAPI_FUNC(PyObject *) PyDict_SetDefault(
40 PyObject *mp, PyObject *key, PyObject *defaultobj);
41
42 // Inserts `key` with a value `default_value`, if `key` is not already present
43 // in the dictionary. If `result` is not NULL, then the value associated
44 // with `key` is returned in `*result` (either the existing value, or the now
45 // inserted `default_value`).
46 // Returns:
47 // -1 on error
48 // 0 if `key` was not present and `default_value` was inserted
49 // 1 if `key` was present and `default_value` was not inserted
50 PyAPI_FUNC(int) PyDict_SetDefaultRef(PyObject *mp, PyObject *key, PyObject *default_value, PyObject **result);
51
52 /* Get the number of items of a dictionary. */
53 static inline Py_ssize_t PyDict_GET_SIZE(PyObject *op) {
54 PyDictObject *mp;
55 assert(PyDict_Check(op));
56 mp = _Py_CAST(PyDictObject*, op);
57 #ifdef Py_GIL_DISABLED
58 return _Py_atomic_load_ssize_relaxed(&mp->ma_used);
59 #else
60 return mp->ma_used;
61 #endif
62 }
63 #define PyDict_GET_SIZE(op) PyDict_GET_SIZE(_PyObject_CAST(op))
64
65 PyAPI_FUNC(int) PyDict_ContainsString(PyObject *mp, const char *key);
66
67 PyAPI_FUNC(PyObject *) _PyDict_NewPresized(Py_ssize_t minused);
68
69 PyAPI_FUNC(int) PyDict_Pop(PyObject *dict, PyObject *key, PyObject **result);
70 PyAPI_FUNC(int) PyDict_PopString(PyObject *dict, const char *key, PyObject **result);
71
72 // Use PyDict_Pop() instead
73 Py_DEPRECATED(3.14) PyAPI_FUNC(PyObject *) _PyDict_Pop(
74 PyObject *dict,
75 PyObject *key,
76 PyObject *default_value);
77
78 /* Dictionary watchers */
79
80 #define PY_FOREACH_DICT_EVENT(V) \
81 V(ADDED) \
82 V(MODIFIED) \
83 V(DELETED) \
84 V(CLONED) \
85 V(CLEARED) \
86 V(DEALLOCATED)
87
88 typedef enum {
89 #define PY_DEF_EVENT(EVENT) PyDict_EVENT_##EVENT,
90 PY_FOREACH_DICT_EVENT(PY_DEF_EVENT)
91 #undef PY_DEF_EVENT
92 } PyDict_WatchEvent;
93
94 // Callback to be invoked when a watched dict is cleared, dealloced, or modified.
95 // In clear/dealloc case, key and new_value will be NULL. Otherwise, new_value will be the
96 // new value for key, NULL if key is being deleted.
97 typedef int(*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject* dict, PyObject* key, PyObject* new_value);
98
99 // Register/unregister a dict-watcher callback
100 PyAPI_FUNC(int) PyDict_AddWatcher(PyDict_WatchCallback callback);
101 PyAPI_FUNC(int) PyDict_ClearWatcher(int watcher_id);
102
103 // Mark given dictionary as "watched" (callback will be called if it is modified)
104 PyAPI_FUNC(int) PyDict_Watch(int watcher_id, PyObject* dict);
105 PyAPI_FUNC(int) PyDict_Unwatch(int watcher_id, PyObject* dict);