### TAF Framework Service Examples

Source: https://github.com/veekocnn/taf-dcache/blob/main/README.md

This snippet provides examples related to the TAF framework's C++ services, including project structure, JCE protocol usage, and RPC call examples.

```c++
// TAF Project Structure Example
// JCE Protocol Example
// RPC Call Example
```

--------------------------------

### Get All Main Keys

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves all main keys from the cache. This function is designed for batched retrieval, with a recommended batch size not exceeding 10,000 hash buckets. It indicates if there are more buckets to fetch.

```C++
int getMKAllMainKey( int index, int count, vector<string> &mainKey, bool &isEnd )
```

```C++
// We need to fetch data in batches, and it is recommended that each batch does not exceed 10,000
    while(!isEnd){
        std::vector<string> tmp;
        DCacheOpt::getInstance()->getClient().getMKAllMainKey(index,5000,tmp,isEnd);
        index +=5000;
        for(auto&id:tmp){
            cout << id <<endl;
        }
    }
```

--------------------------------

### Get String Value

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves a string value associated with a given main key. Overloads are provided to either ignore the version or retrieve the value along with its version.

```C++
int getString(const K& mainKey,string &val)
int getString(const K& mainKey,string &val ,taf::Char& ver)
```

--------------------------------

### KV Module API (DCacheAPI_N.h)

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Provides core Key-Value (KV) operations using the DCacheAPI_N.h interface. This includes getting and setting string values individually and in batches, deleting string values, and updating string values with various operations.

```APIDOC
getString(mainKey, val)
  - Retrieves a string value.
  - Overloads:
    - getString(const K& mainKey, string &val)
    - getString(const K& mainKey, string &val, taf::Char& ver)
  - Parameters:
    - mainKey: The primary key.
    - val: Output parameter for the retrieved value.
    - ver: Output parameter for the version (if applicable).

getBatch(keys)
  - Retrieves multiple string values in a batch.
  - Template parameter V specifies the value type.
  - Parameters:
    - keys: A vector of main keys.
  - Returns: A BatchKeyValues<V> object containing results for each key.
    - BatchKeyValues.getRet(): Overall return status.
    - BatchKeyValues[i].ret: Return status for the i-th key.
    - BatchKeyValues[i].value: The retrieved value for the i-th key.
    - BatchKeyValues[i].ver: The version of the i-th key's value.
    - BatchKeyValues[i].expireTime: The expiration time for the i-th key's value.

delString(mainKey)
  - Deletes a string value associated with the main key.
  - Parameters:
    - mainKey: The primary key of the value to delete.

setString(mainKey, val, [expireTimeSecond], [ver])
  - Inserts or updates a string value.
  - Parameters:
    - mainKey: The primary key.
    - val: The string value to set.
    - expireTimeSecond: Optional expiration time in seconds (relative).
    - ver: Optional version number (1-255; 0 for no version).

setStringWithVer(mainKey, val, ver)
  - Inserts or updates a string value with a specific version.
  - Parameters:
    - mainKey: The primary key.
    - val: The string value to set.
    - ver: The version number (1-255).

setBatch(keys, values, [expire_time], [bNoResp])
  - Inserts multiple key-value pairs in a batch.
  - Parameters:
    - keys: A vector of keys.
    - values: A vector of corresponding values.
    - expire_time: Optional expiration time in seconds (relative).
    - bNoResp: Optional flag to suppress response.

updateString(mainKey, val, option, retValue, [expireTimeSecond])
  - Updates a string value with specified options.
  - Parameters:
    - mainKey: The primary key.
    - val: The new value or delta.
    - option: The update operation (ADD, ADD_INSERT, SUB, SUB_INSERT, PREPEND, APPEND).
    - retValue: Output parameter for the updated value.
    - expireTimeSecond: Optional expiration time in seconds (relative).
```

--------------------------------

### Batch Get String Values

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves multiple string values in a batch using a vector of main keys. The `BatchKeyValues` struct contains the overall return status and individual results for each key, including value, version, and expiration time.

```C++
template<typename V>
BatchKeyValues<V> getBatch(const vector<K>& keys)
```

--------------------------------

### Batch Get Range from Sorted Set by Index

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

A batch version of getRangeZSet, allowing multiple range queries on different main keys. Each main key has its own return value, and duplicate main keys can be provided.

