refactor cache module based on new hash table and reference count management module

src/client/src/tscLocal.c

@@ -484,7 +484,7 @@ int tscProcessLocalCmd(SSqlObj *pSql) {
     pSql->res.qhandle = 0x1;
     pSql->res.numOfRows = 0;
   } else if (pCmd->command == TSDB_SQL_RESET_CACHE) {
-    taosClearDataCache(tscCacheHandle);
+    taosCacheEmpty(tscCacheHandle);
   } else if (pCmd->command == TSDB_SQL_SERV_VERSION) {
     tscProcessServerVer(pSql);
   } else if (pCmd->command == TSDB_SQL_CLI_VERSION) {

src/client/src/tscServer.c

@@ -182,7 +182,6 @@ int tscSendMsgToServer(SSqlObj *pSql) {
   }
 
   pSql->ipList->ip[0] = inet_addr("192.168.0.1");
-  SSqlCmd* pCmd = &pSql->cmd;
   
   if (pSql->cmd.command < TSDB_SQL_MGMT) {
     pSql->ipList->port = tsDnodeShellPort;
@@ -2641,7 +2640,7 @@ int tscProcessMeterMetaRsp(SSqlObj *pSql) {
   SMeterMetaInfo *pMeterMetaInfo = tscGetMeterMetaInfo(&pSql->cmd, 0, 0);
   assert(pMeterMetaInfo->pMeterMeta == NULL);
 
-  pMeterMetaInfo->pMeterMeta = (STableMeta *)taosAddDataIntoCache(tscCacheHandle, pMeterMetaInfo->name, (char *)pMeta,
+  pMeterMetaInfo->pMeterMeta = (STableMeta *)taosCachePut(tscCacheHandle, pMeterMetaInfo->name, (char *)pMeta,
                                                                   pMeta->contLen, tsMeterMetaKeepTimer);
   // todo handle out of memory case
   if (pMeterMetaInfo->pMeterMeta == NULL) return 0;
@@ -2750,7 +2749,7 @@ int tscProcessMultiMeterMetaRsp(SSqlObj *pSql) {
     int32_t size = (int32_t)(rsp - ((char *)pMeta));  // Consistent with STableMeta in cache
 
     pMeta->index = 0;
-    (void)taosAddDataIntoCache(tscCacheHandle, pMeta->tableId, (char *)pMeta, size, tsMeterMetaKeepTimer);
+    (void)taosCachePut(tscCacheHandle, pMeta->tableId, (char *)pMeta, size, tsMeterMetaKeepTimer);
   }
 
   pSql->res.code = TSDB_CODE_SUCCESS;
@@ -2857,9 +2856,9 @@ int tscProcessMetricMetaRsp(SSqlObj *pSql) {
 #endif
 
     // release the used metricmeta
-    taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), false);
+    taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), false);
 
-    pMeterMetaInfo->pMetricMeta = (SSuperTableMeta *)taosAddDataIntoCache(tscCacheHandle, name, (char *)metricMetaList[i],
+    pMeterMetaInfo->pMetricMeta = (SSuperTableMeta *)taosCachePut(tscCacheHandle, name, (char *)metricMetaList[i],
                                                                       sizes[i], tsMetricMetaKeepTimer);
     tfree(metricMetaList[i]);
 
@@ -2917,11 +2916,11 @@ int tscProcessShowRsp(SSqlObj *pSql) {
   key[0] = pCmd->msgType + 'a';
   strcpy(key + 1, "showlist");
 
-  taosRemoveDataFromCache(tscCacheHandle, (void *)&(pMeterMetaInfo->pMeterMeta), false);
+  taosCacheRelease(tscCacheHandle, (void *)&(pMeterMetaInfo->pMeterMeta), false);
 
   int32_t size = pMeta->numOfColumns * sizeof(SSchema) + sizeof(STableMeta);
   pMeterMetaInfo->pMeterMeta =
-      (STableMeta *)taosAddDataIntoCache(tscCacheHandle, key, (char *)pMeta, size, tsMeterMetaKeepTimer);
+      (STableMeta *)taosCachePut(tscCacheHandle, key, (char *)pMeta, size, tsMeterMetaKeepTimer);
   pCmd->numOfCols = pQueryInfo->fieldsInfo.numOfOutputCols;
   SSchema *pMeterSchema = tsGetSchema(pMeterMetaInfo->pMeterMeta);
 
@@ -2975,14 +2974,14 @@ int tscProcessUseDbRsp(SSqlObj *pSql) {
 }
 
 int tscProcessDropDbRsp(SSqlObj *UNUSED_PARAM(pSql)) {
-  taosClearDataCache(tscCacheHandle);
+  taosCacheEmpty(tscCacheHandle);
   return 0;
 }
 
 int tscProcessDropTableRsp(SSqlObj *pSql) {
   SMeterMetaInfo *pMeterMetaInfo = tscGetMeterMetaInfo(&pSql->cmd, 0, 0);
 
-  STableMeta *pMeterMeta = taosGetDataFromCache(tscCacheHandle, pMeterMetaInfo->name);
+  STableMeta *pMeterMeta = taosCacheAcquireByName(tscCacheHandle, pMeterMetaInfo->name);
   if (pMeterMeta == NULL) {
     /* not in cache, abort */
     return 0;
@@ -2996,11 +2995,11 @@ int tscProcessDropTableRsp(SSqlObj *pSql) {
    * instead.
    */
   tscTrace("%p force release metermeta after drop table:%s", pSql, pMeterMetaInfo->name);
-  taosRemoveDataFromCache(tscCacheHandle, (void **)&pMeterMeta, true);
+  taosCacheRelease(tscCacheHandle, (void **)&pMeterMeta, true);
 
   if (pMeterMetaInfo->pMeterMeta) {
-    taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMeterMeta), true);
-    taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), true);
+    taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMeterMeta), true);
+    taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), true);
   }
 
   return 0;
