python3.13/cpython/dictobject.h

0001 #ifndef Py_CPYTHON_DICTOBJECT_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005 typedef struct _dictkeysobject PyDictKeysObject;
0006 typedef struct _dictvalues PyDictValues;
0007
0008 /* The ma_values pointer is NULL for a combined table
0009  * or points to an array of PyObject* for a split table
0010  */
0011 typedef struct {
0012     PyObject_HEAD
0013
0014     /* Number of items in the dictionary */
0015     Py_ssize_t ma_used;
0016
0017     /* Dictionary version: globally unique, value change each time
0018        the dictionary is modified */
0019 #ifdef Py_BUILD_CORE
0020     /* Bits 0-7 are for dict watchers.
0021      * Bits 8-11 are for the watched mutation counter (used by tier2 optimization)
0022      * The remaining bits (12-63) are the actual version tag. */
0023     uint64_t ma_version_tag;
0024 #else
0025     Py_DEPRECATED(3.12) uint64_t ma_version_tag;
0026 #endif
0027
0028     PyDictKeysObject *ma_keys;
0029
0030     /* If ma_values is NULL, the table is "combined": keys and values
0031        are stored in ma_keys.
0032
0033        If ma_values is not NULL, the table is split:
0034        keys are stored in ma_keys and values are stored in ma_values */
0035     PyDictValues *ma_values;
0036 } PyDictObject;
0037
0038 PyAPI_FUNC(PyObject *) _PyDict_GetItem_KnownHash(PyObject *mp, PyObject *key,
0039                                                  Py_hash_t hash);
0040 PyAPI_FUNC(PyObject *) _PyDict_GetItemStringWithError(PyObject *, const char *);
0041 PyAPI_FUNC(PyObject *) PyDict_SetDefault(
0042     PyObject *mp, PyObject *key, PyObject *defaultobj);
0043
0044 // Inserts `key` with a value `default_value`, if `key` is not already present
0045 // in the dictionary.  If `result` is not NULL, then the value associated
0046 // with `key` is returned in `*result` (either the existing value, or the now
0047 // inserted `default_value`).
0048 // Returns:
0049 //   -1 on error
0050 //    0 if `key` was not present and `default_value` was inserted
0051 //    1 if `key` was present and `default_value` was not inserted
0052 PyAPI_FUNC(int) PyDict_SetDefaultRef(PyObject *mp, PyObject *key, PyObject *default_value, PyObject **result);
0053
0054 /* Get the number of items of a dictionary. */
0055 static inline Py_ssize_t PyDict_GET_SIZE(PyObject *op) {
0056     PyDictObject *mp;
0057     assert(PyDict_Check(op));
0058     mp = _Py_CAST(PyDictObject*, op);
0059 #ifdef Py_GIL_DISABLED
0060     return _Py_atomic_load_ssize_relaxed(&mp->ma_used);
0061 #else
0062     return mp->ma_used;
0063 #endif
0064 }
0065 #define PyDict_GET_SIZE(op) PyDict_GET_SIZE(_PyObject_CAST(op))
0066
0067 PyAPI_FUNC(int) PyDict_ContainsString(PyObject *mp, const char *key);
0068
0069 PyAPI_FUNC(PyObject *) _PyDict_NewPresized(Py_ssize_t minused);
0070
0071 PyAPI_FUNC(int) PyDict_Pop(PyObject *dict, PyObject *key, PyObject **result);
0072 PyAPI_FUNC(int) PyDict_PopString(PyObject *dict, const char *key, PyObject **result);
0073 PyAPI_FUNC(PyObject *) _PyDict_Pop(PyObject *dict, PyObject *key, PyObject *default_value);
0074
0075 /* Dictionary watchers */
0076
0077 #define PY_FOREACH_DICT_EVENT(V) \
0078     V(ADDED)                     \
0079     V(MODIFIED)                  \
0080     V(DELETED)                   \
0081     V(CLONED)                    \
0082     V(CLEARED)                   \
0083     V(DEALLOCATED)
0084
0085 typedef enum {
0086     #define PY_DEF_EVENT(EVENT) PyDict_EVENT_##EVENT,
0087     PY_FOREACH_DICT_EVENT(PY_DEF_EVENT)
0088     #undef PY_DEF_EVENT
0089 } PyDict_WatchEvent;
0090
0091 // Callback to be invoked when a watched dict is cleared, dealloced, or modified.
0092 // In clear/dealloc case, key and new_value will be NULL. Otherwise, new_value will be the
0093 // new value for key, NULL if key is being deleted.
0094 typedef int(*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject* dict, PyObject* key, PyObject* new_value);
0095
0096 // Register/unregister a dict-watcher callback
0097 PyAPI_FUNC(int) PyDict_AddWatcher(PyDict_WatchCallback callback);
0098 PyAPI_FUNC(int) PyDict_ClearWatcher(int watcher_id);
0099
0100 // Mark given dictionary as "watched" (callback will be called if it is modified)
0101 PyAPI_FUNC(int) PyDict_Watch(int watcher_id, PyObject* dict);
0102 PyAPI_FUNC(int) PyDict_Unwatch(int watcher_id, PyObject* dict);