```APIDOC
int getRangeZSetBatch( const vector<DCache::GetRangeZSetBatchInfo> &vtInfo, const std::string & field, taf::Bool bUp, vector<SelectResult>& vtResults )

Parameters:
  vtInfo: A vector of GetRangeZSetBatchInfo structs, each specifying:
    mainKey: The primary key of the sorted set.
    iStart: The starting index of the range (inclusive, 0-based).
    iEnd: The ending index of the range (inclusive).
  field: A comma-separated string of fields to query, or "*" for all fields.
  bUp: Boolean indicating the sort order. true for ascending, false for descending.
  vtResults: A vector of SelectResult objects to store the query results for each mainKey.

Usage Example:
  MultiRowBuilder builder;
  vector<SelectResult> vtResults;
  builder.createGetRangeItem("111",0,10)
         .createGetRangeItem("222",10,20);
  bool bUp = true;
  int iRet = DCacheOpt::getInstance()->getClient().getRangeZSetBatch(builder,"*",bUp,vtResults);
  for(auto &item : vtResults) {
      string mk = item.getMainKey();
      int ret = item.getReturnValue();
      auto value = item.data();
  }
```

```C++
int getRangeZSetBatch( const vector<DCache::GetRangeZSetBatchInfo> &vtInfo, const std::string & field, taf::Bool bUp, vector<SelectResult>& vtResults )
```

--------------------------------

### Batch Get Values in DCache - C++

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves multiple values from DCache using a vector of keys and stores them in a result vector. Returns an integer status code.

```C++
int getBatch( const vector<K> &vk, vector<V> &v )
```

--------------------------------

### Batch Get Rank and Score from Sorted Set

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves the rank and score for multiple records in a sorted set based on specified conditions. It supports a main key with a value condition. The order of results for the same main key with different value conditions is consistent with the input order. This function can replace individual getRankZset and getScoreZset batch operations.

```APIDOC
int getRankAndScoreZSetBatch(const vector<DCache::RankAndScoreKey>& keyInfo, bool bOrder, DCache::GetRankAndScoreZSetBatchRsp &rsp)

Parameters:
  keyInfo: A vector of RankAndScoreKey structs, where each struct contains:
    sMainKey: The main key of the sorted set.
    vtCond: A vector of Condition structs representing value conditions.
  bOrder: A boolean indicating the desired order (true for ascending, false for descending).
  rsp: A reference to a GetRankAndScoreZSetBatchRsp struct to store the results.

Structs:
  RankAndScoreKey:
    string sMainKey;
    vector<Condition> vtCond;
  GetRankAndScoreZSetBatchRsp:
    vector<RankAndScoreValue> value;
  RankAndScoreValue:
    string mainKey;
    long iPos; // Rank of the element satisfying the condition.
    double dScore; // Score of the element satisfying the condition.
    int ret; // Return value for this specific query.

Usage Example:
  MultiRowBuilder MBuilder;
  MBuilder.createGetRankAndScoreItem("test0").where(ZSet::value1==18).where(ZSet::value2==1)
          .createGetRankAndScoreItem("test1").where(ZSet::value1==22).where(ZSet::value2==1)
          .createGetRankAndScoreItem("test2").where(ZSet::value1==26).where(ZSet::value2==0);
  DCache::GetRankAndScoreZSetBatchRsp rsp;
  bool bOrder = true;
  int ret = DCacheOpt::getInstance()->getClient().getRankAndScoreZSetBatch(MBuilder, bOrder, rsp);
  for(auto& item : rsp.value){
      cout << "mk: " << item.mainKey << endl;
      cout << "    position: " << item.iPos << endl;
      cout << "    score: " << item.dScore << endl;
      cout << "    ret: " << item.ret << endl;
  }
  cout << "ret " << ret << endl;
```

```C++
int getRankAndScoreZSetBatch(const vector<DCache::RankAndScoreKey>& keyInfo, bool bOrder,DCache::GetRankAndScoreZSetBatchRsp &rsp)
```

--------------------------------

### Batch Get Values in DCache (Template API_N) - C++

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Provides a template function to retrieve multiple values from DCache using a vector of keys. The return value includes an overall status and individual status/data for each key. Individual item status codes include 0 for success, -6 for no data, and -1 for error.

```C++
template<typename V>
BatchKeyValues<V> getBatch(const vector<K>& keys)
```

```C++
//使用方法：
vector<string> vk;
vk.push_back("1123");
vk.push_back("1124");
auto retValues = DCacheOpt::getInstance()->getClient().getBatch<string>(vk);
cout << "getBatch return: " << retValues.getRet() << endl; 
for(size_t i = 0; i < vk.size() && i < retValues.size(); ++i) {
    cout << "mk: " << vk[i] << "|ret: " << retValues[i].ret << "|value: " << retValues[i].value
         << "|ver: " << (int)retValues[i].ver << "|expireTime: " << retValues[i].expireTime << endl;
}
```