@@ -3009,23 +3008,23 @@ int tscProcessDropTableRsp(SSqlObj *pSql) {
 int tscProcessAlterTableMsgRsp(SSqlObj *pSql) {
   SMeterMetaInfo *pMeterMetaInfo = tscGetMeterMetaInfo(&pSql->cmd, 0, 0);
 
-  STableMeta *pMeterMeta = taosGetDataFromCache(tscCacheHandle, pMeterMetaInfo->name);
+  STableMeta *pMeterMeta = taosCacheAcquireByName(tscCacheHandle, pMeterMetaInfo->name);
   if (pMeterMeta == NULL) { /* not in cache, abort */
     return 0;
   }
 
   tscTrace("%p force release metermeta in cache after alter-table: %s", pSql, pMeterMetaInfo->name);
-  taosRemoveDataFromCache(tscCacheHandle, (void **)&pMeterMeta, true);
+  taosCacheRelease(tscCacheHandle, (void **)&pMeterMeta, true);
 
   if (pMeterMetaInfo->pMeterMeta) {
     bool isSuperTable = UTIL_METER_IS_SUPERTABLE(pMeterMetaInfo);
 
-    taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMeterMeta), true);
-    taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), true);
+    taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMeterMeta), true);
+    taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), true);
 
     if (isSuperTable) {  // if it is a super table, reset whole query cache
       tscTrace("%p reset query cache since table:%s is stable", pSql, pMeterMetaInfo->name);
-      taosClearDataCache(tscCacheHandle);
+      taosCacheEmpty(tscCacheHandle);
     }
   }
 
@@ -3151,7 +3150,7 @@ static int32_t doGetMeterMetaFromServer(SSqlObj *pSql, SMeterMetaInfo *pMeterMet
      * Transfer the ownership of metermeta to the new object, instead of invoking the release/acquire routine
      */
     if (code == TSDB_CODE_SUCCESS) {
-      pMeterMetaInfo->pMeterMeta = taosTransferDataInCache(tscCacheHandle, (void**) &pNewMeterMetaInfo->pMeterMeta);
+      pMeterMetaInfo->pMeterMeta = taosCacheTransfer(tscCacheHandle, (void**) &pNewMeterMetaInfo->pMeterMeta);
       assert(pMeterMetaInfo->pMeterMeta != NULL);
     }
 
@@ -3177,10 +3176,10 @@ int tscGetMeterMeta(SSqlObj *pSql, SMeterMetaInfo *pMeterMetaInfo) {
 
   // If this SMeterMetaInfo owns a metermeta, release it first
   if (pMeterMetaInfo->pMeterMeta != NULL) {
-    taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMeterMeta), false);
+    taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMeterMeta), false);
   }
   
