# 使用ConcurrentHashmap在多线程下完成键值信息的查找维护

FAST Kit提供的Concurrent HashMap（并发哈希表）专为高并发场景下的键值对数据管理而设计。主要用于实现多线程环境下的安全存储、快速访问与高效更新，适用于对并发吞吐量和数据一致性要求较高的增删改查操作，典型场景包括单点插入、删除、查询及并发修改等。

#### 接口说明

具体API说明详见接口文档。

| 名称 | 描述 |
| --- | --- |
| FAST_ErrorCode HMS_FAST_ConcurrentHashmap_Create (FAST_ConcurrentHashmapHandle* handle, HMS_FAST_ConcurrentHashmap_HashFunc hasher, HMS_FAST_ConcurrentHashmap_KeyEqualFunc equaler, float maxLoadFac, size_t numShards) | 使用给定配置创建并发哈希表。 |
| void HMS_FAST_ConcurrentHashmap_Destroy (FAST_ConcurrentHashmapHandle* handle) | 销毁指定并发哈希表。 |
| FAST_ErrorCode HMS_FAST_ConcurrentHashmap_Insert (FAST_ConcurrentHashmapHandle* handle, const FAST_ConcurrentHashmapKeyPtr key, const FAST_ConcurrentHashmapValuePtr value, FAST_ConcurrentHashmapValuePtr* originValue) | 将给定的键值对插入并发哈希表中，如果键已经存在，则使用value覆写原有的值，并将对应值的地址保存在originValue中。 |
| FAST_ErrorCode HMS_FAST_ConcurrentHashmap_Find (FAST_ConcurrentHashmapHandle* handle, const FAST_ConcurrentHashmapKeyPtr key, FAST_ConcurrentHashmapValuePtr* value) | 在给定并发哈希表中查找输入的键，并将对应的值保存在value中。 |
| FAST_ErrorCode HMS_FAST_ConcurrentHashmap_Erase (FAST_ConcurrentHashmapHandle* handle, const FAST_ConcurrentHashmapKeyPtr key, FAST_ConcurrentHashmapKeyPtr* originKey, FAST_ConcurrentHashmapValuePtr* originValue) | 在给定哈希表中删除输入的键，并将键/值对应的地址保存在originKey和originValue中。 |
| FAST_ErrorCode HMS_FAST_ConcurrentHashmap_TryInsert (FAST_ConcurrentHashmapHandle* handle, const FAST_ConcurrentHashmapKeyPtr key, const FAST_ConcurrentHashmapValuePtr value) | 将给定的键值对插入并发哈希表中，如果键已经存在、则不做操作。 |
| size_t HMS_FAST_ConcurrentHashmap_Size (FAST_ConcurrentHashmapHandle* handle) | 返回给定哈希表当前的元素个数。 |
| void HMS_FAST_ConcurrentHashmap_Clear (FAST_ConcurrentHashmapHandle* handle) | 清空给定哈希表中维护的所有元素。 |
| size_t HMS_FAST_ConcurrentHashmap_EraseIf (FAST_ConcurrentHashmapHandle* handle, HMS_FAST_ConcurrentHashmap_HookFunc condFunc, void* condCtx, HMS_FAST_ConcurrentHashmap_HookFunc freeFunc, void* freeCtx) | 删除哈希表中符合开发者定义条件的所有元素，并使用开发者定义的方式释放其内存。 |
| void HMS_FAST_ConcurrentHashmap_Traverse (FAST_ConcurrentHashmapHandle* handle, HMS_FAST_ConcurrentHashmap_HookFunc condFunc, void* condCtx, HMS_FAST_ConcurrentHashmap_HookFunc workFunc, void* workCtx) | 遍历哈希表，将所有符合开发者输入条件的键值对按开发者给定的方式修改。 |

#### 开发步骤

1.  在CMake脚本中链接相关动态库。
    
    ```
     find_library(
         lib_fast_ads
         NAMES fast_ads
     )
    target_link_libraries(entry PRIVATE ${lib_fast_ads})
    ```
    