```C++
//BatchKeyValues类型：
template<typename V>
struct BatchKeyValues
{
    BatchKeyValues()
    {

    }
    struct Items
    {
        Items() : ret(-1),ver(0),expireTime(0){}
        Items(taf::Int32 iRet) : ret(iRet),ver(0),expireTime(0){}
        Items(const V&v , taf::Int32 iRet,taf::Char cVer, taf::Int64 iExpire ) : value(v)
        {
            ret = iRet;
            ver = cVer;
            expireTime = iExpire;
        }
        V value;
        taf::Int32 ret;
        taf::Char ver;
        taf::Int64 expireTime;
    };
    size_t size() const
    {
        return values.size();
    }
    bool empty() const
    {
        return values.empty();
    }
    Items& operator[](size_t i) {
        return values[i];
    }
    int getRet() {
        return iRet;
    }
    typedef vector<Items> vContainer;
    typedef typename vContainer::iterator iterator;
    iterator begin() {
        return values.begin();
    }
    iterator end() {
        return values.end();
    }

    int iRet;
    vector<Items> values;
};
```

--------------------------------

### Get Range from Sorted Set by Index

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves data from a sorted set within a specified index range (inclusive). The function allows specifying the field(s) to retrieve and the order of results.

```APIDOC
int getRangeZSet( const K &mainKey, const std::string &field, taf::Int64 iStart, taf::Int64 iEnd, taf::Bool bUp, SelectResult &result )

Parameters:
  mainKey: The primary key of the sorted set.
  field: A comma-separated string of fields to query, or "*" for all fields.
  iStart: The starting index of the range (inclusive, 0-based).
  iEnd: The ending index of the range (inclusive).
  bUp: Boolean indicating the sort order. true for ascending, false for descending.
  result: A reference to a SelectResult object to store the query results.

Notes:
  - When bUp is true, the query starts from iStart and proceeds in the direction of increasing score.
  - When bUp is false, the query starts from (total elements - iEnd + 1) and proceeds in the direction of increasing score, fetching (iEnd - iStart + 1) elements.
```

```C++
int getRangeZSet( const K &mainKey, const std::string &field, taf::Int64 iStart, taf::Int64 iEnd, taf::Bool bUp, SelectResult &result )
```

--------------------------------

### Get Value in DCache - C++

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves a value from DCache using a main key. Overloads allow retrieving the value along with its timestamp and version number. Returns an integer status code.

```C++
int get( const K &k, V &v )
```

```C++
int getWithVer( const K &k, V &v, int &iTimespan, taf::Int64 &lVersion )
```

--------------------------------

### Batch Get Sorted Set by Score

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves data records from multiple main keys in a ZSet within a specified score range. Supports filtering by score and position. The function has two overloads: one for individual key conditions and another for unified conditions across multiple keys. It's recommended to use this for score-based range queries and avoid value conditions for performance.

```C++
int getRangeZSetByScoreBatch(const vector<RangeZSetByScoreKey> & keyInfo, const std::string& field,  map<string, SelectResult>& result)

//all mainkeys with unified condition
int getRangeZSetByScoreBatch(const vector<K> &vtMainKeys, const vector<Field> &vtFields, const vector<Condition> &vtConds, map<K, SelectResult>& result)
```

```APIDOC
getRangeZSetByScoreBatch:
  Description: Batch query for specified data records in ZSet of multiple main keys within a score range.
  Parameters:
    keyInfo: A collection of main keys, where each key can have associated conditions.
      struct RangeZSetByScoreKey {
        string mainKey;
        vector<Condition> cond;
      };
    field: A set of fields to query. "*" for all fields, or a comma-separated string for specific fields.
    result: A map to store the query results, where the key is the main key and the value is a SelectResult object.
      class SelectResult {
      public:
        vector<map<string, string>>& data(); // Returns all field values as strings.
        size_t size(); // Returns the number of records.
        void clear(); // Clears the result set.
        int& getReturnValue(); // Gets the return value of the query.
      };
  Usage Examples:
    // Usage 1: Using MultiRowBuilder
    MultiRowBuilder MBuilder;
    MBuilder.createGetRangeZSetByScoreItem("test0").where(ZSet::ScoreValue > 0).where(ZSet::ScoreValue < 500).pos(0,10)
            .createGetRangeZSetByScoreItem("test1").where(ZSet::ScoreValue > 0).where(ZSet::ScoreValue < 500).pos(0,10)
            .createGetRangeZSetByScoreItem("test2").where(ZSet::ScoreValue > 0).where(ZSet::ScoreValue < 500).pos(0,10);
    int ret = DCacheOpt::getInstance()->getClient().getRangeZSetByScoreBatch(MBuilder, "*", result);

    // Usage 2: Using vector<RangeZSetByScoreKey>
    vector<RangeZSetByScoreKey> keyInfo;
    vector<Condition> cond;
    vector<string> mainKey = {"test0", "test1", "test2"};
    for(auto& item : mainKey){
        RangeZSetByScoreKey tmpKeyInfo;
        tmpKeyInfo.mainKey = item;
        tmpKeyInfo.cond.emplace_back(std::move(ZSet::ScoreValue > 0));
        tmpKeyInfo.cond.emplace_back(std::move(ZSet::ScoreValue < 500));
        Condition limitCond;
        limitCond.fieldName = "";
        limitCond.op = DCache::LIMIT;
        limitCond.value = TC_Common::tostr(0) + ":" + TC_Common::tostr(10);
        tmpKeyInfo.cond.emplace_back(std::move(limitCond));
        keyInfo.emplace_back(tmpKeyInfo);
    }
    map<string, SelectResult> result;
    int ret = DCacheOpt::getInstance()->getClient().getRangeZSetByScoreBatch(keyInfo, "*", result);

  Recommendations:
    - Avoid using vtValueCond and vtScoreCond together due to poor performance; filter values manually if needed.
    - If no value or score conditions are provided, consider using getRangeZSetBatch instead.
    - For score-based range queries, use this function.
    - For value-based conditions, use getRankAndScoreZSetBatch.
```