-  pMeterMetaInfo->pMeterMeta = (STableMeta *)taosGetDataFromCache(tscCacheHandle, pMeterMetaInfo->name);
+  pMeterMetaInfo->pMeterMeta = (STableMeta *)taosCacheAcquireByName(tscCacheHandle, pMeterMetaInfo->name);
   if (pMeterMetaInfo->pMeterMeta != NULL) {
     STableMeta *pMeterMeta = pMeterMetaInfo->pMeterMeta;
 
@@ -3244,7 +3243,7 @@ int tscRenewMeterMeta(SSqlObj *pSql, char *tableId) {
     }
 
     tscWaitingForCreateTable(pCmd);
-    taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMeterMeta), true);
+    taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMeterMeta), true);
 
     code = doGetMeterMetaFromServer(pSql, pMeterMetaInfo);  // todo ??
   } else {
@@ -3278,9 +3277,9 @@ int tscGetMetricMeta(SSqlObj *pSql, int32_t clauseIndex) {
     SMeterMetaInfo *pMeterMetaInfo = tscGetMeterMetaInfoFromQueryInfo(pQueryInfo, i);
     tscGetMetricMetaCacheKey(pQueryInfo, tagstr, pMeterMetaInfo->pMeterMeta->uid);
 
-    taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), false);
+    taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), false);
 
-    SSuperTableMeta *ppMeta = (SSuperTableMeta *)taosGetDataFromCache(tscCacheHandle, tagstr);
+    SSuperTableMeta *ppMeta = (SSuperTableMeta *)taosCacheAcquireByName(tscCacheHandle, tagstr);
     if (ppMeta == NULL) {
       required = true;
       break;
@@ -3308,7 +3307,7 @@ int tscGetMetricMeta(SSqlObj *pSql, int32_t clauseIndex) {
   for (int32_t i = 0; i < pQueryInfo->numOfTables; ++i) {
     SMeterMetaInfo *pMMInfo = tscGetMeterMetaInfoFromQueryInfo(pQueryInfo, i);
 
-    STableMeta *pMeterMeta = taosGetDataFromCache(tscCacheHandle, pMMInfo->name);
+    STableMeta *pMeterMeta = taosCacheAcquireByName(tscCacheHandle, pMMInfo->name);
     tscAddMeterMetaInfo(pNewQueryInfo, pMMInfo->name, pMeterMeta, NULL, pMMInfo->numOfTags, pMMInfo->tagColumnIndex);
   }
 
@@ -3353,8 +3352,8 @@ int tscGetMetricMeta(SSqlObj *pSql, int32_t clauseIndex) {
         printf("create metric key:%s, index:%d\n", tagstr, i);
 #endif
     
-        taosRemoveDataFromCache(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), false);
-        pMeterMetaInfo->pMetricMeta = (SSuperTableMeta *)taosGetDataFromCache(tscCacheHandle, tagstr);
+        taosCacheRelease(tscCacheHandle, (void **)&(pMeterMetaInfo->pMetricMeta), false);
+        pMeterMetaInfo->pMetricMeta = (SSuperTableMeta *) taosCacheAcquireByName(tscCacheHandle, tagstr);
       }
     }
 

src/client/src/tscSub.c

