Where Online Learning is simpler!

The C and C++ Include Header Files

/usr/include/python3.12/internal/pycore_dict.h


$ cat -n /usr/include/python3.12/internal/pycore_dict.h

     1	
     2	#ifndef Py_INTERNAL_DICT_H
     3	#define Py_INTERNAL_DICT_H
     4	#ifdef __cplusplus
     5	extern "C" {
     6	#endif
     7	
     8	#ifndef Py_BUILD_CORE
     9	#  error "this header requires Py_BUILD_CORE define"
    10	#endif
    11	
    12	#include "pycore_dict_state.h"
    13	#include "pycore_runtime.h"         // _PyRuntime
    14	
    15	
    16	/* runtime lifecycle */
    17	
    18	extern void _PyDict_Fini(PyInterpreterState *interp);
    19	
    20	
    21	/* other API */
    22	
    23	typedef struct {
    24	    /* Cached hash code of me_key. */
    25	    Py_hash_t me_hash;
    26	    PyObject *me_key;
    27	    PyObject *me_value; /* This field is only meaningful for combined tables */
    28	} PyDictKeyEntry;
    29	
    30	typedef struct {
    31	    PyObject *me_key;   /* The key must be Unicode and have hash. */
    32	    PyObject *me_value; /* This field is only meaningful for combined tables */
    33	} PyDictUnicodeEntry;
    34	
    35	extern PyDictKeysObject *_PyDict_NewKeysForClass(void);
    36	extern PyObject *_PyDict_FromKeys(PyObject *, PyObject *, PyObject *);
    37	
    38	/* Gets a version number unique to the current state of the keys of dict, if possible.
    39	 * Returns the version number, or zero if it was not possible to get a version number. */
    40	extern uint32_t _PyDictKeys_GetVersionForCurrentState(
    41	        PyInterpreterState *interp, PyDictKeysObject *dictkeys);
    42	
    43	extern size_t _PyDict_KeysSize(PyDictKeysObject *keys);
    44	
    45	/* _Py_dict_lookup() returns index of entry which can be used like DK_ENTRIES(dk)[index].
    46	 * -1 when no entry found, -3 when compare raises error.
    47	 */
    48	extern Py_ssize_t _Py_dict_lookup(PyDictObject *mp, PyObject *key, Py_hash_t hash, PyObject **value_addr);
    49	
    50	extern Py_ssize_t _PyDict_LookupIndex(PyDictObject *, PyObject *);
    51	extern Py_ssize_t _PyDictKeys_StringLookup(PyDictKeysObject* dictkeys, PyObject *key);
    52	extern PyObject *_PyDict_LoadGlobal(PyDictObject *, PyDictObject *, PyObject *);
    53	
    54	/* Consumes references to key and value */
    55	extern int _PyDict_SetItem_Take2(PyDictObject *op, PyObject *key, PyObject *value);
    56	extern int _PyObjectDict_SetItem(PyTypeObject *tp, PyObject **dictptr, PyObject *name, PyObject *value);
    57	
    58	extern PyObject *_PyDict_Pop_KnownHash(PyObject *, PyObject *, Py_hash_t, PyObject *);
    59	
    60	#define DKIX_EMPTY (-1)
    61	#define DKIX_DUMMY (-2)  /* Used internally */
    62	#define DKIX_ERROR (-3)
    63	#define DKIX_KEY_CHANGED (-4) /* Used internally */
    64	
    65	typedef enum {
    66	    DICT_KEYS_GENERAL = 0,
    67	    DICT_KEYS_UNICODE = 1,
    68	    DICT_KEYS_SPLIT = 2
    69	} DictKeysKind;
    70	
    71	/* See dictobject.c for actual layout of DictKeysObject */
    72	struct _dictkeysobject {
    73	    Py_ssize_t dk_refcnt;
    74	
    75	    /* Size of the hash table (dk_indices). It must be a power of 2. */
    76	    uint8_t dk_log2_size;
    77	
    78	    /* Size of the hash table (dk_indices) by bytes. */
    79	    uint8_t dk_log2_index_bytes;
    80	
    81	    /* Kind of keys */
    82	    uint8_t dk_kind;
    83	
    84	    /* Version number -- Reset to 0 by any modification to keys */
    85	    uint32_t dk_version;
    86	
    87	    /* Number of usable entries in dk_entries. */
    88	    Py_ssize_t dk_usable;
    89	
    90	    /* Number of used entries in dk_entries. */
    91	    Py_ssize_t dk_nentries;
    92	
    93	    /* Actual hash table of dk_size entries. It holds indices in dk_entries,
    94	       or DKIX_EMPTY(-1) or DKIX_DUMMY(-2).
    95	
    96	       Indices must be: 0 <= indice < USABLE_FRACTION(dk_size).
    97	
    98	       The size in bytes of an indice depends on dk_size:
    99	
   100	       - 1 byte if dk_size <= 0xff (char*)
   101	       - 2 bytes if dk_size <= 0xffff (int16_t*)
   102	       - 4 bytes if dk_size <= 0xffffffff (int32_t*)
   103	       - 8 bytes otherwise (int64_t*)
   104	
   105	       Dynamically sized, SIZEOF_VOID_P is minimum. */
   106	    char dk_indices[];  /* char is required to avoid strict aliasing. */
   107	
   108	    /* "PyDictKeyEntry or PyDictUnicodeEntry dk_entries[USABLE_FRACTION(DK_SIZE(dk))];" array follows:
   109	       see the DK_ENTRIES() macro */
   110	};
   111	
   112	/* This must be no more than 250, for the prefix size to fit in one byte. */
   113	#define SHARED_KEYS_MAX_SIZE 30
   114	#define NEXT_LOG2_SHARED_KEYS_MAX_SIZE 6
   115	
   116	/* Layout of dict values:
   117	 *
   118	 * The PyObject *values are preceded by an array of bytes holding
   119	 * the insertion order and size.
   120	 * [-1] = prefix size. [-2] = used size. size[-2-n...] = insertion order.
   121	 */
   122	struct _dictvalues {
   123	    PyObject *values[1];
   124	};
   125	
   126	#define DK_LOG_SIZE(dk)  _Py_RVALUE((dk)->dk_log2_size)
   127	#if SIZEOF_VOID_P > 4
   128	#define DK_SIZE(dk)      (((int64_t)1)<<DK_LOG_SIZE(dk))
   129	#else
   130	#define DK_SIZE(dk)      (1<<DK_LOG_SIZE(dk))
   131	#endif
   132	
   133	static inline void* _DK_ENTRIES(PyDictKeysObject *dk) {
   134	    int8_t *indices = (int8_t*)(dk->dk_indices);
   135	    size_t index = (size_t)1 << dk->dk_log2_index_bytes;
   136	    return (&indices[index]);
   137	}
   138	static inline PyDictKeyEntry* DK_ENTRIES(PyDictKeysObject *dk) {
   139	    assert(dk->dk_kind == DICT_KEYS_GENERAL);
   140	    return (PyDictKeyEntry*)_DK_ENTRIES(dk);
   141	}
   142	static inline PyDictUnicodeEntry* DK_UNICODE_ENTRIES(PyDictKeysObject *dk) {
   143	    assert(dk->dk_kind != DICT_KEYS_GENERAL);
   144	    return (PyDictUnicodeEntry*)_DK_ENTRIES(dk);
   145	}
   146	
   147	#define DK_IS_UNICODE(dk) ((dk)->dk_kind != DICT_KEYS_GENERAL)
   148	
   149	#define DICT_VERSION_INCREMENT (1 << DICT_MAX_WATCHERS)
   150	#define DICT_VERSION_MASK (DICT_VERSION_INCREMENT - 1)
   151	
   152	#define DICT_NEXT_VERSION(INTERP) \
   153	    ((INTERP)->dict_state.global_version += DICT_VERSION_INCREMENT)
   154	
   155	void
   156	_PyDict_SendEvent(int watcher_bits,
   157	                  PyDict_WatchEvent event,
   158	                  PyDictObject *mp,
   159	                  PyObject *key,
   160	                  PyObject *value);
   161	
   162	static inline uint64_t
   163	_PyDict_NotifyEvent(PyInterpreterState *interp,
   164	                    PyDict_WatchEvent event,
   165	                    PyDictObject *mp,
   166	                    PyObject *key,
   167	                    PyObject *value)
   168	{
   169	    assert(Py_REFCNT((PyObject*)mp) > 0);
   170	    int watcher_bits = mp->ma_version_tag & DICT_VERSION_MASK;
   171	    if (watcher_bits) {
   172	        _PyDict_SendEvent(watcher_bits, event, mp, key, value);
   173	        return DICT_NEXT_VERSION(interp) | watcher_bits;
   174	    }
   175	    return DICT_NEXT_VERSION(interp);
   176	}
   177	
   178	extern PyObject *_PyObject_MakeDictFromInstanceAttributes(PyObject *obj, PyDictValues *values);
   179	extern PyObject *_PyDict_FromItems(
   180	        PyObject *const *keys, Py_ssize_t keys_offset,
   181	        PyObject *const *values, Py_ssize_t values_offset,
   182	        Py_ssize_t length);
   183	
   184	static inline void
   185	_PyDictValues_AddToInsertionOrder(PyDictValues *values, Py_ssize_t ix)
   186	{
   187	    assert(ix < SHARED_KEYS_MAX_SIZE);
   188	    uint8_t *size_ptr = ((uint8_t *)values)-2;
   189	    int size = *size_ptr;
   190	    assert(size+2 < ((uint8_t *)values)[-1]);
   191	    size++;
   192	    size_ptr[-size] = (uint8_t)ix;
   193	    *size_ptr = size;
   194	}
   195	
   196	#ifdef __cplusplus
   197	}
   198	#endif
   199	#endif   /* !Py_INTERNAL_DICT_H */