/Include/dictobject.h

http://unladen-swallow.googlecode.com/ · C Header · 173 lines · 66 code · 22 blank · 85 comment · 1 complexity · f40a440fff5d74669f5ffbaa13af871a MD5 · raw file

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