@@ -371,7 +371,7 @@ TAOS_RES *taos_consume(TAOS_SUB *tsub) {
       pSql->sqlstr = NULL;
       taos_free_result_imp(pSql, 0);
       pSql->sqlstr = sqlstr;
-      taosClearDataCache(tscCacheHandle);
+      taosCacheEmpty(tscCacheHandle);
       if (!tscUpdateSubscription(pSub->taos, pSub)) return NULL;
       tscTrace("meter synchronization completed");
     } else {

src/client/src/tscSystem.c

@@ -186,7 +186,7 @@ void taos_init_imp() {
   refreshTime = refreshTime > 2 ? 2 : refreshTime;
   refreshTime = refreshTime < 1 ? 1 : refreshTime;
 
-  if (tscCacheHandle == NULL) tscCacheHandle = taosInitDataCache(tsMaxMeterConnections / 2, tscTmr, refreshTime);
+  if (tscCacheHandle == NULL) tscCacheHandle = taosCacheInit(tscTmr, refreshTime);
 
   tscConnCache = taosOpenConnCache(tsMaxMeterConnections * 2, NULL/*taosCloseRpcConn*/, tscTmr, tsShellActivityTimer * 1000);
 

src/client/src/tscUtil.c

@@ -505,7 +505,7 @@ void tscDestroyDataBlock(STableDataBlocks* pDataBlock) {
   tfree(pDataBlock->params);
 
   // free the refcount for metermeta
-  taosRemoveDataFromCache(tscCacheHandle, (void**)&(pDataBlock->pMeterMeta), false);
+  taosCacheRelease(tscCacheHandle, (void**)&(pDataBlock->pMeterMeta), false);
   tfree(pDataBlock);
 }
 
@@ -589,9 +589,9 @@ int32_t tscCopyDataBlockToPayload(SSqlObj* pSql, STableDataBlocks* pDataBlock) {
   // set the correct metermeta object, the metermeta has been locked in pDataBlocks, so it must be in the cache
   if (pMeterMetaInfo->pMeterMeta != pDataBlock->pMeterMeta) {
     strcpy(pMeterMetaInfo->name, pDataBlock->tableId);
-    taosRemoveDataFromCache(tscCacheHandle, (void**)&(pMeterMetaInfo->pMeterMeta), false);
+    taosCacheRelease(tscCacheHandle, (void**)&(pMeterMetaInfo->pMeterMeta), false);
 
-    pMeterMetaInfo->pMeterMeta = taosTransferDataInCache(tscCacheHandle, (void**)&pDataBlock->pMeterMeta);
+    pMeterMetaInfo->pMeterMeta = taosCacheTransfer(tscCacheHandle, (void**)&pDataBlock->pMeterMeta);
   } else {
     assert(strncmp(pMeterMetaInfo->name, pDataBlock->tableId, tListLen(pDataBlock->tableId)) == 0);
   }
@@ -665,7 +665,7 @@ int32_t tscCreateDataBlock(size_t initialSize, int32_t rowSize, int32_t startOff
    * due to operation such as drop database. So here we add the reference count directly instead of invoke
    * taosGetDataFromCache, which may return NULL value.
    */
-  dataBuf->pMeterMeta = taosGetDataFromExists(tscCacheHandle, pMeterMeta);
+  dataBuf->pMeterMeta = taosCacheAcquireByData(tscCacheHandle, pMeterMeta);
   assert(initialSize > 0 && pMeterMeta != NULL && dataBuf->pMeterMeta != NULL);
 
   *dataBlocks = dataBuf;
@@ -1940,8 +1940,8 @@ void tscClearMeterMetaInfo(SMeterMetaInfo* pMeterMetaInfo, bool removeFromCache)
     return;
   }
 
-  taosRemoveDataFromCache(tscCacheHandle, (void**)&(pMeterMetaInfo->pMeterMeta), removeFromCache);
-  taosRemoveDataFromCache(tscCacheHandle, (void**)&(pMeterMetaInfo->pMetricMeta), removeFromCache);
+  taosCacheRelease(tscCacheHandle, (void**)&(pMeterMetaInfo->pMeterMeta), removeFromCache);
+  taosCacheRelease(tscCacheHandle, (void**)&(pMeterMetaInfo->pMetricMeta), removeFromCache);
 }
 
 void tscResetForNextRetrieve(SSqlRes* pRes) {
@@ -2071,16 +2071,16 @@ SSqlObj* createSubqueryObj(SSqlObj* pSql, int16_t tableIndex, void (*fp)(), void
   SMeterMetaInfo* pFinalInfo = NULL;
 
   if (pPrevSql == NULL) {
-    STableMeta*  pMeterMeta = taosGetDataFromCache(tscCacheHandle, name);
-    SSuperTableMeta* pMetricMeta = taosGetDataFromCache(tscCacheHandle, key);
+    STableMeta*  pMeterMeta = taosCacheAcquireByName(tscCacheHandle, name);
+    SSuperTableMeta* pMetricMeta = taosCacheAcquireByName(tscCacheHandle, key);
 
     pFinalInfo = tscAddMeterMetaInfo(pNewQueryInfo, name, pMeterMeta, pMetricMeta, pMeterMetaInfo->numOfTags,
                                      pMeterMetaInfo->tagColumnIndex);
   } else {  // transfer the ownership of pMeterMeta/pMetricMeta to the newly create sql object.
     SMeterMetaInfo* pPrevInfo = tscGetMeterMetaInfo(&pPrevSql->cmd, pPrevSql->cmd.clauseIndex, 0);
 
-    STableMeta*  pPrevMeterMeta = taosTransferDataInCache(tscCacheHandle, (void**)&pPrevInfo->pMeterMeta);
-    SSuperTableMeta* pPrevMetricMeta = taosTransferDataInCache(tscCacheHandle, (void**)&pPrevInfo->pMetricMeta);
+    STableMeta*  pPrevMeterMeta = taosCacheTransfer(tscCacheHandle, (void**)&pPrevInfo->pMeterMeta);
+    SSuperTableMeta* pPrevMetricMeta = taosCacheTransfer(tscCacheHandle, (void**)&pPrevInfo->pMetricMeta);
 
     pFinalInfo = tscAddMeterMetaInfo(pNewQueryInfo, name, pPrevMeterMeta, pPrevMetricMeta, pMeterMetaInfo->numOfTags,
                                      pMeterMetaInfo->tagColumnIndex);

src/query/inc/tcache.h

@@ -20,7 +20,63 @@
 extern "C" {
 #endif
 
-#include <stdbool.h>
+#include "os.h"
+#include "tref.h"
+#include "hash.h"
+
+typedef struct SCacheStatis {
+  int64_t missCount;
+  int64_t hitCount;
+  int64_t totalAccess;
+  int64_t refreshCount;
+  int32_t numOfCollision;
+} SCacheStatis;
+
+typedef struct SCacheDataNode {
+  uint64_t addedTime;    // the added time when this element is added or updated into cache
+  uint64_t expiredTime;  // expiredTime expiredTime when this element should be remove from cache
+  uint64_t signature;
+  uint32_t size;         // allocated size for current SCacheDataNode
+  uint16_t keySize : 15;
+  bool     inTrash : 1;  // denote if it is in trash or not
+  T_REF_DECLARE()
+  char *key;
+  char  data[];
+} SCacheDataNode;
+
+typedef struct STrashElem {
+  struct STrashElem *prev;
+  struct STrashElem *next;
+  SCacheDataNode *        pData;
+} STrashElem;
+
+typedef struct {
+  int64_t totalSize;  // total allocated buffer in this hash table, SCacheObj is not included.
+  int64_t refreshTime;
+  
+  /*
+   * to accommodate the old datanode which has the same key value of new one in hashList
+   * when an new node is put into cache, if an existed one with the same key:
+   * 1. if the old one does not be referenced, update it.
+   * 2. otherwise, move the old one to pTrash, addedTime the new one.
+   *
+   * when the node in pTrash does not be referenced, it will be release at the expired expiredTime
+   */
+  STrashElem * pTrash;
+  void *       tmrCtrl;
+  void *       pTimer;
+  SCacheStatis statistics;
+  SHashObj *   pHashTable;
+  int          numOfElemsInTrash;  // number of element in trash
+  int16_t      deleting;           // set the deleting flag to stop refreshing ASAP.
+
+#if defined(LINUX)
+  pthread_rwlock_t lock;
+#else
+  pthread_mutex_t lock;
+#endif
+
+} SCacheObj;
 
 /**
  *
@@ -30,7 +86,7 @@ extern "C" {
  *                          not referenced by other objects
  * @return
  */
-void *taosInitDataCache(int maxSessions, void *tmrCtrl, int64_t refreshTimeInSeconds);
+SCacheObj *taosCacheInit(void *tmrCtrl, int64_t refreshTimeInSeconds);
 
 /**
  * add data into cache
@@ -42,28 +98,7 @@ void *taosInitDataCache(int maxSessions, void *tmrCtrl, int64_t refreshTimeInSec
  * @param keepTime      survival time in second
  * @return              cached element
  */
-void *taosAddDataIntoCache(void *handle, char *key, char *pData, int dataSize, int keepTimeInSeconds);
-
-/**
- * remove data in cache, the data will not be removed immediately.
- * if it is referenced by other object, it will be remain in cache
- * @param handle    cache object
- * @param data      not the key, actually referenced data
- * @param _remove   force model, reduce the ref count and move the data into
- * pTrash
- */
-void taosRemoveDataFromCache(void *handle, void **data, bool _remove);
-
-/**
- * update data in cache
- * @param handle hash object handle(pointer)
- * @param key    key for hash
- * @param pData  actually data
- * @param size   length of data
- * @param duration  survival time of this object in cache
- * @return       new referenced data
- */
-void *taosUpdateDataFromCache(void *handle, char *key, char *pData, int size, int duration);
+void *taosCachePut(void *handle, char *key, char *pData, int dataSize, int keepTimeInSeconds);
 
 /**
  * get data from cache
@@ -71,40 +106,56 @@ void *taosUpdateDataFromCache(void *handle, char *key, char *pData, int size, in
  * @param key           key
  * @return              cached data or NULL
  */
-void *taosGetDataFromCache(void *handle, char *key);
+void *taosCacheAcquireByName(void *handle, char *key);
 
 /**
- * release all allocated memory and destroy the cache object
+ * Add one reference count for the exist data, and assign this data for a new owner.
+ * The new owner needs to invoke the taosCacheRelease when it does not need this data anymore.
+ * This procedure is a faster version of taosCacheAcquireByName function, which avoids the sideeffect of the problem of
+ * the data is moved to trash, and taosCacheAcquireByName will fail to retrieve it again.
  *
  * @param handle
+ * @param data
+ * @return
  */
-void taosCleanUpDataCache(void *handle);
+void *taosCacheAcquireByData(void *handle, void *data);
 
 /**
- *  move all data node into trash,clear node in trash can if it is not referenced by client
+ * transfer the ownership of data in cache to another object without increasing reference count.
  * @param handle
+ * @param data
+ * @return
  */
-void taosClearDataCache(void *handle);
+void *taosCacheTransfer(void *handle, void **data);
 
 /**
- * Add one reference count for the exist data, and assign this data for a new owner.
- * The new owner needs to invoke the taosRemoveDataFromCache when it does not need this data anymore.
- * This procedure is a faster version of taosGetDataFromCache function, which avoids the sideeffect of the problem of the
- * data is moved to trash, and taosGetDataFromCache will fail to retrieve it again.
- *
+ * remove data in cache, the data will not be removed immediately.
+ * if it is referenced by other object, it will be remain in cache
+ * @param handle    cache object
+ * @param data      not the key, actually referenced data
+ * @param _remove   force model, reduce the ref count and move the data into
+ * pTrash
+ */
+void taosCacheRelease(void *handle, void **data, bool _remove);
+
+/**
+ *  move all data node into trash, clear node in trash can if it is not referenced by any clients
  * @param handle
- * @param data
- * @return
  */
-void* taosGetDataFromExists(void* handle, void* data);
+void taosCacheEmpty(SCacheObj *pCacheObj);
 
 /**
- * transfer the ownership of data in cache to another object without increasing reference count.
+ * release all allocated memory and destroy the cache object.
+ *
+ * This function only set the deleting flag, and the specific work of clean up cache is delegated to
+ * taosCacheRefresh function, which will executed every SCacheObj->refreshTime sec.
+ *
+ * If the value of SCacheObj->refreshTime is too large, the taosCacheRefresh function may not be invoked
+ * before the main thread terminated, in which case all allocated resources are simply recycled by OS.
+ *
  * @param handle
- * @param data
- * @return
  */
-void* taosTransferDataInCache(void* handle, void** data);
+void taosCacheCleanup(SCacheObj *pCacheObj);
 
 #ifdef __cplusplus
 }