include/python3.12/pyhash.h

0001 #ifndef Py_HASH_H
0002
0003 #define Py_HASH_H
0004 #ifdef __cplusplus
0005 extern "C" {
0006 #endif
0007
0008 /* Helpers for hash functions */
0009 #ifndef Py_LIMITED_API
0010 PyAPI_FUNC(Py_hash_t) _Py_HashDouble(PyObject *, double);
0011 PyAPI_FUNC(Py_hash_t) _Py_HashPointer(const void*);
0012 // Similar to _Py_HashPointer(), but don't replace -1 with -2
0013 PyAPI_FUNC(Py_hash_t) _Py_HashPointerRaw(const void*);
0014 PyAPI_FUNC(Py_hash_t) _Py_HashBytes(const void*, Py_ssize_t);
0015 #endif
0016
0017 /* Prime multiplier used in string and various other hashes. */
0018 #define _PyHASH_MULTIPLIER 1000003UL  /* 0xf4243 */
0019
0020 /* Parameters used for the numeric hash implementation.  See notes for
0021    _Py_HashDouble in Python/pyhash.c.  Numeric hashes are based on
0022    reduction modulo the prime 2**_PyHASH_BITS - 1. */
0023
0024 #if SIZEOF_VOID_P >= 8
0025 #  define _PyHASH_BITS 61
0026 #else
0027 #  define _PyHASH_BITS 31
0028 #endif
0029
0030 #define _PyHASH_MODULUS (((size_t)1 << _PyHASH_BITS) - 1)
0031 #define _PyHASH_INF 314159
0032 #define _PyHASH_IMAG _PyHASH_MULTIPLIER
0033
0034
0035 /* hash secret
0036  *
0037  * memory layout on 64 bit systems
0038  *   cccccccc cccccccc cccccccc  uc -- unsigned char[24]
0039  *   pppppppp ssssssss ........  fnv -- two Py_hash_t
0040  *   k0k0k0k0 k1k1k1k1 ........  siphash -- two uint64_t
0041  *   ........ ........ ssssssss  djbx33a -- 16 bytes padding + one Py_hash_t
0042  *   ........ ........ eeeeeeee  pyexpat XML hash salt
0043  *
0044  * memory layout on 32 bit systems
0045  *   cccccccc cccccccc cccccccc  uc
0046  *   ppppssss ........ ........  fnv -- two Py_hash_t
0047  *   k0k0k0k0 k1k1k1k1 ........  siphash -- two uint64_t (*)
0048  *   ........ ........ ssss....  djbx33a -- 16 bytes padding + one Py_hash_t
0049  *   ........ ........ eeee....  pyexpat XML hash salt
0050  *
0051  * (*) The siphash member may not be available on 32 bit platforms without
0052  *     an unsigned int64 data type.
0053  */
0054 #ifndef Py_LIMITED_API
0055 typedef union {
0056     /* ensure 24 bytes */
0057     unsigned char uc[24];
0058     /* two Py_hash_t for FNV */
0059     struct {
0060         Py_hash_t prefix;
0061         Py_hash_t suffix;
0062     } fnv;
0063     /* two uint64 for SipHash24 */
0064     struct {
0065         uint64_t k0;
0066         uint64_t k1;
0067     } siphash;
0068     /* a different (!) Py_hash_t for small string optimization */
0069     struct {
0070         unsigned char padding[16];
0071         Py_hash_t suffix;
0072     } djbx33a;
0073     struct {
0074         unsigned char padding[16];
0075         Py_hash_t hashsalt;
0076     } expat;
0077 } _Py_HashSecret_t;
0078 PyAPI_DATA(_Py_HashSecret_t) _Py_HashSecret;
0079
0080 #ifdef Py_DEBUG
0081 PyAPI_DATA(int) _Py_HashSecret_Initialized;
0082 #endif
0083
0084
0085 /* hash function definition */
0086 typedef struct {
0087     Py_hash_t (*const hash)(const void *, Py_ssize_t);
0088     const char *name;
0089     const int hash_bits;
0090     const int seed_bits;
0091 } PyHash_FuncDef;
0092
0093 PyAPI_FUNC(PyHash_FuncDef*) PyHash_GetFuncDef(void);
0094 #endif
0095
0096
0097 /* cutoff for small string DJBX33A optimization in range [1, cutoff).
0098  *
0099  * About 50% of the strings in a typical Python application are smaller than
0100  * 6 to 7 chars. However DJBX33A is vulnerable to hash collision attacks.
0101  * NEVER use DJBX33A for long strings!
0102  *
0103  * A Py_HASH_CUTOFF of 0 disables small string optimization. 32 bit platforms
0104  * should use a smaller cutoff because it is easier to create colliding
0105  * strings. A cutoff of 7 on 64bit platforms and 5 on 32bit platforms should
0106  * provide a decent safety margin.
0107  */
0108 #ifndef Py_HASH_CUTOFF
0109 #  define Py_HASH_CUTOFF 0
0110 #elif (Py_HASH_CUTOFF > 7 || Py_HASH_CUTOFF < 0)
0111 #  error Py_HASH_CUTOFF must in range 0...7.
0112 #endif /* Py_HASH_CUTOFF */
0113
0114
0115 /* hash algorithm selection
0116  *
0117  * The values for Py_HASH_* are hard-coded in the
0118  * configure script.
0119  *
0120  * - FNV and SIPHASH* are available on all platforms and architectures.
0121  * - With EXTERNAL embedders can provide an alternative implementation with::
0122  *
0123  *     PyHash_FuncDef PyHash_Func = {...};
0124  *
0125  * XXX: Figure out __declspec() for extern PyHash_FuncDef.
0126  */
0127 #define Py_HASH_EXTERNAL 0
0128 #define Py_HASH_SIPHASH24 1
0129 #define Py_HASH_FNV 2
0130 #define Py_HASH_SIPHASH13 3
0131
0132 #ifndef Py_HASH_ALGORITHM
0133 #  ifndef HAVE_ALIGNED_REQUIRED
0134 #    define Py_HASH_ALGORITHM Py_HASH_SIPHASH13
0135 #  else
0136 #    define Py_HASH_ALGORITHM Py_HASH_FNV
0137 #  endif /* uint64_t && uint32_t && aligned */
0138 #endif /* Py_HASH_ALGORITHM */
0139
0140 #ifdef __cplusplus
0141 }
0142 #endif
0143
0144 #endif /* !Py_HASH_H */