| 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); |