--------------------------------

### Getting KV String Value - C++

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves the string value associated with a given main key from a Key-Value store. Two overloaded versions are provided: one that only returns the value and another that also returns the version number. Parameters include the main key and an output parameter for the value (and optionally version). Returns an integer status code.

```C++
int getString(const K& mainKey,string &val)
int getString(const K& mainKey,string &val ,taf::Char& ver)
```

--------------------------------

### Initialize DCache Client

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Steps to initialize the DCache client, including modifying the makefile, declaring and initializing the DCacheAPI_N variable using TAF configurations for proxy and module names, and setting the timeout.

```c++
#include "DCacheAPI_N.h"
// <std::string>表示该dcache模块的mkey是string类型
DCache::DCacheAPI_N<std::string> m_dcaheCustomInfo;

// TAF配置文件类
TC_Config m_configFile;
// TAF配置中获取dcache模块proxy
const string& proxyName = m_configFile.get( "/obj/huyavideo-cp-dcache/<proxy-name>", "DCache.HUYADataProxyServer.ProxyObj");
// TAF配置中获取dcache模块module
const string& moduleName = m_configFile.get( "/obj/huyavideo-cp-dcache/<module-name>", "HUYACustomInfo");
m_dcaheCustomInfo.init(Application::getCommunicator(), proxyName, moduleName, 3000/*timeout*/);
```

--------------------------------

### Get Range from Sorted Set by Score

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Retrieves data from a sorted set within a specified score range (inclusive). The function allows specifying the field(s) to retrieve.

```APIDOC
int getRangeZSetByScore( const K &mainKey, const std::string &field, taf::Double iMin, taf::Double iMax, SelectResult &result )

Parameters:
  mainKey: The primary key of the sorted set.
  field: A comma-separated string of fields to query, or "*" for all fields.
  iMin: The minimum score of the range (inclusive).
  iMax: The maximum score of the range (inclusive).
  result: A reference to a SelectResult object to store the query results.
```

```C++
int getRangeZSetByScore( const K &mainKey, const std::string &field, taf::Double iMin, taf::Double iMax, SelectResult &result )
```

--------------------------------

### DCache_Struct Macro Usage

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Demonstrates the usage of the DCache_Struct macro to define data structures for DCache modules. It shows how to create namespaces and map ukey and value fields, and how to use the DBuilder for update operations.

```c++
//DCache_Struct是一个宏，它会创建以第一个参数为名称的命名空间
//创建名称为DCACHE_Hash的命名空间，timestamp、count、xxx为uk和value字段
// DCache_Struct(DCACHE_Hash,timestamp,count,xxx)
//创建名称为DCACHE_Rank的命名空间，uid、sex、age为uk和value字段
// DCache_Struct(DCACHE_Rank,uid,sex,age)
// 具体：创建名称为Hash的命名空间，biz为ukey和value字段:name, address, number
DCache_Struct(DCACHE_CustomInfo, biz, name, address, number);

//使用：
DBuilder builder;
// 更新操作:设置map<string, UpdateValue>
builder.set(DCACHE_CustomInfo::name="tuomasi").set(DCACHE_CustomInfo::number=7758258);

m_dcaheCustomInfo.updateAtom(key, builder.updateValues, builder.vConds);
```

--------------------------------

### Select Data (KKV Module)

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Queries data based on specified fields and conditions. Supports selecting all fields or specific fields, and applying conditions on fields other than the main key. It can return results in SelectResult or DCacheRow objects and optionally the total count of records.

