universe@563: /*
universe@563:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
universe@563:  *
universe@563:  * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
universe@563:  *
universe@563:  * Redistribution and use in source and binary forms, with or without
universe@563:  * modification, are permitted provided that the following conditions are met:
universe@563:  *
universe@563:  *   1. Redistributions of source code must retain the above copyright
universe@563:  *      notice, this list of conditions and the following disclaimer.
universe@563:  *
universe@563:  *   2. Redistributions in binary form must reproduce the above copyright
universe@563:  *      notice, this list of conditions and the following disclaimer in the
universe@563:  *      documentation and/or other materials provided with the distribution.
universe@563:  *
universe@563:  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
universe@563:  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
universe@563:  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
universe@563:  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
universe@563:  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
universe@563:  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
universe@563:  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
universe@563:  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
universe@563:  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
universe@563:  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
universe@563:  * POSSIBILITY OF SUCH DAMAGE.
universe@563:  */
universe@563: /**
universe@563:  * \file hash_key.h
universe@563:  * \brief Interface for map implementations.
universe@563:  * \author Mike Becker
universe@563:  * \author Olaf Wintermann
universe@563:  * \copyright 2-Clause BSD License
universe@563:  */
universe@563: 
universe@563: 
universe@563: #ifndef UCX_HASH_KEY_H
universe@563: #define UCX_HASH_KEY_H
universe@563: 
universe@681: #include "common.h"
universe@563: 
universe@563: #ifdef __cplusplus
universe@563: extern "C" {
universe@563: #endif
universe@563: 
universe@563: /** Internal structure for a key within a hash map. */
universe@563: struct cx_hash_key_s {
universe@563:     /** The key data. */
universe@690:     void const *data;
universe@563:     /**
universe@563:      * The key data length.
universe@563:      */
universe@563:     size_t len;
universe@563:     /** The hash value of the key data. */
universe@563:     unsigned hash;
universe@563: };
universe@563: 
universe@563: /**
universe@563:  * Type for a hash key.
universe@563:  */
universe@563: typedef struct cx_hash_key_s CxHashKey;
universe@563: 
universe@563: /**
universe@604:  * Computes a murmur2 32 bit hash.
universe@563:  *
universe@604:  * You need to initialize \c data and \c len in the key struct.
universe@563:  * The hash is then directly written to that struct.
universe@563:  *
universe@604:  * \note If \c data is \c NULL, the hash is defined as 1574210520.
universe@604:  *
universe@563:  * @param key the key, the hash shall be computed for
universe@563:  */
universe@563: void cx_hash_murmur(CxHashKey *key);
universe@563: 
universe@563: /**
universe@563:  * Computes a hash key from a string.
universe@563:  *
universe@563:  * The string needs to be zero-terminated.
universe@563:  *
universe@563:  * @param str the string
universe@563:  * @return the hash key
universe@563:  */
universe@563: __attribute__((__warn_unused_result__))
universe@563: CxHashKey cx_hash_key_str(char const *str);
universe@563: 
universe@563: /**
universe@563:  * Computes a hash key from a byte array.
universe@563:  *
universe@563:  * @param bytes the array
universe@563:  * @param len the length
universe@563:  * @return the hash key
universe@563:  */
universe@563: __attribute__((__warn_unused_result__))
universe@563: CxHashKey cx_hash_key_bytes(
universe@563:         unsigned char const *bytes,
universe@563:         size_t len
universe@563: );
universe@563: 
universe@563: /**
universe@563:  * Computes a hash key for an arbitrary object.
universe@563:  *
universe@563:  * The computation uses the in-memory representation that might not be
universe@563:  * the same on different platforms. Therefore, this hash should not be
universe@563:  * used for data exchange with different machines.
universe@563:  *
universe@563:  * @param obj a pointer to an arbitrary object
universe@563:  * @param len the length of object in memory
universe@563:  * @return the hash key
universe@563:  */
universe@563: __attribute__((__warn_unused_result__))
universe@563: CxHashKey cx_hash_key(
universe@603:         void const *obj,
universe@563:         size_t len
universe@563: );
universe@563: 
universe@663: /**
universe@663:  * Computes a hash key from a UCX string.
universe@663:  *
universe@663:  * @param str the string
universe@663:  * @return the hash key
universe@663:  */
universe@663: #define cx_hash_key_cxstr(str) cx_hash_key((void*)(str).ptr, (str).length)
universe@663: 
universe@563: #ifdef __cplusplus
universe@563: } // extern "C"
universe@563: #endif
universe@563: 
universe@628: #endif // UCX_HASH_KEY_H