ucx/ucx/ucx.h

   1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   3  *
   4  * Copyright 2017 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  * Main UCX Header providing most common definitions.
  30  *
  31  * @file   ucx.h
  32  * @author Mike Becker
  33  * @author Olaf Wintermann
  34  */
  35
  36 #ifndef UCX_H
  37 #define UCX_H
  38
  39 /** Major UCX version as integer constant. */
  40 #define UCX_VERSION_MAJOR   2
  41
  42 /** Minor UCX version as integer constant. */
  43 #define UCX_VERSION_MINOR   1
  44
  45 /** Version constant which ensures to increase monotonically. */
  46 #define UCX_VERSION (((UCX_VERSION_MAJOR)<<16)|UCX_VERSION_MINOR)
  47
  48 #include <stdlib.h>
  49 #include <stdint.h>
  50
  51 #ifdef _WIN32
  52 #if !(defined __ssize_t_defined || defined _SSIZE_T_)
  53 #include <BaseTsd.h>
  54 typedef SSIZE_T ssize_t;
  55 #define __ssize_t_defined
  56 #define _SSIZE_T_
  57 #endif /* __ssize_t_defined and _SSIZE_T */
  58 #else /* !_WIN32 */
  59 #include <sys/types.h>
  60 #endif /* _WIN32 */
  61
  62 #ifdef  __cplusplus
  63 extern "C" {
  64 #endif
  65
  66
  67 /**
  68  * A function pointer to a destructor function.
  69  * @see ucx_mempool_setdestr()
  70  * @see ucx_mempool_regdestr()
  71  */
  72 typedef void(*ucx_destructor)(void*);
  73
  74 /**
  75  * Function pointer to a compare function.
  76  *
  77  * The compare function shall take three arguments: the two values that shall be
  78  * compared and optional additional data.
  79  * The function shall then return -1 if the first argument is less than the
  80  * second argument, 1 if the first argument is greater than the second argument
  81  * and 0 if both arguments are equal. If the third argument is
  82  * <code>NULL</code>, it shall be ignored.
  83  */
  84 typedef int(*cmp_func)(const void*,const void*,void*);
  85
  86 /**
  87  * Function pointer to a distance function.
  88  *
  89  * The distance function shall take three arguments: the two values for which
  90  * the distance shall be computed and optional additional data.
  91  * The function shall then return the signed distance as integer value.
  92  */
  93 typedef intmax_t(*distance_func)(const void*,const void*,void*);
  94
  95 /**
  96  * Function pointer to a copy function.
  97  *
  98  * The copy function shall create a copy of the first argument and may use
  99  * additional data provided by the second argument. If the second argument is
 100  * <code>NULL</code>, it shall be ignored.
 101
 102  * <b>Attention:</b> if pointers returned by functions of this type may be
 103  * passed to <code>free()</code> depends on the implementation of the
 104  * respective <code>copy_func</code>.
 105  */
 106 typedef void*(*copy_func)(const void*,void*);
 107
 108 /**
 109  * Function pointer to a write function.
 110  *
 111  * The signature of the write function shall be compatible to the signature
 112  * of standard <code>fwrite</code>, though it may use arbitrary data types for
 113  * source and destination.
 114  *
 115  * The arguments shall contain (in ascending order): a pointer to the source,
 116  * the length of one element, the element count and a pointer to the
 117  * destination.
 118  */
 119 typedef size_t(*write_func)(const void*, size_t, size_t, void*);
 120
 121 /**
 122  * Function pointer to a read function.
 123  *
 124  * The signature of the read function shall be compatible to the signature
 125  * of standard <code>fread</code>, though it may use arbitrary data types for
 126  * source and destination.
 127  *
 128  * The arguments shall contain (in ascending order): a pointer to the
 129  * destination, the length of one element, the element count and a pointer to
 130  * the source.
 131  */
 132 typedef size_t(*read_func)(void*, size_t, size_t, void*);
 133
 134
 135
 136 #if __GNUC__ >= 5 || defined(__clang__)
 137 #define UCX_MUL_BUILTIN
 138
 139 #if __WORDSIZE == 32
 140 /**
 141  * Alias for <code>__builtin_umul_overflow</code>.
 142  *
 143  * Performs a multiplication of size_t values and checks for overflow.
 144  *
 145  * @param a first operand
 146  * @param b second operand
 147  * @param result a pointer to a size_t, where the result should
 148  * be stored
 149  * @return zero, if no overflow occurred and the result is correct, non-zero
 150  * otherwise
 151  */
 152 #define ucx_szmul(a, b, result) __builtin_umul_overflow(a, b, result)
 153 #else /* __WORDSIZE != 32 */
 154 /**
 155  * Alias for <code>__builtin_umull_overflow</code>.
 156  *
 157  * Performs a multiplication of size_t values and checks for overflow.
 158  *
 159  * @param a first operand
 160  * @param b second operand
 161  * @param result a pointer to a size_t, where the result should
 162  * be stored
 163  * @return zero, if no overflow occurred and the result is correct, non-zero
 164  * otherwise
 165  */
 166 #define ucx_szmul(a, b, result) __builtin_umull_overflow(a, b, result)
 167 #endif /* __WORDSIZE */
 168
 169 #else /* no GNUC or clang bultin */
 170
 171 /**
 172  * Performs a multiplication of size_t values and checks for overflow.
 173   *
 174  * @param a first operand
 175  * @param b second operand
 176  * @param result a pointer to a size_t, where the result should
 177  * be stored
 178  * @return zero, if no overflow occurred and the result is correct, non-zero
 179  * otherwise
 180  */
 181 #define ucx_szmul(a, b, result) ucx_szmul_impl(a, b, result)
 182
 183 /**
 184  * Performs a multiplication of size_t values and checks for overflow.
 185  *
 186  * This is a custom implementation in case there is no compiler builtin
 187  * available.
 188  *
 189  * @param a first operand
 190  * @param b second operand
 191  * @param result a pointer to a size_t where the result should be stored
 192  * @return zero, if no overflow occurred and the result is correct, non-zero
 193  * otherwise
 194  */
 195 int ucx_szmul_impl(size_t a, size_t b, size_t *result);
 196
 197 #endif
 198
 199 #ifdef  __cplusplus
 200 }
 201 #endif
 202
 203 #endif  /* UCX_H */
 204