```C++
int select( const K &k, const vector<Field> &vtFields, const vector<Condition> &vtConds, SelectResult &result, bool totalCount = false )
```

```C++
// Usage 1, using SelectResult
SelectResult result;
int iRet = DCacheOpt::getInstance()->getClient().select( "mainkey", SELECT_ALL, {}, result );
if(iRet>0){ // Data exists
}

// Usage 2, using DCacheRow
DCacheRow row;
// Select columns where age > 10 in mainkey, and return fields Rank::uid, Rank::name
// Equivalent to SQL: 'select uid,name from mainkey where age >10;
DCacheOpt::getInstance()->getClient().select( "mainkey", {Rank::uid,Rank::name}, {Rank::age>10}, row );
// Can be iterated directly
for (auto &item:row) {
    // Automatically converts the right-side value to the left-side type
    long uid = item[Rank::uid];
    string name = item[Rank::name];
    // Method to get version number: This is for printing in the log
    cout << "ver:" << item.getVersionPrint() << endl;
    // If CAS needs to be implemented, item.getVersion() should be used
}
```

```C++
// Paging query:
// In KKV, the select interface supports the SELECT_ALL flag, but if the data volume is too large, it will cause performance issues. Therefore, the pos parameter of select condition is provided to provide paging ukey select.
// Please note: Due to the current implementation where ukeys are linked using a linked list, the positioning operation of pos start, end is O(N). Therefore, the typical use of pos operations is:
// 1. Set DCache to have the insertion order as the ukey order
// 2. Select the latest N pieces of data: pos 0, N
// Code is as follows:
// DCache_Struct(hash,ukey,value)
// SelectResult result;
// DBuilder builder;
// builder.where(hash::ukey > 1).where(hash::ukey < 10).pos(0, 2);
//
// int iRet = DCacheOpt::getInstance()->getClient().select( "mainkey", SELECT_ALL, builder.genCondition(), result );
// if(iRet>0){ // Data exists
// }
//
// Note:
// ==TC_Common::strto<int> causes CAS to fail due to DCache version number conversion==
// Some people use it like this, hoping to do CAS, 100% failure, users say it has always been okay before, because between 0 ~48, TC_Common::strto<int> ===0, 0 means CAS failure, version is ignored!! But after 49, TC_Common::strto<int> ===1, it will report version_mismatch.
// Should use ` iCacheVersion = DCache::SelectResult::CastVersion(fields["@DataVer"]);`
```

--------------------------------

### DCache Common Interfaces: getMainKeyCount and getMainKeyCountBatch

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Provides details on common interface methods for KKV, list, set, and zset modules. getMainKeyCount retrieves the number of records for a given main key, while getMainKeyCountBatch retrieves counts for multiple main keys.

```APIDOC
int getMainKeyCount( const K &sMainIndex, bool bCheckExpire = false )
**功能：** 获取主键下数据记录总数，
**详细说明：** 在KKV中，将返回Ukey个数，在zset/list/set中，将返回mainkey下的元素个数。
**时间复杂度：** O(1)
**参数：**  
sMainIndex 主键
bCheckExpire 为false时获取的数据记录总数会包含已过期的数据，设为true可过滤已过期的数据，复杂度由O(1)->O(N)

template<typename KK>
int getMainKeyCountBatch( const vector<KK> &vtMainKey, map<KK, int> &keyCount, bool bCheckExpire = false )
**功能：** 获取多个主键下数据记录总数
**时间复杂度：** O(n)，n为元素个数
**参数：**  
vtMainKey 主键
keyCount 返回每个key对应的记录个数
bCheckExpire 为false时获取的数据记录总数会包含已过期的数据，设为true可过滤已过期的数据，复杂度由O(1)->O(N)
```

--------------------------------

### Batch Insert Data

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Inserts a batch of data into DCache. The `builder` object constructs the data, and `mpFailReasons` records reasons for partial failures. Supports various configurations like version, dirty flag, overwrite, and timeout.

```C++
int insertBatch( const InsertBatchBuilder &builder, map<int, int> &mpFailReasons );

// Example Usage:
MultiRowInserter builder;
auto &oneRow = builder.createKKVItem( 123456 );
oneRow.set( imname = "alex" );
oneRow.set( nickname = "nick" );
builder.createKKVItem( 123456 ).set( imname = "alex2" ).set( nickname = "222nick" )
       .createKKVItem( 123457 ).set( imname = "alex3" ).set( nickname = "333nick" )
       .createKKVItem( 123457 ).set( imname = "alex4" ).set( nickname = "333nick" );

// With custom parameters:
builder.createKKVItem( 123456 ,0,true,true).set( imname = "alex2" ).set( nickname = "222nick" )
       .createKKVItem( 123457 ,0,true,true).set( imname = "alex3" ).set( nickname = "333nick" )
       .createKKVItem( 123457 ,0,true,true).set( imname = "alex4" ).set( nickname = "333nick" );

map<int, int> mpFailReasons;
int ret = DCacheOpt::getInstance()->getClient().insertBatch( builder, mpFailReasons );
cout << "insertBatch:" << ret << endl;
```

