memcached 1.2.6 → 1.2.7

data/ext/libmemcached-0.32/docs/memcached_callback.pod

@@ -0,0 +1,123 @@
+=head1 NAME
+
+memcached_callback_get, memcached_callback_set - Get and set a callback
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_return 
+    memcached_callback_set (memcached_st *ptr, 
+                            memcached_callback flag, 
+                            void *data);
+
+  void *
+    memcached_callback_get (memcached_st *ptr, 
+                            memcached_callback flag,
+                            memcached_return *error);
+
+=head1 DESCRIPTION
+
+libmemcached(3) can have callbacks set key execution points. These either
+provide function calls at points in the code, or return pointers to
+structures for particular usages.
+
+memcached_callback_get() takes a callback flag and returns the structure or
+function set by memcached_callback_set().
+
+memcached_callback_set() changes the function/structure assigned by a
+callback flag. No connections are reset. 
+
+You can use MEMCACHED_CALLBACK_USER_DATA to provide custom context if required for any 
+of the callbacks
+
+=over 4
+
+=item MEMCACHED_CALLBACK_CLEANUP_FUNCTION
+
+When memcached_delete() is called this function will be excuted. At the
+point of its execution all connections have been closed.
+
+=item MEMCACHED_CALLBACK_CLONE_FUNCTION
+
+When memcached_delete() is called this function will be excuted. At the
+point of its execution all connections have been closed.
+
+=item MEMCACHED_CALLBACK_PREFIX_KEY
+
+You can set a value which will be used to create a domain for your keys.
+The value specified here will be prefixed to each of your keys. The value can not
+be greater then MEMCACHED_PREFIX_KEY_MAX_SIZE - 1 and will reduce MEMCACHED_MAX_KEY by
+the value of your key. The prefix key is only applied to the primary key,
+not the master key. MEMCACHED_FAILURE will be returned if no key is set. In the case
+of a key which is too long MEMCACHED_BAD_KEY_PROVIDED will be returned.
+
+=item MEMCACHED_CALLBACK_USER_DATA
+
+This allows you to store a pointer to a specifc piece of data. This can be
+retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st
+will copy the pointer to the clone.
+
+=item  MEMCACHED_CALLBACK_MALLOC_FUNCTION
+
+DEPRECATED: use memcached_set_memory_allocators instead.
+
+=item  MEMCACHED_CALLBACK_REALLOC_FUNCTION
+
+DEPRECATED: use memcached_set_memory_allocators instead.
+
+=item  MEMCACHED_CALLBACK_FREE_FUNCTION
+
+DEPRECATED: use memcached_set_memory_allocators instead.
+
+=item  MEMCACHED_CALLBACK_GET_FAILURE
+
+This function implements the read through cache behavior. On failure of retrieval this callback will be called. 
+You are responsible for populating the result object provided. This result object will then be stored in the server and
+returned to the calling process. You must clone the memcached_st in order to
+make use of it. The value will be stored only if you return
+MEMCACHED_SUCCESS or MEMCACHED_BUFFERED. Returning MEMCACHED_BUFFERED will
+cause the object to be buffered and not sent immediatly (if this is the default behavior based on your connection setup this will happen automatically).
+
+The prototype for this is:
+memcached_return (*memcached_trigger_key)(memcached_st *ptr, char *key, size_t key_length, memcached_result_st *result);
+
+=item  MEMCACHED_CALLBACK_DELETE_TRIGGER
+
+This function implements a trigger upon successful deletion of a key. The memcached_st structure will need to be cloned
+in order to make use of it.
+
+The prototype for this is:
+typedef memcached_return (*memcached_trigger_delete_key)(memcached_st *ptr, char *key, size_t key_length);
+
+
+=back
+
+=head1 RETURN
+
+memcached_callback_get() return the function or structure that was provided.
+Upon error, nothing is set, null is returned, and the memcached_return
+argument is set to MEMCACHED_FAILURE.
+
+memcached_callback_set() returns MEMCACHED_SUCCESS upon successful setting,
+otherwise MEMCACHED_FAILURE on error.
+
+=head1 HOME
+
+To find out more information please check:
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Brian Aker, E<lt>brian@tangent.orgE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
+=cut
+

data/ext/libmemcached-0.32/docs/memcached_create.pod

