ucx/cx/hash_key.h

   1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   3  *
   4  * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions are met:
   8  *
   9  *   1. Redistributions of source code must retain the above copyright
  10  *      notice, this list of conditions and the following disclaimer.
  11  *
  12  *   2. Redistributions in binary form must reproduce the above copyright
  13  *      notice, this list of conditions and the following disclaimer in the
  14  *      documentation and/or other materials provided with the distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  * POSSIBILITY OF SUCH DAMAGE.
  27  */
  28 /**
  29  * \file hash_key.h
  30  * \brief Interface for map implementations.
  31  * \author Mike Becker
  32  * \author Olaf Wintermann
  33  * \version 3.0
  34  * \copyright 2-Clause BSD License
  35  */
  36
  37
  38 #ifndef UCX_HASH_KEY_H
  39 #define UCX_HASH_KEY_H
  40
  41 #include "stddef.h"
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /** Internal structure for a key within a hash map. */
  48 struct cx_hash_key_s {
  49     /** The key data. */
  50     union {
  51         unsigned char *bytes;
  52         unsigned char const *cbytes;
  53         char *str;
  54         char const *cstr;
  55         void *obj;
  56         void const *cobj;
  57     } data;
  58     /**
  59      * The key data length.
  60      */
  61     size_t len;
  62     /** The hash value of the key data. */
  63     unsigned hash;
  64 };
  65
  66 /**
  67  * Type for a hash key.
  68  */
  69 typedef struct cx_hash_key_s CxHashKey;
  70
  71 /**
  72  * Computes a murmur2 32 bit hash.
  73  *
  74  * You need to initialize \c data and \c len in the key struct.
  75  * The hash is then directly written to that struct.
  76  *
  77  * \note If \c data is \c NULL, the hash is defined as 1574210520.
  78  *
  79  * @param key the key, the hash shall be computed for
  80  */
  81 void cx_hash_murmur(CxHashKey *key);
  82
  83 /**
  84  * Computes a hash key from a string.
  85  *
  86  * The string needs to be zero-terminated.
  87  *
  88  * @param str the string
  89  * @return the hash key
  90  */
  91 __attribute__((__warn_unused_result__))
  92 CxHashKey cx_hash_key_str(char const *str);
  93
  94 /**
  95  * Computes a hash key from a byte array.
  96  *
  97  * @param bytes the array
  98  * @param len the length
  99  * @return the hash key
 100  */
 101 __attribute__((__warn_unused_result__))
 102 CxHashKey cx_hash_key_bytes(
 103         unsigned char const *bytes,
 104         size_t len
 105 );
 106
 107 /**
 108  * Computes a hash key for an arbitrary object.
 109  *
 110  * The computation uses the in-memory representation that might not be
 111  * the same on different platforms. Therefore, this hash should not be
 112  * used for data exchange with different machines.
 113  *
 114  * @param obj a pointer to an arbitrary object
 115  * @param len the length of object in memory
 116  * @return the hash key
 117  */
 118 __attribute__((__warn_unused_result__))
 119 CxHashKey cx_hash_key(
 120         void const *obj,
 121         size_t len
 122 );
 123
 124 /**
 125  * Computes a hash key from a UCX string.
 126  *
 127  * @param str the string
 128  * @return the hash key
 129  */
 130 #define cx_hash_key_cxstr(str) cx_hash_key((void*)(str).ptr, (str).length)
 131
 132 #ifdef __cplusplus
 133 } // extern "C"
 134 #endif
 135
 136 #endif // UCX_HASH_KEY_H