--------------------------------

### TAF C++ Component Libraries Overview

Source: https://github.com/veekocnn/taf-dcache/blob/main/README.md

This section outlines the common component libraries used within the TAF C++ framework for the taf-dcache project. It details functionalities like event consumption, push capabilities, database operations, and DCache operations.

```c++
// EventMq: Event consumption for gifts, heartbeats
// Push capabilities: Broadcast, unicast
// Sending pop-up messages
// Database operations
// DCache operations
```

--------------------------------

### TAF-DCACHE selectBatchOr Function

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Performs batch queries where different main keys can have different query conditions, or the same main key can be queried with multiple conditions, similar to SQL's 'SELECT ... IN (a,b,c)'. It also supports pagination.

```C++
int selectBatchOr( const vector<DCache::SelectBatchOrReq> &vtKey, vector<SelectResult>& vtResults, const map<string, string> &context = TAF_CONTEXT() )
int selectBatchOr( const MultiRowBuilder& builder, vector<SelectResult>& vtResults, const map<string, string> &context = TAF_CONTEXT() )

Parameters:
- vtKey: Collection of main keys, including necessary query information.
- vtResults: Vector to store query results.
- context: Optional context map.

SelectBatchOrReq struct:
struct SelectBatchOrReq {
    std::string mainKey;
    std::string field;
    vector<DCache::Condition> vtCond;
    taf::Bool bGetMKCout;
}

Usage Examples:
// Usage 1: Directly constructing the struct.
{
    vector<SelectResult> vtResult;
    DBuilder builder;
    builder.add(Hash::UKEY == "10000");
    vector<SelectBatchOrReq> req;
    SelectBatchOrReq s1("123", "*", builder.vConds, false);
    SelectBatchOrReq s2("999888", "*", builder.vConds, false);
    builder.clear();
    builder.add(Hash::UKEY == "1");
    SelectBatchOrReq s3("123", "*", builder.vConds, false);
    req.emplace_back(s1);
    req.emplace_back(s2);
    req.emplace_back(s3);
    int ret = DCacheOpt::getInstance()->getClient().selectBatchOr(req, vtResult);
}

// Usage 2: Using builder for chained expressions.
{
    vector<SelectResult> vtResult;
    MultiRowBuilder builder;
    builder.createSelectBatchOr("123", "*", false).where(Hash::UKEY == "1")
           .createSelectBatchOr("123")
           .createSelectBatchOr("999888");
    int ret = DCacheOpt::getInstance()->getClient().selectBatchOr(builder, vtResult);
}

// Usage 3: Using builder and saving intermediate variables.
{
    auto &selectBatchOrItem = builder.createSelectBatchOr("123", "*", false).where(Hash::UKEY == "1");
    selectBatchOrItem.createSelectBatchOr("123"); // condition is empty
    selectBatchOrItem.createSelectBatchOr("999888");
}

// Processing return values:
for(auto &item : vtResult) {
    cout << "mainkey: " << item.getMainKey() << endl; // mk
    cout << "total record: " << item.totalRecords() << endl; // number of records
    printSelectResult(item.data()); // data
    cout << "=========================" << endl;
}

Performance Notes:
- Similar to selectBatch, performance depends on whether the UKEY is fully provided in the conditions.
```

--------------------------------

### Batch Set String Values

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Inserts multiple string values in a batch. It takes vectors of keys and corresponding values, with an optional expiration time and a flag to suppress response.

```C++
template<typename V>
int setBatch(const vector<K> &keys, const vector<V> &values, int expire_time = 0 , bool bNoResp = false)
```

--------------------------------

### TAF-DCACHE selectBatch Function

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Performs a batch query where multiple main keys share the same query conditions. It supports pagination by specifying a position. The performance depends on whether the unique key (UKEY) is fully provided in the conditions.