2.  调用相关接口能力完成键值信息的管理。
    
    ```
    #include "FASTKit/fast_ads_concurrent_hashmap.h"
    
    // 定义哈希值如何计算，键如何比较
    uint64_t custom_hash_int(const FAST_ConcurrentHashmapKeyPtr key) {
        static std::hash<int> hasher;
        int* intKey = (int*)key;
        return hasher(*intKey);
    }
    
    int32_t custom_equal_int(const FAST_ConcurrentHashmapKeyPtr key1, const FAST_ConcurrentHashmapKeyPtr key2) {
        int* intKey1 = (int*)key1;
        int* intKey2 = (int*)key2;
        return (*intKey1) == (*intKey2);
    }
    
    // 自定义删除条件
    int32_t custom_erase_cond(FAST_ConcurrentHashmapKeyPtr key, FAST_ConcurrentHashmapValuePtr val, void* context) {
        return 1;
    }
    
    // 释放键和值指针持有的内存
    int32_t custom_free(FAST_ConcurrentHashmapKeyPtr key, FAST_ConcurrentHashmapValuePtr val, void* context) {
        int* intKey = (int*)key;
        int* intVal = (int*)val;
        delete intKey;
        delete intVal;
        return 0;
    }
    
    // 自定义修改条件，也可传入nullptr以对所有元素执行修改
    int32_t custom_modify_cond(FAST_ConcurrentHashmapKeyPtr key, FAST_ConcurrentHashmapValuePtr val, void* context) {
        return 1;
    }
    
    int32_t custom_work(FAST_ConcurrentHashmapKeyPtr key, FAST_ConcurrentHashmapValuePtr val, void* context) {
        int* intVal = (int*)val;
        int* intCtx = (int*)context;
        *intVal += (*intCtx);
        return 1;
    }
    
    static napi_value RunConcurrentHashmap(napi_env env, napi_callback_info info)
    {
        // 使用合适的配置创建并发哈希表，负载因子（loadfac）和分段数（numShards）的典型值一般为0.8和64。
        // 负载因子主要作用于分段内部，更大的负载因子通常意味着更小的内存消耗和更大的操作开销；
        // 分段数主要作用域并发哈希表全局，更大的分段数通常意味着更好的并发性能和更大的内存消耗
        FAST_ConcurrentHashmapHandle handle;
        HMS_FAST_ConcurrentHashmap_HashFunc hasher = &custom_hash_int;
        HMS_FAST_ConcurrentHashmap_KeyEqualFunc equaler = &custom_equal_int;
        float loadfac = 0.8;
        size_t numShards = 64;
        int ret = HMS_FAST_ConcurrentHashmap_Create(&handle, hasher, equaler, loadfac, numShards);
    
        // 初始化空的哈希表并向其中插入元素
        const int size = 10;
        int keys[size] = {1,2,3,4,5,6,7,8,9,10};
        int vals[size] = {1,2,3,4,5,6,7,8,9,10};
        for (int i = 0; i < size; ++i) {
            ret = HMS_FAST_ConcurrentHashmap_Insert(
                handle,
                (FAST_ConcurrentHashmapKeyPtr)&(keys[i]),
                (FAST_ConcurrentHashmapValuePtr)&(vals[i]),
                nullptr
            );
        } // 完成插入后哈希表中应包含 {1: 1, 2: 2, ..., 10: 10}
        
        // 使用insert覆写已有的key，如果使用tryInsert则不会覆写
        int key2 = 1;
        int val2 = 2;
        int* originVal0;
        ret = HMS_FAST_ConcurrentHashmap_Insert(
            handle,
            (FAST_ConcurrentHashmapKeyPtr)&key2,
            (FAST_ConcurrentHashmapValuePtr)&val2,
            (FAST_ConcurrentHashmapValuePtr*)&originVal0
        ); // {1: 2, ...}, 且originVal0 == &vals[0]
    
        // 键查找对应的值，并将结果保存在输入指针中。开发者需注意在使用此接口时应校验返回值ret，
        // 如果ret值不等于FAST_ERROR_CODE_SUCCESS，则res获取到的值是无效的
        int targetKey = 1;
        int* res;
        ret = HMS_FAST_ConcurrentHashmap_Find(
            handle,
            (FAST_ConcurrentHashmapKeyPtr)&targetKey,
            (FAST_ConcurrentHashmapValuePtr*)&res
        ); // (*res) == 2
    
        // 键删除并发哈希表中对应的键值对，并获取关联内存的地址
        // 可以使用originKey/Val获得预先插入的元素地址，便于内存管理，可以使用nullptr作为入参
        int* originKey1;
        int* originVal1;
        int deleteKey = 1;
        ret = HMS_FAST_ConcurrentHashmap_Erase(
            handle,
            (FAST_ConcurrentHashmapKeyPtr)&deleteKey,
            (FAST_ConcurrentHashmapKeyPtr*)&originKey1,
            (FAST_ConcurrentHashmapValuePtr*)&originVal1
        ); // originKey1 == &keys[0] && originVal1 == &val2
    
        // 查询并发哈希表当前元素个数
        size_t curSize = HMS_FAST_ConcurrentHashmap_Size(handle); // curSize == 9
    
        // 清空并发哈希表中所有元素
        HMS_FAST_ConcurrentHashmap_Clear(handle);
        curSize = HMS_FAST_ConcurrentHashmap_Size(handle); // curSize == 0
    
        for (int i = 0; i < 6; i++) {
            int* key = new int{i};
            int* val = new int{i};
            ret = HMS_FAST_ConcurrentHashmap_Insert(
                handle,
                (FAST_ConcurrentHashmapKeyPtr)key,
                (FAST_ConcurrentHashmapValuePtr)val,
                nullptr
            );
        } // {0: 0, 1: 1, 2: 2, 3: 3, 4: 4, 5: 5}
    
        // 使用Traverse接口对符合custom_modify_cond的元素执行custom_work操作
        int context = 10;
        HMS_FAST_ConcurrentHashmap_Traverse(
            handle,
            (HMS_FAST_ConcurrentHashmap_HookFunc)&custom_modify_cond,
            nullptr,
            (HMS_FAST_ConcurrentHashmap_HookFunc)&custom_work,
            (void*)&context
        ); // {0: 10, 1: 11, 2: 12, 3: 13, 4: 14, 5: 15}
    
        // 使用EraseIf接口删除所有符合custom_erase_cond的键值对并使用custom_free清理相应的内存
        ret = HMS_FAST_ConcurrentHashmap_EraseIf(
            handle,
            (HMS_FAST_ConcurrentHashmap_HookFunc)&custom_erase_cond,
            nullptr,
            (HMS_FAST_ConcurrentHashmap_HookFunc)&custom_free,
            nullptr
        ); // size == 0 && ret == 6
    
        // 销毁并发哈希表
        HMS_FAST_ConcurrentHashmap_Destroy(handle);
        return 0;
    }
    ```