X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fmemcached_get.pod;h=df0ac7799ee985f3e85e37edbc89e2c3c9cfde9d;hb=b369db6ab57bc940618281a2be848542a406bb7c;hp=6de4b5eb4af15ed0402da032d13a2b218401b496;hpb=27ed7884526a4cf01d57437648c20e59caffefa2;p=m6w6%2Flibmemcached

diff --git a/docs/memcached_get.pod b/docs/memcached_get.pod
index 6de4b5eb..df0ac779 100755
--- a/docs/memcached_get.pod
+++ b/docs/memcached_get.pod
@@ -16,31 +16,50 @@ C Client Library for memcached (libmemcached, -lmemcached)
 		       memcached_return *error);
 
   char *memcached_get (memcached_st *ptr,
-                       char *key, size_t key_length,
+                       const char *key, size_t key_length,
                        size_t *value_length, 
-                       uint16_t *flags,
+                       uint32_t *flags,
                        memcached_return *error);
 
   memcached_return
   memcached_mget (memcached_st *ptr, 
                   char **keys, size_t *key_length, 
                   unsigned int number_of_keys);
+  char *
+  memcached_get_by_key(memcached_st *ptr, 
+                       const char *master_key, size_t master_key_length, 
+                       const char *key, size_t key_length, 
+                       size_t *value_length, 
+                       uint32_t *flags,
+                       memcached_return *error);
+
+  memcached_return 
+  memcached_mget_by_key(memcached_st *ptr, 
+                        const char *master_key, size_t master_key_length,
+                        char **keys, size_t *key_length, 
+                        unsigned int number_of_keys);
 
   char *memcached_fetch (memcached_st *ptr,
-                         char *key, size_t *key_length, 
+                         const char *key, size_t *key_length, 
                          size_t *value_length,
-                         uint16_t *flags, 
+                         uint32_t *flags, 
                          memcached_return *error);
+  memcached_return 
+  memcached_fetch_execute(memcached_st *ptr, 
+                          memcached_return (*callback[])(memcached_st *ptr, memcached_result_st *result, void *context),
+                          void *context,
+                          unsigned int number_of_callbacks);
 
 =head1 DESCRIPTION
 
 memcached_get() is used to fetch an individual value from the server. You
 must pass in a key and its length to fetch the object. You must supply
 three pointer variables which will give you the state of the returned
-object.  A uint16_t pointer to contain whatever flags you stored with the value,
+object.  A uint32_t pointer to contain whatever flags you stored with the value,
 a size_t pointer which will be filled with size of of the object, and a
 memcached_return pointer to hold any error. The object will be returned
-upon success and NULL will be returned on failure. 
+upon success and NULL will be returned on failure. Any object returned by
+memcached_get() must be released by the caller application. 
 
 memcached_mget() is used to select multiple keys at once. For multiple key
 operations it is always faster to use this function. This function always
@@ -56,10 +75,13 @@ memcached_fetch() is used to fetch an individual value from the server.
 memcached_mget() must always be called before using this method.  You
 must pass in a key and its length to fetch the object. You must supply
 three pointer variables which will give you the state of the returned
-object.  A uint16_t pointer to contain whatever flags you stored with the value,
+object.  A uint32_t pointer to contain whatever flags you stored with the value,
 a size_t pointer which will be filled with size of of the object, and a
 memcached_return pointer to hold any error. The object will be returned
-upon success and NULL will be returned on failure. 
+upon success and NULL will be returned on failure. MEMCACHD_END is returned
+by the *error value when all objects that have been found are returned. 
+The final value upon MEMCACHED_END is null. Values returned by
+memcached_fetch() musted be free'ed by the caller.
 
 memcached_fetch_result() is used to return a memcached_result_st(3) structure 
 from a memcached server. The result object is forward compatible with changes
@@ -67,6 +89,21 @@ to the server. For more information please refer to the memcached_result_st(3)
 help. This function will dynamically allocate a result structure for you
 if you do not pass one to the function.
 
+memcached_fetch_execute() is a callback function for result sets. Instead
+of returning the results to you for processing, it passes each of the
+result sets to the list of functions you provide. It passes to the function
+a memcached_st that can be cloned for use in the called function (it can not 
+be used directly). It also passes a result set which does not need to be freed.
+Finally it passes a "context". This is just a pointer to a memory reference
+you supply the calling function. Currently only one value is being passed
+to each function call. In the future there will be an option to allow this
+to be an array.
+
+memcached_get_by_key() and memcached_mget_by_key() behave in a similar nature
+as memcached_get() and memcached_mget(). The difference is that they take
+a master key that is used for determining which server an object was stored
+if key partitioning was used for storage.
+
 =head1 RETURN
 
 All objects returned must be freed by the calling application.