```C++
int selectBatch( const vector<K> &vtMainKeys, const vector<Field> &vtFields, const vector<Condition> &vtConds, map<K, SelectResult> &mpKResults )

Parameters:
- vtMainKeys: Collection of main keys.
- vtFields: Fields to query, "*" for all.
- vtConds: Query conditions for fields other than the main key. Multiple conditions are ANDed.
- mpKResults: Map to store query results.

Usage Examples:
// Example 1: Assuming Hash::uid is the UKEY, with at most one hit.
{
    DBuilder builder;
    builder.add(Hash::uid==2341);
    map<string, SelectResult> mpResults;
    int iRet = DCacheOpt::getInstance()->getClient().selectBatch( vmainKey, SELECT_ALL, builder.vConds, mpResults );
}

// Example 2: Assuming Hash::uid and Hash::imid are UKEYs, but only uid is used in the condition.
{
    DBuilder builder;
    builder.add(Hash::uid==2341);
    builder.pos(0,1000); // Original limit, now referred to as position.
    map<string, SelectResult> mpResults;
    int iRet = DCacheOpt::getInstance()->getClient().selectBatch( vmainKey, SELECT_ALL, builder.vConds, mpResults );
}

Performance Notes:
- If UKEY is fully provided (e.g., Hash::uid), complexity is O(1).
- If UKEY is not fully provided (e.g., Hash::uid, Hash::imid, but only Hash::uid is in condition), complexity is O(N).
```

--------------------------------

### Atomic Data Update with updateAtomFetch_v2

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

An enhanced version of `updateAtomFetch` for atomic data updates. It includes an additional parameter `bInsert` to explicitly control insertion when a key (uk) does not exist. Like its predecessor, it supports conditional operations and idempotency via UUID.

```C++
int updateAtomFetch_v2( const K &sMainIndex, const map<string, UpdateValue> &mpUpdateValues, const vector<Condition> &vtConds, SelectResult &result, bool getOldValue = false, bool bDirty = true, bool bInsert = true, time_t tExpire = 0 )
```

```C++
DBuilder builder;
builder.clear();
//various operations
builder.set( DCacheUserProfile::nickname = "lisonzhu" );
builder.set( DCacheUserProfile::roomid &= 18 );
builder.set( DCacheUserProfile::presenterlevel ^= 1);
builder.set( DCacheUserProfile::yyid |= 3);
builder.set( ~DCacheUserProfile::ispresenter);
SelectResult fetchResult;
auto iRet = DCacheOpt::getInstance()->getClient().updateAtomFetch( mainKey, builder.updateValues, {}, fetchResult );

//uuid retry idempotency
builder.clear();
builder.set( DCacheUserProfile::nickname = "lisonzhu" )
       .set( DCacheUserProfile::__uuid = "1" );
DCacheOpt::getInstance()->getClient().updateAtomFetch( mainKey, builder.updateValues, {}, fetchResult );
// retry iRet = ET_UUID_DUPLICATED
iRet = DCacheOpt::getInstance()->getClient().updateAtomFetch( mainKey, builder.updateValues, {}, fetchResult );
```

--------------------------------

### Scan Database Data (scanMKFromDB)

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Scans data from a database within a specified range using a servant name and a main key. For subsequent queries, the `next_main_key` returned from a previous call should be used as the `main_key`. Ensure the `servant_name` is correctly configured for DBAccess.

```C++
int scanMKFromDB(const string& servant_name, const string & main_key, int count, vector<map<std::string, std::string>> &allVtData,
bool &isEnd, string & next_main_key)
```

```C++
void testScanMKFromDB()
{
    std::string main_key;
    std::string next_main_key;
    int count = 1000; //每次取1000个，建议不超过5000
    bool isEnd = false;
    string servant_name = "DCache.BenchmarkKKVTestDbAccessServer.DbAccessObj";
    
    while( !isEnd ){
        vector<map<std::string, std::string> > vtData;
        DCacheOpt::getInstance()->getClient().scanMKFromDB( servant_name, main_key, count, vtData, isEnd, next_main_key );
        main_key = next_main_key;
        for( auto &item : vtData ){
            for( auto &item2 : item ){
                cout << item2.first << "|" << item2.second << endl;
            }
        }
    }
}
```

--------------------------------

### Delete Data (Cache and DB)

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Deletes data from both the cache and the database. It takes the main key and a vector of conditions as parameters. Conditions support overloaded operators for comparisons.

```C++
int del( const K &sMainIndex, const vector<DCache::Condition> &vtConds )
```

```C++
// Condition supports overloaded symbols:
auto condition = {Rank::uid>100000,Rank::sex==1,Rank::age>18,Rank::age>=18,Rank::age<=18,Rank::age<18,Rank::age!=18};

auto condition = {Rank::uid>100000,Rank::sex==1,Rank::age!=18};
DCacheOpt::getInstance()->getClient().del("mk",condition);
```

--------------------------------

### Batch Update Fetch

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Performs batch updates on data. It supports specifying conditions for insertion if a key doesn't exist and allows fetching either old or new values. Atomic updates are guaranteed for the same mainKey if all conditions are updateUk. For different mainKeys, it's equivalent to multiple calls to updateAtomFetch, without cross-mainKey atomicity guarantees. Returns 0 for successful requests, with individual return values per mainKey.