@@ -0,0 +1,61 @@
+=head1 NAME
+
+memcached_create, memcached_free - Create a memcached_st structure
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_st *memcached_create (memcached_st *ptr);
+
+  void memcached_free (memcached_st *ptr);
+
+  memcached_st *memcached_clone(memcached_st *clone, memcached_st *source);
+
+=head1 DESCRIPTION
+
+memcached_create() is used to create a C<memcached_st> structure that will then
+be used by other libmemcached(3) functions to communicate with the server. You
+should either pass a statically declared C<memcached_st> to memcached_create() or
+a NULL. If a NULL passed in then a structure is allocated for you.
+
+memcached_clone() is similar to memcached_create(3) but it copies the
+defaults and list of servers from the source C<memcached_st>. If you pass a null as
+the argument for the source to clone, it is the same as a call to memcached_create().
+If the clone argument is NULL a C<memcached_st> will be allocated for you.
+If you pass a pointer to a memory area for the clone pointer, make sure you 
+memset it to 0 (unless you got the clone from a factory method in libmemcached).
+
+To clean up memory associated with a C<memcached_st> structure you should pass
+it to memcached_free() when you are finished using it. memcached_free() is
+the only way to make sure all memory is deallocated when you finish using
+the structure.
+
+=head1 RETURN
+
+memcached_create() returns a pointer to the memcached_st that was created
+(or initialized). On an allocation failure, it returns NULL.
+
+memcached_clone() returns a pointer to the memcached_st that was created
+(or initialized). On an allocation failure, it returns NULL. If you pass in 
+a preallocated structure it must be cleared first (aka memset()).
+
+=head1 HOME
+
+To find out more information please check:
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Brian Aker, E<lt>brian@tangent.orgE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
+=cut
+

data/ext/libmemcached-0.32/docs/memcached_delete.pod

@@ -0,0 +1,54 @@
+=head1 NAME
+
+memcached_delete - Delete a key
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_return
+    memcached_delete (memcached_st *ptr,
+                      const char *key, size_t key_length,
+                      time_t expiration);
+
+  memcached_return
+  memcached_delete_by_key (memcached_st *ptr,
+                           const char *master_key, size_t master_key_length,
+                           const char *key, size_t key_length,
+                           time_t expiration);
+
+=head1 DESCRIPTION
+
+memcached_delete() is used to delete a particular key. An expiration value
+can be applied so that the key is deleted after that many seconds.
+memcached_delete_by_key() works the same, but it takes a master key to 
+find the given value.
+
+=head1 RETURN
+
+A value of type C<memcached_return> is returned
+On success that value will be C<MEMCACHED_SUCCESS>.
+Use memcached_strerror() to translate this value to a printable string.
+
+If you are using the non-blocking mode of the library, success only
+means that the message was queued for delivery.
+
+=head1 HOME
+
+To find out more information please check:
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Brian Aker, E<lt>brian@tangent.orgE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
+=cut
+

data/ext/libmemcached-0.32/docs/memcached_dump.pod

@@ -0,0 +1,53 @@
+=head1 NAME
+
+memcached_dump - get a list of keys found on memcached servers
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_return
+    memcached_dump (memcached_st *ptr, 
+                    memcached_dump_func *function, 
+                    void *context, 
+                    uint32_t number_of_callbacks);
+
+  typedef memcached_return (*memcached_dump_func)(memcached_st *ptr,  
+                                                  const char *key, 
+                                                  size_t key_length, 
+                                                  void *context);
+
+=head1 DESCRIPTION
+
+memcached_dump() is used to get a list of keys found  memcached(1) servers.
+Because memcached(1) does not guarentee to dump all keys you can not assume
+you have fetched all keys from the server. The function takes an array
+of callbacks that it will use to execute on keys as they are found.
+
+Currently the binar protocol is not supported.
+
+=head1 RETURN
+
+A value of type C<memcached_return> is returned
+On success that value will be C<MEMCACHED_SUCCESS>.
+Use memcached_strerror() to translate this value to a printable string.
+
+=head1 HOME
+
+To find out more information please check:
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Brian Aker, E<lt>brian@tangent.orgE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
+=cut
+

data/ext/libmemcached-0.32/docs/memcached_flush.pod

@@ -0,0 +1,46 @@
+=head1 NAME
+
+memcached_flush - wipe contents of memcached servers
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_return
+    memcached_flush (memcached_st *ptr,
+                     time_t expiration);
+
+=head1 DESCRIPTION
+
+memcached_flush() is used to wipe clean the contents of memcached(1) servers.
+It will either do this immediately or expire the content based on the
+expiration time passed to the method (a value of zero causes an immediate
+flush). The operation is not atomic to multiple servers, just atomic to a
+single server. That is, it will flush the servers in the order that they were
+added.
+
+=head1 RETURN
+
+A value of type C<memcached_return> is returned
+On success that value will be C<MEMCACHED_SUCCESS>.
+Use memcached_strerror() to translate this value to a printable string.
+
+=head1 HOME
+
+To find out more information please check:
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Brian Aker, E<lt>brian@tangent.orgE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
+=cut
+

data/ext/libmemcached-0.32/docs/memcached_flush_buffers.pod

@@ -0,0 +1,42 @@
+=head1 NAME
+
+memcached_flush_buffers - Flush buffers and send buffered commands
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_return
+    memcached_flush_buffers (memcached_st *ptr);
+
+=head1 DESCRIPTION
+
+memcached_flush_buffers() is used in conjunction with 
+MEMCACHED_BEHAVIOR_BUFFER_REQUESTS (see memcached_behavior(3)) to flush
+all buffers by sending the buffered commands to the server for processing..
+
+=head1 RETURN
+
+A value of type C<memcached_return> is returned
+On success that value will be C<MEMCACHED_SUCCESS>.
+Use memcached_strerror() to translate this value to a printable string.
+
+=head1 HOME
+
+To find out more information please check:
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Trond Norbye, E<lt>trond.norbye@sun.comE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_strerror(3) memcached_behavior(3)
+
+=cut
+

