| 1 |
#ifndef Py_INTERNAL_HAMT_H |
| 2 |
#define Py_INTERNAL_HAMT_H |
| 3 |
|
| 4 |
#ifndef Py_BUILD_CORE |
| 5 |
# error "this header requires Py_BUILD_CORE define" |
| 6 |
#endif |
| 7 |
|
| 8 |
#include "pycore_structs.h" // PyHamtNode |
| 9 |
|
| 10 |
/* |
| 11 |
HAMT tree is shaped by hashes of keys. Every group of 5 bits of a hash denotes |
| 12 |
the exact position of the key in one level of the tree. Since we're using |
| 13 |
32 bit hashes, we can have at most 7 such levels. Although if there are |
| 14 |
two distinct keys with equal hashes, they will have to occupy the same |
| 15 |
cell in the 7th level of the tree -- so we'd put them in a "collision" node. |
| 16 |
Which brings the total possible tree depth to 8. Read more about the actual |
| 17 |
layout of the HAMT tree in `hamt.c`. |
| 18 |
|
| 19 |
This constant is used to define a datastucture for storing iteration state. |
| 20 |
*/ |
| 21 |
#define _Py_HAMT_MAX_TREE_DEPTH 8 |
| 22 |
|
| 23 |
|
| 24 |
extern PyTypeObject _PyHamt_Type; |
| 25 |
extern PyTypeObject _PyHamt_ArrayNode_Type; |
| 26 |
extern PyTypeObject _PyHamt_BitmapNode_Type; |
| 27 |
extern PyTypeObject _PyHamt_CollisionNode_Type; |
| 28 |
extern PyTypeObject _PyHamtKeys_Type; |
| 29 |
extern PyTypeObject _PyHamtValues_Type; |
| 30 |
extern PyTypeObject _PyHamtItems_Type; |
| 31 |
|
| 32 |
|
| 33 |
/* other API */ |
| 34 |
|
| 35 |
#define PyHamt_Check(o) Py_IS_TYPE((o), &_PyHamt_Type) |
| 36 |
|
| 37 |
|
| 38 |
/* A struct to hold the state of depth-first traverse of the tree. |
| 39 |
|
| 40 |
HAMT is an immutable collection. Iterators will hold a strong reference |
| 41 |
to it, and every node in the HAMT has strong references to its children. |
| 42 |
|
| 43 |
So for iterators, we can implement zero allocations and zero reference |
| 44 |
inc/dec depth-first iteration. |
| 45 |
|
| 46 |
- i_nodes: an array of seven pointers to tree nodes |
| 47 |
- i_level: the current node in i_nodes |
| 48 |
- i_pos: an array of positions within nodes in i_nodes. |
| 49 |
*/ |
| 50 |
typedef struct { |
| 51 |
PyHamtNode *i_nodes[_Py_HAMT_MAX_TREE_DEPTH]; |
| 52 |
Py_ssize_t i_pos[_Py_HAMT_MAX_TREE_DEPTH]; |
| 53 |
int8_t i_level; |
| 54 |
} PyHamtIteratorState; |
| 55 |
|
| 56 |
|
| 57 |
/* Base iterator object. |
| 58 |
|
| 59 |
Contains the iteration state, a pointer to the HAMT tree, |
| 60 |
and a pointer to the 'yield function'. The latter is a simple |
| 61 |
function that returns a key/value tuple for the 'Items' iterator, |
| 62 |
just a key for the 'Keys' iterator, and a value for the 'Values' |
| 63 |
iterator. |
| 64 |
*/ |
| 65 |
typedef struct { |
| 66 |
PyObject_HEAD |
| 67 |
PyHamtObject *hi_obj; |
| 68 |
PyHamtIteratorState hi_iter; |
| 69 |
binaryfunc hi_yield; |
| 70 |
} PyHamtIterator; |
| 71 |
|
| 72 |
|
| 73 |
/* Create a new HAMT immutable mapping. */ |
| 74 |
PyHamtObject * _PyHamt_New(void); |
| 75 |
|
| 76 |
/* Return a new collection based on "o", but with an additional |
| 77 |
key/val pair. */ |
| 78 |
PyHamtObject * _PyHamt_Assoc(PyHamtObject *o, PyObject *key, PyObject *val); |
| 79 |
|
| 80 |
/* Return a new collection based on "o", but without "key". */ |
| 81 |
PyHamtObject * _PyHamt_Without(PyHamtObject *o, PyObject *key); |
| 82 |
|
| 83 |
/* Find "key" in the "o" collection. |
| 84 |
|
| 85 |
Return: |
| 86 |
- -1: An error occurred. |
| 87 |
- 0: "key" wasn't found in "o". |
| 88 |
- 1: "key" is in "o"; "*val" is set to its value (a borrowed ref). |
| 89 |
*/ |
| 90 |
int _PyHamt_Find(PyHamtObject *o, PyObject *key, PyObject **val); |
| 91 |
|
| 92 |
/* Check if "v" is equal to "w". |
| 93 |
|
| 94 |
Return: |
| 95 |
- 0: v != w |
| 96 |
- 1: v == w |
| 97 |
- -1: An error occurred. |
| 98 |
*/ |
| 99 |
int _PyHamt_Eq(PyHamtObject *v, PyHamtObject *w); |
| 100 |
|
| 101 |
/* Return the size of "o"; equivalent of "len(o)". */ |
| 102 |
Py_ssize_t _PyHamt_Len(PyHamtObject *o); |
| 103 |
|
| 104 |
/* Return a Keys iterator over "o". */ |
| 105 |
PyObject * _PyHamt_NewIterKeys(PyHamtObject *o); |
| 106 |
|
| 107 |
/* Return a Values iterator over "o". */ |
| 108 |
PyObject * _PyHamt_NewIterValues(PyHamtObject *o); |
| 109 |
|
| 110 |
/* Return a Items iterator over "o". */ |
| 111 |
PyObject * _PyHamt_NewIterItems(PyHamtObject *o); |
| 112 |
|
| 113 |
#endif /* !Py_INTERNAL_HAMT_H */ |