1 /** 2 * @file cstl_public.h 3 * @copyright Copyright (c) Huawei Technologies Co., Ltd. 2021-2021. All rights reserved. 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 16 * @brief cstl_public 公共模块对外定义 17 * @details cstl公共定义实现源码 18 * @date 2021-05-14 19 * @version v0.1.0 20 * ******************************************************************************************* 21 * @par 修改日志： 22 * <table> 23 * <tr><th>Date <th>Version <th>Description 24 * <tr><td>2021-05-14 <td>0.1.0 <td>创建初始版本 25 * </table> 26 * ******************************************************************************************* 27 */ 28 29 #ifndef CSTL_PUBLIC_H 30 #define CSTL_PUBLIC_H 31 32 #include <stdint.h> 33 #include <stdbool.h> 34 #include <stddef.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif /* __cpluscplus */ 39 40 /* ******************************************************************************** */ 41 /* 公共错误码定义 */ 42 /* ******************************************************************************** */ 43 44 enum { 45 ERRNO_ELEMENT_EMPTY = 1, 46 ERRNO_INPUT_INVALID = 2, 47 ERRNO_NODE_CREATE_FAIL = 3, 48 }; 49 50 /** 51 * @ingroup cstl_public 52 * 0x0 正确。 53 */ 54 #define CSTL_OK 0 55 56 /** 57 * @ingroup cstl_public 58 * -1 错误。 59 */ 60 #define CSTL_ERROR (-1) 61 62 /** 63 * @ingroup cstl_public 64 * CSTL_ERRNO_BASE 错误码定义 65 */ 66 #define CSTL_ERRNO_BASE (uint32_t)0x0a03u 67 68 /** 69 * @ingroup cstl_public 70 * 容器不是NULL但是内容为空，该值为十六进制的0xa030001 71 */ 72 #define ERRNO_CSTL_ELEMENT_EMPTY ((CSTL_ERRNO_BASE << 16u) | ((uint32_t)ERRNO_ELEMENT_EMPTY)) 73 74 /** 75 * @ingroup cstl_public 76 * 容器的入参是非法的，该值为十六进制的0xa030002 77 */ 78 #define ERRNO_CSTL_INPUT_INVALID ((CSTL_ERRNO_BASE << 16u) | ((uint32_t)ERRNO_INPUT_INVALID)) 79 80 /** 81 * @ingroup cstl_public 82 * 节点创建失败，该值为十六进制的0xa030003 83 */ 84 #define ERRNO_CSTL_NODE_CREATE_FAIL ((CSTL_ERRNO_BASE << 16u) | ((uint32_t)ERRNO_NODE_CREATE_FAIL)) 85 86 /** 87 * @ingroup cstl_public 88 * @brief 比较函数原型 89 * @par 描述：比较函数原型，用于排序场景。 90 * @attention 注意：这里只定义了比较函数原型，由于不知道数据类型和长度，因此钩子函数需要业务自己实现。 91 * @param data1 [IN] 数据1 92 * @param data2 [IN] 数据2 93 * @retval >0 升序排序 94 * @retval =0 不做交换 95 * @retval <0 降序排序 96 */ 97 typedef int32_t (*CstlDataCmpFunc)(const void *data1, const void *data2); 98 99 /** 100 * @ingroup cstl_public 101 * @brief 比较函数原型 102 * @par 描述：比较函数原型，用于排序场景。 103 * @attention 注意：这里只定义了比较函数原型，由于不知道数据类型和长度，因此钩子函数需要业务自己实现。\n 104 * 当前源码内有默认的比较函数：该函数不对外提供，但是用户如果不指定默认比较方法会调用它，对此简单解释： 105 * 其比较方式为把当前数据转化为有符号数进行比较，即处理含有负数的场景，比较方式为升序。 106 * 如果用户需要存储的数据是无符号整数类型。此时排序结果可能不是预期的。 107 * 这种场景下的数据比较，用户需要自定义比较函数来解决这种情况的数据比较。 108 * 例如对于大数A = uintptr_t(-1) 和 大数 B = 1ULL << 50，目前的函数会认为A < B，实际上A是大于B的。 109 * 综上所述，用户对于使用什么样的比较函数，应该根据自己的数据类型来编写(包括降序或其它比较规则) 110 * @param key1 [IN] key1 111 * @param key2 [IN] key2 112 * @retval >0 升序排序 113 * @retval =0 不做交换 114 * @retval <0 降序排序 115 */ 116 typedef int32_t (*CstlKeyCmpFunc)(uintptr_t key1, uintptr_t key2); 117 118 /** 119 * @ingroup cstl_public 120 * @brief 匹配函数原型 121 * @par 描述：用于匹配查询场景。 122 * @attention 注意：这里只定义了函数原型，由于不知道用户查询匹配机制，因此钩子函数需要业务自己实现。 123 * @param node [IN] 算法结构体节点 124 * @param data [IN] 关键信息 125 * @retval true 匹配成功 126 * @retval false 匹配失败 127 */ 128 typedef bool (*CstlMatchFunc)(const void *node, uintptr_t data); 129 130 /** 131 * @ingroup cstl_public 132 * @brief 用户数据拷贝函数原型 133 * @attention 注意：源缓冲区长度需要调用者获取，由于不知道数据类型和长度，因此钩子函数需要业务自己实现。 134 * @param ptr [IN] 指向用户数据的指针 135 * @param size [IN] 用户数据拷贝长度 136 * @retval 目标缓冲区，NULL表示失败。 137 */ 138 typedef void *(*CstlDupFunc)(void *ptr, size_t size); 139 140 /** 141 * @ingroup cstl_public 142 * @brief 用户内存释放函数原型 143 * @par 描述：资源释放函数原型，一般用于机制批量free内存时，内存中可能含有用户私有资源，这是需要用户自行释放 144 * @param ptr [IN] 指向用户数据的指针 145 * @retval 无 146 */ 147 typedef void (*CstlFreeFunc)(void *ptr); 148 149 /** 150 * @ingroup cstl_public 151 * @brief 用户内存申请函数原型 152 * @attention 注意：用户内存申请函数原型，需要用户自己实现。 153 * @param size [IN] 内存申请大小 154 * @retval 指向分配内存空间的指针，NULL表示失败 155 */ 156 typedef void *(*CstlMallocFunc)(size_t size); 157 158 /** 159 * @ingroup cstl_public 160 * @brief 用户内存申请释放函数对 161 * @par 描述：内存申请和释放函数成对出现。 162 */ 163 typedef struct { 164 CstlMallocFunc mallocFunc; 165 CstlFreeFunc freeFunc; 166 } CstlMallocFreeFuncPair; 167 168 /** 169 * @ingroup cstl_public 170 * @brief key和value函数原型对 171 * @par 描述：key和value的拷贝及释放函数成对出现。 172 */ 173 typedef struct { 174 CstlDupFunc dupFunc; 175 CstlFreeFunc freeFunc; 176 } CstlDupFreeFuncPair; 177 178 /** 179 * @ingroup cstl_public 180 * @brief 该API通过结构的某个成员变量，得到这个结构的起始地址。 181 * @par 描述: 182 * 该API通过结构的某个成员变量，得到这个结构的起始地址。该API是一个特殊的宏，输入参数取决于宏的实现。 183 * @attention 184 * @param ptr [IN] 该参数表示结点某成员的地址。取值范围为数据类型。 185 * @param type [IN] 该参数表示传入的成员所属的结点类型结构。取值范围为数据类型。 186 * @param member [IN] 该参数表示结构中成员变量的名字。取值范围为数据类型。 187 * @retval 与入参类型相同结构的地址。 188 * @see 无。 189 */ 190 #define CSTL_CONTAINER_OF(ptr, type, member) \ 191 ((type *)((uintptr_t)(ptr) - (uintptr_t)(&(((type *)0)->member)))) 192 193 #ifdef __cplusplus 194 } 195 #endif /* __cpluscplus */ 196 197 #endif /* CSTL_PUBLIC_H */ 198