memcached 1.2.6 → 1.2.7

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

@@ -0,0 +1,123 @@
+=head1 NAME
+
+libmemcached - Client library for memcached
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+=head1 DESCRIPTION
+
+"Memcached is a high-performance, distributed memory object caching
+system, generic in nature, but intended for use in speeding up dynamic web
+applications by alleviating database load." L<http://danga.com/memcached/>
+
+B<libmemcached> is a small, thread-safe client library for the
+memcached protocol. The code has all been written with an eye to allow
+for both web and embedded usage. It handles the work behind routing
+particular keys to specific servers that you specify (and values are
+matched based on server order as supplied by you). It implements both
+a modula and consistent method of object distribution.
+
+There are multiple implemented routing and hashing methods. See the
+memcached_behavior_set() manpage.
+
+All operations are performed against a C<memcached_st> structure.
+These structures can either be dynamically allocated or statically
+allocated and then initialized by memcached_create(). Functions have been
+written in order to encapsulate the C<memcached_st>. It is not
+recommended that you operate directly against the structure.
+
+Nearly all functions return a C<memcached_return> value.
+This value can be translated to a printable string with memcached_strerror(3).
+
+Partitioning based on keys is supported in the library. Using the key partioning
+functions it is possible to group sets of object onto servers.
+
+C<memcached_st> structures are thread-safe, but each thread must
+contain its own structure (that is, if you want to share these among
+threads you must provide your own locking). No global variables are
+used in this library.
+
+If you are working with GNU autotools you will want to add the following to
+your configure.ac to properly include libmemcached in your application.
+
+PKG_CHECK_MODULES(DEPS, libmemcached >= 0.8.0)
+AC_SUBST(DEPS_CFLAGS)
+AC_SUBST(DEPS_LIBS)
+
+Some features of the library must be enabled through memcached_behavior_set().
+
+Hope you enjoy it!
+
+=head1 CONSTANTS
+
+A number of constants have been provided for in the library.
+
+=over 4
+
+=item MEMCACHED_DEFAULT_PORT
+
+The default port used by memcached(3).
+
+=item MEMCACHED_MAX_KEY
+
+Default maximum size of a key (which includes the null pointer). Master keys
+have no limit, this only applies to keys used for storage.
+
+=item MEMCACHED_MAX_KEY
+
+Default size of key (which includes the null pointer).
+
+=item MEMCACHED_MAX_HOST_LENGTH
+
+Maximum allowed size of the hostname.
+
+=item MEMCACHED_VERSION_STRING
+
+String value of libmemcached version such as "1.23.4"
+
+=item MEMCACHED_MAJOR_VERSION
+
+Major version value. Such as 1.23.4, would be 1
+
+=item MEMCACHED_MINOR_VERSION
+
+Major version value. Such as 1.23.4, would be 23
+
+=item MEMCACHED_MICRO_VERSION
+
+Major version value. Such as 1.23.4, would be 4
+
+
+=back
+
+
+
+=head1 THREADS AND PROCESSES
+
+When using threads or forked processes it is important to keep an instance
+of C<memcached_st> per process or thread. Without creating your own locking
+structures you can not share a single C<memcached_st>. You can though call
+memcached_quit(3) on a C<memcached_st> and then use the resulting cloned
+structure.
+
+=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_examples(3) libmemcached(1) memcat(1) memcp(1) memflush(1) memrm(1) memslap(1) memstat(1) memcached_fetch(3) memcached_replace(3) memcached_server_list_free(3) libmemcached_examples(3) memcached_clone(3) memcached_free(3) memcached_server_add(3) memcached_server_push(3) memcached_add(3) memcached_get(3) memcached_server_count(3) memcached_servers_parse(3) memcached_create(3) memcached_increment(3) memcached_server_list(3) memcached_set(3) memcached_decrement(3) memcached_mget(3) memcached_server_list_append(3) memcached_strerror(3) memcached_delete(3) memcached_quit(3) memcached_server_list_count(3) memcached_verbosity(3) memcached_server_add_unix_socket(3) memcached_result_create(3)  memcached_result_free(3)  memcached_result_key_value(3)  memcached_result_key_length(3)  memcached_result_value(3)  memcached_result_length(3)  memcached_result_flags(3)  memcached_result_cas(3) memcached_result_st(3) memcached_append(3) memcached_prepend(3) memcached_fetch_result(3) memerror(1) memcached_get_by_key(3) memcached_mget_by_key(3) memcached_delete_by_key(3) memcached_fetch_execute(3) memcached_callback_get(3) memcached_callback_set(3) memcached_version(3) memcached_lib_version(3) memcached_result_set_value(3) memcached_dump(3) memdump(1) memcached_set_memory_allocators(3) memcached_get_memory_allocators(3) memcached_get_user_data(3) memcached_set_user_data(3)
+
+=cut
+

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

