Wed, 16 May 2018 14:02:59 +0200
adds remaining documentation for the scstr functions
universe@103 | 1 | /* |
universe@103 | 2 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
olaf@5 | 3 | * |
universe@259 | 4 | * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved. |
universe@103 | 5 | * |
universe@103 | 6 | * Redistribution and use in source and binary forms, with or without |
universe@103 | 7 | * modification, are permitted provided that the following conditions are met: |
universe@103 | 8 | * |
universe@103 | 9 | * 1. Redistributions of source code must retain the above copyright |
universe@103 | 10 | * notice, this list of conditions and the following disclaimer. |
universe@103 | 11 | * |
universe@103 | 12 | * 2. Redistributions in binary form must reproduce the above copyright |
universe@103 | 13 | * notice, this list of conditions and the following disclaimer in the |
universe@103 | 14 | * documentation and/or other materials provided with the distribution. |
universe@103 | 15 | * |
universe@103 | 16 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
universe@103 | 17 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
universe@103 | 18 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
universe@103 | 19 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE |
universe@103 | 20 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
universe@103 | 21 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
universe@103 | 22 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
universe@103 | 23 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
universe@103 | 24 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
universe@103 | 25 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
universe@103 | 26 | * POSSIBILITY OF SUCH DAMAGE. |
olaf@5 | 27 | */ |
universe@114 | 28 | /** |
universe@114 | 29 | * Main UCX Header providing most common definitions. |
universe@114 | 30 | * |
universe@114 | 31 | * @file ucx.h |
universe@115 | 32 | * @author Mike Becker |
universe@114 | 33 | * @author Olaf Wintermann |
universe@114 | 34 | */ |
olaf@5 | 35 | |
olaf@5 | 36 | #ifndef UCX_H |
olaf@5 | 37 | #define UCX_H |
olaf@5 | 38 | |
universe@151 | 39 | /** Major UCX version as integer constant. */ |
universe@306 | 40 | #define UCX_VERSION_MAJOR 2 |
universe@151 | 41 | |
universe@151 | 42 | /** Minor UCX version as integer constant. */ |
universe@306 | 43 | #define UCX_VERSION_MINOR 0 |
universe@259 | 44 | |
universe@259 | 45 | /** Version constant which ensures to increase monotonically. */ |
universe@259 | 46 | #define UCX_VERSION (((UCX_VERSION_MAJOR)<<16)|UCX_VERSION_MINOR) |
universe@151 | 47 | |
olaf@5 | 48 | #include <stdlib.h> |
universe@243 | 49 | #include <stdint.h> |
olaf@5 | 50 | |
universe@127 | 51 | #ifdef _WIN32 |
universe@132 | 52 | #if !(defined __ssize_t_defined || defined _SSIZE_T_) |
universe@127 | 53 | #include <BaseTsd.h> |
universe@127 | 54 | typedef SSIZE_T ssize_t; |
universe@127 | 55 | #define __ssize_t_defined |
universe@132 | 56 | #define _SSIZE_T_ |
universe@132 | 57 | #endif /* __ssize_t_defined and _SSIZE_T */ |
universe@127 | 58 | #else /* !_WIN32 */ |
universe@127 | 59 | #include <sys/types.h> |
universe@127 | 60 | #endif /* _WIN32 */ |
universe@127 | 61 | |
olaf@5 | 62 | #ifdef __cplusplus |
olaf@5 | 63 | extern "C" { |
olaf@5 | 64 | #endif |
universe@209 | 65 | |
universe@209 | 66 | |
universe@209 | 67 | /** |
universe@209 | 68 | * A function pointer to a destructor function. |
universe@209 | 69 | * @see ucx_mempool_setdestr() |
universe@209 | 70 | * @see ucx_mempool_regdestr() |
universe@209 | 71 | */ |
universe@209 | 72 | typedef void(*ucx_destructor)(void*); |
olaf@5 | 73 | |
universe@114 | 74 | /** |
universe@114 | 75 | * Function pointer to a compare function. |
universe@114 | 76 | * |
universe@114 | 77 | * The compare function shall take three arguments: the two values that shall be |
universe@114 | 78 | * compared and optional additional data. |
universe@114 | 79 | * The function shall then return -1 if the first argument is less than the |
universe@114 | 80 | * second argument, 1 if the first argument is greater than the second argument |
universe@114 | 81 | * and 0 if both arguments are equal. If the third argument is |
universe@114 | 82 | * <code>NULL</code>, it shall be ignored. |
universe@114 | 83 | */ |
universe@244 | 84 | typedef int(*cmp_func)(const void*,const void*,void*); |
universe@18 | 85 | |
universe@114 | 86 | /** |
universe@243 | 87 | * Function pointer to a distance function. |
universe@243 | 88 | * |
universe@243 | 89 | * The distance function shall take three arguments: the two values for which |
universe@243 | 90 | * the distance shall be computed and optional additional data. |
universe@243 | 91 | * The function shall then return the signed distance as integer value. |
universe@243 | 92 | */ |
universe@244 | 93 | typedef intmax_t(*distance_func)(const void*,const void*,void*); |
universe@243 | 94 | |
universe@243 | 95 | /** |
universe@114 | 96 | * Function pointer to a copy function. |
universe@114 | 97 | * |
universe@114 | 98 | * The copy function shall create a copy of the first argument and may use |
universe@114 | 99 | * additional data provided by the second argument. If the second argument is |
universe@114 | 100 | * <code>NULL</code>, it shall be ignored. |
universe@114 | 101 | |
universe@114 | 102 | * <b>Attention:</b> if pointers returned by functions of this type may be |
universe@114 | 103 | * passed to <code>free()</code> depends on the implementation of the |
universe@114 | 104 | * respective <code>copy_func</code>. |
universe@114 | 105 | */ |
universe@244 | 106 | typedef void*(*copy_func)(const void*,void*); |
universe@18 | 107 | |
universe@114 | 108 | /** |
universe@114 | 109 | * Function pointer to a write function. |
universe@114 | 110 | * |
universe@114 | 111 | * The signature of the write function shall be compatible to the signature |
universe@114 | 112 | * of standard <code>fwrite</code>, though it may use arbitrary data types for |
universe@114 | 113 | * source and destination. |
universe@114 | 114 | * |
universe@114 | 115 | * The arguments shall contain (in ascending order): a pointer to the source, |
universe@116 | 116 | * the length of one element, the element count and a pointer to the |
universe@116 | 117 | * destination. |
universe@114 | 118 | */ |
olaf@76 | 119 | typedef size_t(*write_func)(const void*, size_t, size_t, void*); |
olaf@76 | 120 | |
universe@114 | 121 | /** |
universe@114 | 122 | * Function pointer to a read function. |
universe@114 | 123 | * |
universe@114 | 124 | * The signature of the read function shall be compatible to the signature |
universe@114 | 125 | * of standard <code>fread</code>, though it may use arbitrary data types for |
universe@114 | 126 | * source and destination. |
universe@114 | 127 | * |
universe@114 | 128 | * The arguments shall contain (in ascending order): a pointer to the |
universe@116 | 129 | * destination, the length of one element, the element count and a pointer to |
universe@116 | 130 | * the source. |
universe@114 | 131 | */ |
olaf@76 | 132 | typedef size_t(*read_func)(void*, size_t, size_t, void*); |
olaf@76 | 133 | |
olaf@270 | 134 | |
olaf@270 | 135 | |
olaf@270 | 136 | #if defined(__GNUC__) || defined(__clang__) |
olaf@270 | 137 | #define UCX_MUL_BUILTIN |
universe@303 | 138 | |
universe@303 | 139 | #if __WORDSIZE == 32 |
universe@303 | 140 | /** |
universe@303 | 141 | * Alias for <code>__builtin_umul_overflow</code>. |
universe@303 | 142 | * |
universe@303 | 143 | * Performs a multiplication of size_t values and checks for overflow. |
universe@303 | 144 | * |
universe@303 | 145 | * @param a first operand |
universe@303 | 146 | * @param b second operand |
universe@303 | 147 | * @param result a pointer to a size_t, where the result should |
universe@303 | 148 | * be stored |
universe@303 | 149 | * @return zero, if no overflow occurred and the result is correct, non-zero |
universe@303 | 150 | * otherwise |
universe@303 | 151 | */ |
universe@303 | 152 | #define ucx_szmul(a, b, result) __builtin_umul_overflow(a, b, result) |
universe@303 | 153 | #else /* __WORDSIZE != 32 */ |
universe@303 | 154 | /** |
universe@303 | 155 | * Alias for <code>__builtin_umull_overflow</code>. |
universe@303 | 156 | * |
universe@303 | 157 | * Performs a multiplication of size_t values and checks for overflow. |
universe@303 | 158 | * |
universe@303 | 159 | * @param a first operand |
universe@303 | 160 | * @param b second operand |
universe@303 | 161 | * @param result a pointer to a size_t, where the result should |
universe@303 | 162 | * be stored |
universe@303 | 163 | * @return zero, if no overflow occurred and the result is correct, non-zero |
universe@303 | 164 | * otherwise |
universe@303 | 165 | */ |
olaf@270 | 166 | #define ucx_szmul(a, b, result) __builtin_umull_overflow(a, b, result) |
universe@303 | 167 | #endif /* __WORDSIZE */ |
universe@303 | 168 | |
universe@303 | 169 | #else /* no GNUC or clang bultin */ |
universe@303 | 170 | |
universe@303 | 171 | /** |
universe@303 | 172 | * Performs a multiplication of size_t values and checks for overflow. |
universe@303 | 173 | * |
universe@303 | 174 | * This is a custom implementation in case there is no compiler builtin |
universe@303 | 175 | * available. |
universe@303 | 176 | * |
universe@303 | 177 | * @param a first operand |
universe@303 | 178 | * @param b second operand |
universe@303 | 179 | * @param result a pointer to a size_t, where the result should |
universe@303 | 180 | * be stored |
universe@303 | 181 | * @return zero, if no overflow occurred and the result is correct, non-zero |
universe@303 | 182 | * otherwise |
universe@303 | 183 | */ |
olaf@270 | 184 | int ucx_szmul(size_t a, size_t b, size_t *result); |
universe@303 | 185 | |
olaf@270 | 186 | #endif |
olaf@270 | 187 | |
olaf@5 | 188 | #ifdef __cplusplus |
olaf@5 | 189 | } |
olaf@5 | 190 | #endif |
olaf@5 | 191 | |
olaf@5 | 192 | #endif /* UCX_H */ |
olaf@5 | 193 |