data/ext/libmemcached-0.32/docs/memcached_generate_hash_value.pod

@@ -0,0 +1,57 @@
+=head1 NAME
+
+memcached_generate_hash_value - Hash a key value
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  uint32_t
+    memcached_generate_hash_value (const char *key,
+                                   size_t key_length,
+                                   memcached_hash hash_algorithm);
+
+  uint32_t 
+    memcached_generate_hash (memcached_st *ptr,
+                             const char *key, 
+                             size_t key_length);
+
+=head1 DESCRIPTION
+
+memcached_generate_hash_value() allows you to hash a key using one of
+the hash fuctions defined in the library. This method is provided for
+the convenience of higher-level language bindings and is not necessary
+for normal memcache operations.
+
+The allowed hash algorithm constants are listed in the manpage for
+memcached_behavior_set().
+
+memcached_generate_hash() takes a memcached_st struture and produces
+the hash value that would have been generated based on the defaults
+of the memcached_st structure.
+
+=head1 RETURN
+
+A 32-bit integer which is the result of hashing the given key.
+For 64-bit hash algorithms, only the least-significant 32 bits are
+returned.
+
+=head1 HOME
+
+To find out more information please check: 
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Brian Aker, E<lt>brian@tangent.orgE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_behavior_set(3)
+
+=cut
+

data/ext/libmemcached-0.32/docs/memcached_get.pod

@@ -0,0 +1,161 @@
+=head1 NAME
+
+memcached_get, memcached_get_len, memcached_mget, memcached_mget_len, memcached_fetch - Get a value
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_result_st *
+  memcached_fetch_result(memcached_st *ptr, 
+		       memcached_result_st *result,
+		       memcached_return *error);
+
+  char *memcached_get(memcached_st *ptr,
+                      const char *key, size_t key_length,
+                      size_t *value_length, 
+                      uint32_t *flags,
+                      memcached_return *error);
+
+  memcached_return
+  memcached_mget(memcached_st *ptr, 
+                 char **keys, size_t *key_length, 
+                 size_t 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, 
+                       uint32_t user_spec_len,
+                       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, 
+                        size_t number_of_keys,
+                       uint32_t user_spec_len);
+
+  char *memcached_fetch(memcached_st *ptr,
+                        char *key, size_t *key_length, 
+                        size_t *value_length,
+                        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);
+
+  char *
+  memcached_get_len(memcached_st *ptr, 
+                    const char *key, size_t key_length,
+                    uint32_t user_spec_len,
+                    size_t *value_length, 
+                    uint32_t *flags,
+                    memcached_return *error);
+
+  memcached_return
+  memcached_mget_len(memcached_st *ptr, 
+                     const char **keys, size_t *key_length, 
+                     size_t number_of_keys, uint32_t user_spec_len);
+
+=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 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. Any object returned by
+memcached_get() must be released by the caller application. 
+
+memcached_get_len() is also used to fetch an individual value from the
+server.  The only difference when compared to memcached_get() is that
+the server will only send back the first n bytes of the value where n is
+specified by the user.  Note that this command is only available when
+using the ascii protocol.
+
+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
+works asynchronously. memcached_fetch() is then used to retrieve any keys
+found. No error is given on keys that are not found. You must call either
+memcached_fetch() or memcached_fetch_result() after a successful call to
+memcached_mget(). You should continue to call these functions until they
+return NULL (aka no more values). If you need to quit in the middle of a
+memcached_get() call, execute a memcached_quit(). After you do this, you can
+issue new queries against the server.
+
+memcached_mget_len() is also used to select multiple keys at once.  The
+only difference when compared to memcached_mget() is that the server
+will only send back the first n bytes of each value where n is
+specified by the user.  Note that this command is only available when
+using the ascii protocol.
+
+memcached_fetch() is used to fetch an individual value from the server. 
+memcached_mget() or memcached_mget_len() 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 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. 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
+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.
+
+All of the above functions are not supported when the C<MEMCACHED_BEHAVIOR_USE_UDP>
+has been set. Executing any of these functions with this behavior on will result in 
+C<MEMCACHED_NOT_SUPPORTED> being returned or, for those functions which do not return
+a C<memcached_return>, the error function parameter will be set to 
+C<MEMCACHED_NOT_SUPPORTED>.
+
+=head1 RETURN
+
+All objects returned must be freed by the calling application.
+memcached_get(), memcached_get_len(), and memcached_fetch() will return
+NULL on error. You must look at the value of error to determine what
+the actual error was.
+
+=head1 HOME
+
+To find out more information please check:
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Brian Aker, E<lt>brian@tangent.orgE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
+=cut
+