Recent changes to RetrieveNoCopy Method

WikiPage RetrieveNoCopy Method modified by Glenn Hofford

Glenn Hofford — Thu, 15 Dec 2011 19:38:05 -0000

--- v2 
+++ v3 
@@ -35,7 +35,7 @@
 
 RetrieveNoCopy() does a cache retrieve operation, which affects replacement metadata, however it does not copy any data; it simply returns a pointer to the cache entry data, in ppbData.
 
-When used in multi-threaded situations, this is unreliable unless the caller first calls SetCacheEntryDoNotEvictFlag () to mark the cache entry so that it will not be evicted.
+When used in multi-threaded situations, this is unreliable unless the caller first calls SetCacheEntryDoNotEvictFlag () to mark the cache entry so that it will not be evicted. Otherwise, the Retrieve() method should be used, since it copies the data to a buffer that is provided by the caller.
 
 

 ###### Example ######

WikiPage RetrieveNoCopy Method modified by Glenn Hofford

Glenn Hofford — Thu, 15 Dec 2011 19:36:17 -0000

--- v1 
+++ v2 
@@ -2,46 +2,59 @@
 
 ###### Summary: ######
 
-RetrieveNoCopy() retrieves the length in bytes of a cache entry's Document field's data.
-
-

+RetrieveNoCopy() gets a pointer to the data of a cache entry.
+
+

 ###### Syntax: ######
 
-    int RetrieveDataLength (const QBYTE *szKey,
-                            size_t *pcbData);
-
-    int RetrieveDataLength (const QWORD *wszKey,
-                            size_t *pcbData);
+    int RetrieveNoCopy (const QBYTE *szKey, 
+                        QBYTE **ppbData);
+
+    int RetrieveNoCopy (const QWORD *wszKey, 
+                        QBYTE **ppbData);
 
 

 ###### Parameters:######
 
     1) szKey or wszKey: the key
 
-    2) pcbData: pointer to a variable that on return will contain the exact number of bytes of the data that is stored in the cache entry.
+    2) ppbData: pointer to a pointer that on return will point to a buffer containing the data. This buffer is maintained by the cache and must not be deleted or free'd.
 
 

 ###### Return values:######
 
       E_KEY_INVALIDKEYTYPE
       E_INVALID_KEYVALUE
       E_KEY_NOTFOUND
       E_CACHE_RETRIEVE_ENTRY_MARKED_FOR_DELETION
       E_CACHE_RETRIEVE_ENTRY_IS_EXPIRED
       E_SUCCESS
 
 

 ###### Remarks:######
 
-RetrieveNoCopy
+RetrieveNoCopy() does a cache retrieve operation, which affects replacement metadata, however it does not copy any data; it simply returns a pointer to the cache entry data, in ppbData.
+
+When used in multi-threaded situations, this is unreliable unless the caller first calls SetCacheEntryDoNotEvictFlag () to mark the cache entry so that it will not be evicted.
 
 

 ###### Example ######
 
+    // First, get the length in bytes of the data:
+
     size_t cbData = 0;
 
     int iResult = pCache->RetrieveDataLength ((const QBYTE *) "AAA", // key
                                               &cbData);
+    if (iResult != E_SUCCESS)
+    {
+        // error handling here
+    }
+
+    QBYTE *pbData = NULL;
+
+    iResult = pCache->RetrieveNoCopy ((const QBYTE *) "AAA", // key
+                                      &pbData);
     if (iResult != E_SUCCESS)
     {
         // error handling here

WikiPage RetrieveNoCopy Method modified by Glenn Hofford

Glenn Hofford — Thu, 15 Dec 2011 19:29:06 -0000

##### Method: Cache::RetrieveNoCopy ##### ###### Summary: ###### RetrieveNoCopy() retrieves the length in bytes of a cache entry's Document field's data.
###### Syntax: ###### int RetrieveDataLength (const QBYTE *szKey, size_t *pcbData); int RetrieveDataLength (const QWORD *wszKey, size_t *pcbData);
###### Parameters:###### 1) szKey or wszKey: the key 2) pcbData: pointer to a variable that on return will contain the exact number of bytes of the data that is stored in the cache entry.
###### Return values:###### E_KEY_INVALIDKEYTYPE E_INVALID_KEYVALUE E_KEY_NOTFOUND E_CACHE_RETRIEVE_ENTRY_MARKED_FOR_DELETION E_CACHE_RETRIEVE_ENTRY_IS_EXPIRED E_SUCCESS
###### Remarks:###### RetrieveNoCopy
###### Example ###### size_t cbData = 0; int iResult = pCache->RetrieveDataLength ((const QBYTE *) "AAA", // key &cbData); if (iResult != E_SUCCESS) { // error handling here }