Recent changes to InsertCallerBuffer Method

WikiPage InsertCallerBuffer Method modified by Glenn Hofford

Glenn Hofford — Thu, 15 Dec 2011 01:15:40 -0000

--- v3 
+++ v4 
@@ -2,7 +2,7 @@
 
 ###### Summary: ######
 
-InsertCallerBuffer() copies cbData bytes from the buffer pointed to by pbData into a cache entry within the cache.
+InsertCallerBuffer() copies cbData bytes from the buffer pointed to by pbData into a cache entry within the cache. The cache does not allocate new memory for the data - it uses the buffer that the caller has allocated.
 
 

 ###### Syntax: ######

WikiPage InsertCallerBuffer Method modified by Glenn Hofford

Glenn Hofford — Thu, 15 Dec 2011 01:14:43 -0000

--- v2 
+++ v3 
@@ -52,17 +52,16 @@
 

 ###### Example ######
 
-    char szVal  [26 + 1];
-
-    strcpy (szVal, "ABCDEFGHIJKLMNOPQRSTUVWXYZ");
-
-    // (note: in this case, the trailing NULL is inserted)
-
-    int iResult = pCache->Insert ((const QBYTE *)"Alphabet", // key
-                                  (QBYTE *) szVal,           // pbData (the value)
-                                  strlen(szVal)+1,           // cbData
-                                  0);                        // TTL
-
+    // the caller buffer:
+
+    QBYTE *pbBuffer = (QBYTE *) malloc (26 + 1);
+
+    strcpy ((char *) pbBuffer, "ABCDEFGHIJKLMNOPQRSTUVWXYZ");
+
+    int iResult = pCache->InsertCallerBuffer ((const QBYTE *) "Alphabet", // key
+                                              pbBuffer, 
+                                              strlen ((char *) pbBuffer) + 1, // cbData
+                                              300);  // TTL
     if (iResult != E_SUCCESS)
     {
         // error handling here

WikiPage InsertCallerBuffer Method modified by Glenn Hofford

Glenn Hofford — Thu, 15 Dec 2011 01:09:42 -0000

--- v1 
+++ v2 
@@ -43,7 +43,11 @@
 

 ###### Remarks:######
 
-The InsertCallerBuffer() method inserts a key and an associated value into the cache. If the cache is full, a replacement is performed; the type of replacement is dependent on the cache replacement policy.
+InsertCallerBuffer() is similar to the Insert() method. It differs as follows: InsertCallerBuffer() uses the caller-allocated buffer pointed to by pbData. The caller allocates a buffer of data, and passes a pointer in pbData. The cache will free the memory pointed to by pbData, during one of the following:
+
+   1) another Insert operation with duplicate key (where allowed), or Replace operation
+   2) a cache-directed replacement, during which a cache entry eviction takes place
+   3) during cleanup of the cache
 
 

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

WikiPage InsertCallerBuffer Method modified by Glenn Hofford

Glenn Hofford — Thu, 15 Dec 2011 00:53:36 -0000

##### Method: Cache::InsertCallerBuffer ##### ###### Summary: ###### InsertCallerBuffer() copies cbData bytes from the buffer pointed to by pbData into a cache entry within the cache.
###### Syntax: ###### int InsertCallerBuffer (const QBYTE *szKey, const QBYTE *pbData, const size_t cbData, const unsigned int numSecondsTTL); int InsertCallerBuffer (const QWORD *wszKey, const QBYTE *pbData, const size_t cbData, const unsigned int numSecondsTTL);
###### Parameters:###### 1) szKey or wszKey: the key 2) pbData: a pointer to a buffer of bytes that will be inserted into the cache. This buffer will have been allocated by the caller; the cache will free the memory pointed to by the buffer pointer. 3) cbData: a count of bytes of the data. This value does not necessarily need to include space for a trailing NULL. Exactly cbData bytes of the buffer pointed to by pbData will be stored in the cache. 4) numSecondsTTL: number of seconds for the "time-to-live" value.
###### Return values:###### E_KEY_INVALIDKEYTYPE E_INVALID_KEYVALUE E_CACHE_DUPLICATE_KEY_FOUND_ENTRY_NOT_REPLACED E_SUCCESS
###### Remarks:###### The InsertCallerBuffer() method inserts a key and an associated value into the cache. If the cache is full, a replacement is performed; the type of replacement is dependent on the cache replacement policy.
###### Example ###### char szVal [26 + 1]; strcpy (szVal, "ABCDEFGHIJKLMNOPQRSTUVWXYZ"); // (note: in this case, the trailing NULL is inserted) int iResult = pCache->Insert ((const QBYTE *)"Alphabet", // key (QBYTE *) szVal, // pbData (the value) strlen(szVal)+1, // cbData 0); // TTL if (iResult != E_SUCCESS) { // error handling here }