/Include/dictobject.h

  1#ifndef Py_DICTOBJECT_H
  2#define Py_DICTOBJECT_H
  3#ifdef __cplusplus
  4extern "C" {
  5#endif
  6
  7
  8struct PySmallPtrSet;
  9
 10/* Dictionary object type -- mapping from hashable object to object */
 11
 12/* The distribution includes a separate file, Objects/dictnotes.txt,
 13   describing explorations into dictionary design and optimization.
 14   It covers typical dictionary use patterns, the parameters for
 15   tuning dictionaries, and several ideas for possible optimizations.
 16*/
 17
 18/*
 19There are three kinds of slots in the table:
 20
 211. Unused.  me_key == me_value == NULL
 22   Does not hold an active (key, value) pair now and never did.  Unused can
 23   transition to Active upon key insertion.  This is the only case in which
 24   me_key is NULL, and is each slot's initial state.
 25
 262. Active.  me_key != NULL and me_key != dummy and me_value != NULL
 27   Holds an active (key, value) pair.  Active can transition to Dummy upon
 28   key deletion.  This is the only case in which me_value != NULL.
 29
 303. Dummy.  me_key == dummy and me_value == NULL
 31   Previously held an active (key, value) pair, but that was deleted and an
 32   active pair has not yet overwritten the slot.  Dummy can transition to
 33   Active upon key insertion.  Dummy slots cannot be made Unused again
 34   (cannot have me_key set to NULL), else the probe sequence in case of
 35   collision would have no way to know they were once active.
 36
 37Note: .popitem() abuses the me_hash field of an Unused or Dummy slot to
 38hold a search finger.  The me_hash field of Unused or Dummy slots has no
 39meaning otherwise.
 40*/
 41
 42/* PyDict_MINSIZE is the minimum size of a dictionary.  This many slots are
 43 * allocated directly in the dict object (in the ma_smalltable member).
 44 * It must be a power of 2, and at least 4.  8 allows dicts with no more
 45 * than 5 active entries to live in ma_smalltable (and so avoid an
 46 * additional malloc); instrumentation suggested this suffices for the
 47 * majority of dicts (consisting mostly of usually-small instance dicts and
 48 * usually-small dicts created to pass keyword arguments).
 49 */
 50#define PyDict_MINSIZE 8
 51
 52typedef struct {
 53	/* Cached hash code of me_key.  Note that hash codes are C longs.
 54	 * We have to use Py_ssize_t instead because dict_popitem() abuses
 55	 * me_hash to hold a search finger.
 56	 */
 57	Py_ssize_t me_hash;
 58	PyObject *me_key;
 59	PyObject *me_value;
 60} PyDictEntry;
 61
 62/*
 63To ensure the lookup algorithm terminates, there must be at least one Unused
 64slot (NULL key) in the table.
 65The value ma_fill is the number of non-NULL keys (sum of Active and Dummy);
 66ma_used is the number of non-NULL, non-dummy keys (== the number of non-NULL
 67values == the number of Active items).
 68To avoid slowing down lookups on a near-full table, we resize the table when
 69it's two-thirds full.
 70*/
 71typedef struct _dictobject PyDictObject;
 72struct _dictobject {
 73	PyObject_HEAD
 74	Py_ssize_t ma_fill;  /* # Active + # Dummy */
 75	Py_ssize_t ma_used;  /* # Active */
 76
 77	/* The table contains ma_mask + 1 slots, and that's a power of 2.
 78	 * We store the mask instead of the size because the mask is more
 79	 * frequently needed.
 80	 */
 81	Py_ssize_t ma_mask;
 82
 83	/* ma_table points to ma_smalltable for small tables, else to
 84	 * additional malloc'ed memory.  ma_table is never NULL!  This rule
 85	 * saves repeated runtime null-tests in the workhorse getitem and
 86	 * setitem calls.
 87	 */
 88	PyDictEntry *ma_table;
 89	PyDictEntry *(*ma_lookup)(PyDictObject *mp, PyObject *key, long hash);
 90	PyDictEntry ma_smalltable[PyDict_MINSIZE];
 91
 92#ifdef WITH_LLVM
 93	/* When the dict changes, tell any dependent code objects that whatever
 94	 * assumptions they may have had about the state of the dict may be
 95	 * invalid. This is used by the LLVM-generated machine code to speed up
 96	 * access to globals and builtins. If ma_watchers is NULL, no code
 97	 * objects depend on this dictionary; this keeps updates to non-globals/
 98	 * non-builtins dicts fast. Use _PyDict_AddWatcher() and 
 99	 * _PyDict_DropWatcher() to modify this.
100	 */
101	struct PySmallPtrSet *ma_watchers;
102#endif
103};
104
105PyAPI_DATA(PyTypeObject) PyDict_Type;
106
107#define PyDict_Check(op) \
108                 PyType_FastSubclass(Py_TYPE(op), Py_TPFLAGS_DICT_SUBCLASS)
109#define PyDict_CheckExact(op) (Py_TYPE(op) == &PyDict_Type)
110
111PyAPI_FUNC(PyObject *) PyDict_New(void);
112PyAPI_FUNC(PyObject *) PyDict_GetItem(PyObject *mp, PyObject *key);
113PyAPI_FUNC(int) PyDict_SetItem(PyObject *mp, PyObject *key, PyObject *item);
114PyAPI_FUNC(int) PyDict_DelItem(PyObject *mp, PyObject *key);
115PyAPI_FUNC(void) PyDict_Clear(PyObject *mp);
116PyAPI_FUNC(int) PyDict_Next(
117	PyObject *mp, Py_ssize_t *pos, PyObject **key, PyObject **value);
118PyAPI_FUNC(int) _PyDict_Next(
119	PyObject *mp, Py_ssize_t *pos, PyObject **key, PyObject **value, long *hash);
120PyAPI_FUNC(PyObject *) PyDict_Keys(PyObject *mp);
121PyAPI_FUNC(PyObject *) PyDict_Values(PyObject *mp);
122PyAPI_FUNC(PyObject *) PyDict_Items(PyObject *mp);
123PyAPI_FUNC(Py_ssize_t) PyDict_Size(PyObject *mp);
124PyAPI_FUNC(PyObject *) PyDict_Copy(PyObject *mp);
125PyAPI_FUNC(int) PyDict_Contains(PyObject *mp, PyObject *key);
126PyAPI_FUNC(int) _PyDict_Contains(PyObject *mp, PyObject *key, long hash);
127PyAPI_FUNC(PyObject *) _PyDict_NewPresized(Py_ssize_t minused);
128
129/* PyDict_Update(mp, other) is equivalent to PyDict_Merge(mp, other, 1). */
130PyAPI_FUNC(int) PyDict_Update(PyObject *mp, PyObject *other);
131
132/* PyDict_Merge updates/merges from a mapping object (an object that
133   supports PyMapping_Keys() and PyObject_GetItem()).  If override is true,
134   the last occurrence of a key wins, else the first.  The Python
135   dict.update(other) is equivalent to PyDict_Merge(dict, other, 1).
136*/
137PyAPI_FUNC(int) PyDict_Merge(PyObject *mp,
138				   PyObject *other,
139				   int override);
140
141/* PyDict_MergeFromSeq2 updates/merges from an iterable object producing
142   iterable objects of length 2.  If override is true, the last occurrence
143   of a key wins, else the first.  The Python dict constructor dict(seq2)
144   is equivalent to dict={}; PyDict_MergeFromSeq(dict, seq2, 1).
145*/
146PyAPI_FUNC(int) PyDict_MergeFromSeq2(PyObject *d,
147					   PyObject *seq2,
148					   int override);
149
150PyAPI_FUNC(PyObject *) PyDict_GetItemString(PyObject *dp, const char *key);
151PyAPI_FUNC(int) PyDict_SetItemString(PyObject *dp, const char *key, PyObject *item);
152PyAPI_FUNC(int) PyDict_DelItemString(PyObject *dp, const char *key);
153
154#ifdef WITH_LLVM
155/* Register the given code object as depending on the state of this dict.
156   The same code object may be registered multiple times without error. Returns
157   -1 on error, 0 on success. */
158PyAPI_FUNC(int) _PyDict_AddWatcher(PyObject *dp, PyCodeObject *code);
159
160/* Unregister the given code object; it is no longer watching this dict for
161   changes. The same dict/code pair may be unregistered multiple times without
162   error. */
163PyAPI_FUNC(void) _PyDict_DropWatcher(PyObject *dp, PyCodeObject *code);
164
165/* Internal helper methods used for testing the dict-watching system. */
166PyAPI_FUNC(Py_ssize_t) _PyDict_NumWatchers(PyDictObject *dp);
167PyAPI_FUNC(int) _PyDict_IsWatchedBy(PyDictObject *dp, PyCodeObject *code);
168#endif
169
170#ifdef __cplusplus
171}
172#endif
173#endif /* !Py_DICTOBJECT_H */