@@ -0,0 +1,115 @@
+=head1 NAME
+
+libmemcached_examples - Examples for libmemcached
+
+=head1 DESCRIPTION
+
+For full examples, test cases are found in tests/*.c in the main
+distribution. These are always up to date, and are used for each test run of
+the library.
+
+=head2 Creating and Freeing structure
+
+  memcached_st *memc;
+  memcached_return rc;
+
+  memc= memcached_create(NULL);
+  ...do stuff...
+  memcached_free(memc);
+
+The above code would create a connection and then free the connection when
+finished.
+
+=head2 Connecting to servers
+
+  memcached_server_st *servers;
+  memcached_st *memc= memcached_create(NULL);
+  char servername[]= "0.example.com";
+
+  servers= memcached_server_list_append(NULL, servername, 400, &rc);
+
+  for (x= 0; x < 20; x++)
+  {
+    char buffer[SMALL_STRING_LEN];
+
+    snprintf(buffer, SMALL_STRING_LEN, "%u.example.com", 400+x);
+    servers= memcached_server_list_append(servers, buffer, 401, &rc);
+  }
+  rc= memcached_server_push(memc, servers);
+  memcached_server_free(servers);
+  memcached_free(memc);
+
+In the above code you create a C<memcached_st> object that you then feed in a
+single host into. In the for loop you build a C<memcached_server_st>
+pointer that you then later feed via memcached_server_push() into the
+C<memcached_st> structure.
+
+You can reuse the C<memcached_server_st> object with multile C<memcached_st>
+structures.
+
+=head2 Adding a value to the server
+
+  char *key= "foo";
+  char *value;
+  size_t value_length= 8191;
+  unsigned int x;
+
+  value = (char*)malloc(value_length);
+  assert(value);
+
+  for (x= 0; x < value_length; x++)
+  value[x] = (char) (x % 127);
+
+  for (x= 0; x < 1; x++)
+  {
+    rc= memcached_set(memc, key, strlen(key), 
+    value, value_length,
+    (time_t)0, (uint32_t)0);
+    assert(rc == MEMCACHED_SUCCESS);
+  }
+
+  free(value);
+
+It is best practice to always look at the return value of any operation.
+
+=head2 Fetching multiple values
+
+  memcached_return rc;
+  char *keys[]= {"fudge", "son", "food"};
+  size_t key_length[]= {5, 3, 4};
+  unsigned int x;
+  uint32_t flags;
+
+  char return_key[MEMCACHED_MAX_KEY];
+  size_t return_key_length;
+  char *return_value;
+  size_t return_value_length;
+
+  rc= memcached_mget(memc, keys, key_length, 3);
+
+  x= 0;
+  while ((return_value= memcached_fetch(memc, return_key, &return_key_length, 
+                                        &return_value_length, &flags, &rc)))
+  {
+    free(return_value);
+    x++;
+  }
+
+Notice that you freed values returned from memcached_fetch(). The define
+C<MEMCACHED_MAX_KEY> is provided for usage.
+
+=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)
+
+=cut
+

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

@@ -0,0 +1,40 @@
+=head1 NAME
+
+libmemcachedutil - Utility library for libmemcached
+
+=head1 LIBRARY
+
+C Client Library containing utility functions for libmemcached (libmemcachedutil, -lmemcachedutil)
+
+=head1 SYNOPSIS
+
+  cc [ flag ... ] file ... -lmemcachedutil
+
+  #include <libmemcached/memcached_util.h>
+
+=head1 DESCRIPTION
+
+B<libmemcachedutil> is a small and thread-safe client library that provides
+extra functionality built on top of B<libmemcached>.
+
+=head1 THREADS
+
+Do not try to access an instance of C<memcached_st> from multiple threads
+at the same time. If you want to access memcached from multiple threads
+you should either clone the C<memcached_st>, or use the memcached pool
+implementation. see memcached_pool_create(3).
+
+=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
+
+libmemcached(3) memcached_pool_create(3) memcached_pool_destroy(3) memcached_pool_pop(3) memcached_pool_push(3)
+
+=cut

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

@@ -0,0 +1,52 @@
+=head1 NAME
+
+memcached_analyze - Analyze server information
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_analysis_st *memcached_analyze(memcached_st *ptr,
+                                           memcached_stat_st *stat,
+                                           memcached_return *error);
+
+=head1 DESCRIPTION
+
+libmemcached(3) has the ability to query a memcached server (or collection
+of servers) for their current state. Queries to find state return a
+C<memcached_analysis_st> structure. You are responsible for freeing this structure.
+
+memcached_analyze() analyzes useful information based on the provided servers
+and sets the result to the C<memcached_analysis_st> structure. The return value
+must be freed by the calling application.
+
+A command line tool, memstat(1) with the option --analyze, is provided so that
+you do not have to write an application to use this method.
+
+=head1 RETURN
+
+A pointer to the allocated C<memcached_analysis_st> structure on success and
+a NULL pointer on failure. You may inspect the error detail by checking the
+C<memcached_return> value.
+
+Any method returning a C<memcached_analysis_st> expects you to free the
+memory allocated for it.
+
+=head1 HOME
+
+To find out more information please check:
+L<http://tangent.org/552/libmemcached.html>
+
+=head1 AUTHOR
+
+Toru Maesaka, E<lt>dev@torum.netE<gt>
+
+=head1 SEE ALSO
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
+=cut

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

@@ -0,0 +1,97 @@
+=head1 NAME
+
+memcached_increment, memcached_decrement,
+memcached_increment_with_initial, memcached_decrement_with_initial - Manipulate
+counters
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  memcached_return
+    memcached_increment (memcached_st *ptr, 
+                         const char *key, size_t key_length,
+                         unsigned int offset,
+                         uint64_t *value);
+
+  memcached_return
+    memcached_decrement (memcached_st *ptr, 
+                         const char *key, size_t key_length,
+                         unsigned int offset,
+                         uint64_t *value);
+
+  memcached_return
+    memcached_increment_with_initial (memcached_st *ptr,
+                                      const char *key,
+                                      size_t key_length,
+                                      uint64_t offset,
+                                      uint64_t initial,
+                                      time_t expiration,
+                                      uint64_t *value);
+
+  memcached_return
+    memcached_decrement_with_initial (memcached_st *ptr,
+                                      const char *key,
+                                      size_t key_length,
+                                      uint64_t offset,
+                                      uint64_t initial,
+                                      time_t expiration,
+                                      uint64_t *value);
+
+=head1 DESCRIPTION
+
+memcached(1) servers have the ability to increment and decrement keys
+(overflow and underflow are not detected). This gives you the ability to use
+memcached to generate shared sequences of values.  
+
+memcached_increment() takes a key and keylength and increments the value by
+the offset passed to it. The value is then returned via the unsigned int
+value pointer you pass to it.
+
+memcached_decrement() takes a key and keylength and decrements the value by
+the offset passed to it. The value is then returned via the unsigned int
+value pointer you pass to it.
+
+memcached_increment_with_initial() takes a key and keylength and increments
+the value by the offset passed to it. If the object specified by key does
+not exist, one of two things may happen: If the expiration value is
+MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other
+expiration values, the operation will succeed by seeding the value for that
+key with a initial value to expire with the provided expiration time. The
+flags will be set to zero.The value is then returned via the unsigned int
+value pointer you pass to it.
+
+memcached_decrement_with_initial() takes a key and keylength and decrements
+the value by the offset passed to it. If the object specified by key does
+not exist, one of two things may happen: If the expiration value is
+MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other
+expiration values, the operation will succeed by seeding the value for that
+key with a initial value to expire with the provided expiration time. The
+flags will be set to zero.The value is then returned via the unsigned int
+value pointer you pass to it.
+
+=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_behavior.pod

@@ -0,0 +1,224 @@
+=head1 NAME
+
+memcached_behavior_get, memcached_behavior_set - Manipulate behavior
+
+=head1 LIBRARY
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+=head1 SYNOPSIS
+
+  #include <memcached.h>
+
+  uint64_t
+    memcached_behavior_get (memcached_st *ptr,
+                            memcached_behavior flag);
+
+  memcached_return
+    memcached_behavior_set (memcached_st *ptr,
+                            memcached_behavior flag,
+                            uint64_t data);
+
+=head1 DESCRIPTION
+
+libmemcached(3) behavior can be modified by use memcached_behavior_set().
+Default behavior is the library strives to be quick and accurate. Some
+behavior, while being faster, can also result in not entirely accurate
+behavior (for instance, memcached_set() will always respond with
+C<MEMCACHED_SUCCESS>).
+
+memcached_behavior_get() takes a behavior flag and returns whether or not
+that behavior is currently enabled in the client.
+
+memcached_behavior_set() changes the value of a particular option of the
+client. It takes both a flag (listed below) and a value. For simple on or
+off options you just need to pass in a value of 1. Calls to
+memcached_behavior_set() will flush and reset all connections.
+
+=over 4
+
+=item MEMCACHED_BEHAVIOR_USE_UDP
+
+Causes libmemcached(3) to use the UDP transport when communicating
+with a memcached server. Not all I/O operations are supported
+when this behavior is enababled. The following operations will return
+C<MEMCACHED_NOT_SUPPORTED> when executed with the MEMCACHED_BEHAVIOR_USE_UDP
+enabled: memcached_version(), memcached_stat(), memcached_get(),
+memcached_get_by_key(), memcached_mget(), memcached_mget_by_key(),
+memcached_fetch(), memcached_fetch_result(), memcached_value_fetch().
+
+All other operations are supported but are executed in a 'fire-and-forget'
+mode, in which once the client has executed the operation, no attempt
+will be made to ensure the operation has been received and acted on by the
+server.
+
+libmemcached(3) does not allow TCP and UDP servers to be shared within
+the same libmemached(3) client 'instance'. An attempt to add a TCP server
+when this behavior is enabled will result in a C<MEMCACHED_INVALID_HOST_PROTOCOL>,
+as will attempting to add a UDP server when this behavior has not been enabled.
+
+=item MEMCACHED_BEHAVIOR_NO_BLOCK
+
+Causes libmemcached(3) to use asychronous IO. This is the fastest transport
+available for storage functions.
+
+=item MEMCACHED_BEHAVIOR_SND_TIMEOUT
+
+This sets the microsecond behavior of the socket against the SO_SNDTIMEO flag.
+In cases where you cannot use non-blocking IO this will allow you to still have
+timeouts on the sending of data.
+
+=item MEMCACHED_BEHAVIOR_RCV_TIMEOUT
+
+This sets the microsecond behavior of the socket against the SO_RCVTIMEO flag.
+In cases where you cannot use non-blocking IO this will allow you to still have
+timeouts on the reading of data.
+
+=item MEMCACHED_BEHAVIOR_TCP_NODELAY
+
+Turns on the no-delay feature for connecting sockets (may be faster in some
+environments).
+
+=item MEMCACHED_BEHAVIOR_HASH
+
+Makes the default hashing algorithm for keys use MD5. The value can be set
+to either MEMCACHED_HASH_DEFAULT, MEMCACHED_HASH_MD5, MEMCACHED_HASH_CRC, MEMCACHED_HASH_FNV1_64, MEMCACHED_HASH_FNV1A_64, MEMCACHED_HASH_FNV1_32, MEMCACHED_HASH_FNV1A_32, MEMCACHED_HASH_JENKINS, MEMCACHED_HASH_HSIEH, and MEMCACHED_HASH_MURMUR.
+Each hash has it's advantages and it's weaknesses. If you dont know or dont care, just go with the default.
+Support for MEMCACHED_HASH_HSIEH is a compile time option that is disabled by default. To enable support for this hashing algorithm, configure and build libmemcached with the --enable-hash_hsieh.
+
+=item MEMCACHED_BEHAVIOR_DISTRIBUTION
+
+Using this you can enable different means of distributing values to servers.
+The default method is MEMCACHED_DISTRIBUTION_MODULA. You can enable
+consistent hashing by setting MEMCACHED_DISTRIBUTION_CONSISTENT.
+Consistent hashing delivers better distribution and allows servers to be
+added to the cluster with minimal cache losses. Currently
+MEMCACHED_DISTRIBUTION_CONSISTENT is an alias for the value
+MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA.
+
+=item MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
+
+Memcached can cache named lookups so that DNS lookups are made only once.
+
+=item MEMCACHED_BEHAVIOR_SUPPORT_CAS
+
+Support CAS operations (this is not enabled by default at this point in the server since it imposes a slight performance penalty).
+
+=item MEMCACHED_BEHAVIOR_KETAMA
+
+Sets the default distribution to MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
+and the hash to MEMCACHED_HASH_MD5.
+
+=item MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
+
+Sets the default distribution to MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA with the weighted support.
+and the hash to MEMCACHED_HASH_MD5.
+
+=item MEMCACHED_BEHAVIOR_KETAMA_HASH
+
+Sets the hashing algorithm for host mapping on continuum. The value can be set
+to either MEMCACHED_HASH_DEFAULT, MEMCACHED_HASH_MD5, MEMCACHED_HASH_CRC, MEMCACHED_HASH_FNV1_64, MEMCACHED_HASH_FNV1A_64, MEMCACHED_HASH_FNV1_32, and MEMCACHED_HASH_FNV1A_32.
+
+=item MEMCACHED_BEHAVIOR_POLL_TIMEOUT
+
+Modify the timeout value that is used by poll(). The default value is -1. An signed int pointer must be passed to memcached_behavior_set() to change this value. For memcached_behavior_get() a signed int value will be cast and returned as the unsigned long long.
+
+=item MEMCACHED_BEHAVIOR_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. This was deprecated in 0.14 in favor
+of memcached_callback_set(3). This will be removed in 0.15.
+
+=item MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
+
+Enabling buffered IO causes commands to "buffer" instead of being sent. Any
+action that gets data causes this buffer to be be sent to the remote
+connection. Quiting the connection or closing down the connection will also
+cause the buffered data to be pushed to the remote connection.
+
+=item MEMCACHED_BEHAVIOR_VERIFY_KEY
+
+Enabling this will cause libmemcached(3) to test all keys to verify that they
+are valid keys.
+
+=item MEMCACHED_BEHAVIOR_SORT_HOSTS
+
+Enabling this will cause hosts that are added to be placed in the host list in
+sorted order. This will defeat consisten hashing.
+
+=item MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
+
+In non-blocking mode this changes the value of the timeout during socket
+connection.
+
+=item MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
+
+Enable the use of the binary protocol. Please note that you cannot toggle
+this flag on an open connection.
+
+=item MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
+
+Set this value to enable the server be removed after continuous MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
+times connection failure.
+
+=item MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
+
+Set this value to tune the number of messages that may be sent before
+libmemcached should start to automatically drain the input queue. Setting
+this value to high, may cause libmemcached to deadlock (trying to send data,
+but the send will block because the input buffer in the kernel is full).
+
+=item MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
+
+Set this value to tune the number of bytes that may be sent before
+libmemcached should start to automatically drain the input queue (need
+at least 10 IO requests sent without reading the input buffer). Setting
+this value to high, may cause libmemcached to deadlock (trying to send
+data, but the send will block because the input buffer in the kernel is full).
+
+=item MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
+
+The binary protocol works a bit different than the textual protocol in
+that a multiget is implemented as a pipe of single get-operations which
+are sent to the server in a chunk. If you are using large multigets from
+your application, you may improve the latency of the gets by setting
+this value so you send out the first chunk of requests when you hit the
+specified limit.  It allows the servers to start processing the requests
+to send the data back while the rest of the requests are created and
+sent to the server.
+
+=item MEMCACHED_BEHAVIOR_NOREPLY
+
+Set this value to specify that you really don't care about the result
+from your storage commands (set, add, replace, append, prepend).
+
+=back
+
+=head1 RETURN
+
+memcached_behavior_get() returns either the current value of the get, or 0
+or 1 on simple flag behaviors (1 being enabled). memcached_behavior_set()
+returns failure or success.
+
+=head1 NOTES
+
+memcached_behavior_set() in version .17 was changed from taking a pointer
+to data value, to taking a uin64_t.
+
+=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
+