```C++
int updateFetchBatch( const vector<UpdateAtomFetchBatchParam> &updateParam, vector<SelectResult>& vtResults );
struct UpdateAtomFetchBatchParam {
    std::string mainKey;
    map<std::string, DCache::UpdateValue> mpValue;
    vector<DCache::Condition> cond;
    taf::Bool getOldValue;
    taf::Bool dirty;
    taf::Int32 expireTimeSecond;
};

// Example Usage:
// MultiRowBuilder builder;
// vector<SelectResult> vtResults;
// builder.createUpdateItem("1005", true, true, 0).set(Hash::zzz+="1").where(Hash::timestamp=="1").where(Hash::qqq=="1");
// builder.createUpdateItem("1002", false).set(Hash::zzz+="1").where(Hash::timestamp=="1").where(Hash::qqq=="2");
// builder.createUpdateItem("1002").set(Hash::zzz+="1").where(Hash::timestamp=="2").where(Hash::qqq=="3");
// int ret = DCacheOpt::getInstance()->getClient().updateFetchBatch(builder,vtResults);
// for(auto &item : vtResults) {
//     cout << item.getMainKey(); // mk
//     cout << item.getReturnValue(); // mk corresponding return value
//     cout << printSelectResult(item.data()); // value
// }
```

--------------------------------

### Scan Hash Table Data (scanMK)

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Scans data from a hash table within a specified range. It iterates through hash buckets, and performance can be affected by the number of buckets and data sparsity. Data might be excluded if it's older than the cache's LRU policy. Recommended for datasets smaller than 100,000 entries.

```C++
int scanMK( int index, int count, vector<map<std::string, std::string>> &allVtData, bool &isEnd )
```

```C++
void testScanMK()
{
    int index = 0;
    int count = 1000; //每次取1000个，建议不超过5000
    bool isEnd = false;
    
    while( !isEnd ){
        vector<map<std::string, std::string> > vtData;
        DCacheOpt::getInstance()->getClient().scanMK( index, count, vtData, isEnd );
        index += count;
        for( auto &item : vtData ){
            for( auto &item2 : item ){
                cout << item2.first << "|" << item2.second << endl;
            }
        }
    }
}
```

--------------------------------

### Batch Delete Data

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Performs batch deletion of data. It accepts a vector of DelCondition objects, each specifying the main key, deletion conditions, and version. The return map indicates the result of each deletion operation.

```C++
int delBatch( const vector<DCache::DelCondition> &vtCond, map<taf::Int32, taf::Int32> &mRet )
```

```C++
// Method 1:
    vector<DCache::DelCondition> vtDelConds;
    auto cond = Rank::uid > 17 && Rank::sex == 1 && Rank::age < 18;
    // Note: Manually writing DelCondition requires converting the type to string
    vtDelConds.emplace_back("1231424", cond, 0 ); // Delete data with main key 1231424 and condition cond with version 0
    map<taf::Int32, taf::Int32> &mRet;
    DCacheOpt::getInstance()->getClient().delBatch(vtDelCond,mRet);
    
    
    // Method 2:
    MultiRowBuilder mbuilder;
    // For different ukeys under the same main key, writing like this is more efficient
    // Can achieve the effect of OR
    // Delete
    for(size_t i = 0; i < 5; ++i) {
        auto &oneRow = mbuilder.createDeleteItem("xx1111");
        oneRow.where(uid==i && nickname=="yyy");
    }
    
    // Chained writing is also possible:
    mbuilder.createDeleteItem("xx1111")
            .where(uid==1111 && nickname=="yyy")
            .createDeleteItem("xx1111")
            .where(uid==666666666666 && nickname=="yyy"); // Same main key, multiple conditions
            
    // Different main keys or different ukeys must be written like this
    mbuilder.createDeleteItem("xxx222").where({uid==2222,nickname=="ggsdfg"})
            .createDeleteItem("xxx333").where({uid==3333,nickname=="x34fg"});
    map<int,int>mret;
    ret = DCacheOpt::getInstance()->getClient().delBatch(mbuilder,mret);
```

--------------------------------

### Set String Value

Source: https://github.com/veekocnn/taf-dcache/blob/main/DCache接口描述文档.md

Inserts or updates a string value for a given main key. Supports setting an expiration time and optionally a version number. Version numbers range from 1-255; 0 indicates no version.

```C++
int setString(const K& mainKey, const string& val)
int setString(const K& mainKey, const string& val, int expireTimeSecond = 0)
int setStringWithVer(const K& mainKey, const string& val, taf::Char ver)
```