From: Date: Sat, 13 Oct 2007 23:04:08 +0000 (-0700) Subject: Hard to believe I documented the entire thing... this is a first. X-Git-Tag: 0_7~38 X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=a11143256264a00e7437fa23ec8ff5196c5a5c0b;p=m6w6%2Flibmemcached Hard to believe I documented the entire thing... this is a first. We should thank Remedy Tea in Capital Hill who let me drink three pots of their green tea (which is the only reason I got through all of this). --- diff --git a/.hgignore b/.hgignore index b6b95ea4..37ab2ff5 100644 --- a/.hgignore +++ b/.hgignore @@ -15,3 +15,7 @@ Makefile(.in)?$ .(deps|libs)$ \.l?o$ + +# Generated man files +\.1$ +\.3$ diff --git a/ChangeLog b/ChangeLog index ba1e78d3..56244cbd 100644 --- a/ChangeLog +++ b/ChangeLog @@ -3,6 +3,7 @@ * Fixed for more hosts then two. * Rewrite of the read/write IO systems to handle different sorts of host failures. + * Added man pages for all functions and tools 0.5 Tue Oct 9 00:22:25 PDT 2007 * Ruby maintainer mentioned TCP_NODELAY patch he had added. Added this to C diff --git a/docs/Makefile.am b/docs/Makefile.am index 28864ae2..9b9e4f7a 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1 +1,150 @@ INCLUDES = include + +man_MANS = libmemcached.3\ + libmemcached_examples.3\ + memcat.1\ + memcp.1\ + memflush.1\ + memrm.1\ + memslap.1\ + memstat.1\ + memcached_add.3\ + memcached_behavior_get.3\ + memcached_behavior_set.3\ + memcached_create.3\ + memcached_decrement.3\ + memcached_delete.3\ + memcached_fetch.3\ + memcached_free.3\ + memcached_get.3\ + memcached_increment.3\ + memcached_mget.3\ + memcached_replace.3\ + memcached_server_add.3\ + memcached_server_count.3\ + memcached_server_list.3\ + memcached_server_list_append.3\ + memcached_server_list_count.3\ + memcached_server_list_free.3\ + memcached_server_push.3\ + memcached_servers_parse.3\ + memcached_set.3\ + memcached_stat.3\ + memcached_stat_get_keys.3\ + memcached_stat_get_value.3\ + memcached_stat_servername.3\ + memcached_strerror.3\ + memcached_quit.3\ + memcached_verbosity.3 + +libmemcached.3: libmemcached.pod + pod2man libmemcached.pod > libmemcached.3 + +libmemcached_examples.3: libmemcached_examples.pod + pod2man libmemcached_examples.pod > libmemcached_examples.3 + +memcached_create.3: memcached_create.pod + pod2man memcached_create.pod > memcached_create.3 + +memcached_free.3: memcached_create.pod + pod2man memcached_create.pod > memcached_free.3 + +memcached_set.3: memcached_set.pod + pod2man memcached_set.pod > memcached_set.3 + +memcached_replace.3: memcached_set.pod + pod2man memcached_set.pod > memcached_replace.3 + +memcached_add.3: memcached_set.pod + pod2man memcached_set.pod > memcached_add.3 + +memcached_delete.3: memcached_delete.pod + pod2man memcached_delete.pod > memcached_delete.3 + +memcached_increment.3: + pod2man memcached_auto.pod > memcached_increment.3 + +memcached_decrement.3: + pod2man memcached_auto.pod > memcached_decrement.3 + +memcached_flush.3: memcached_flush.pod + pod2man memcached_flush.pod > memcached_flush.3 + +memcached_get.3: memcached_get.pod + pod2man memcached_get.pod > memcached_get.3 + +memcached_mget.3: memcached_get.pod + pod2man memcached_get.pod > memcached_mget.3 + +memcached_fetch.3: memcached_get.pod + pod2man memcached_get.pod > memcached_fetch.3 + +memcached_quit.3: memcached_quit.pod + pod2man memcached_quit.pod > memcached_quit.3 + +memcached_strerror.3: memcached_strerror.pod + pod2man memcached_strerror.pod > memcached_strerror.3 + +memcached_server_count.3: memcached_servers.pod + pod2man memcached_servers.pod > memcached_server_count.3 + +memcached_server_list.3: memcached_servers.pod + pod2man memcached_servers.pod > memcached_server_list.3 + +memcached_server_add.3: memcached_servers.pod + pod2man memcached_servers.pod > memcached_server_add.3 + +memcached_server_push.3: memcached_servers.pod + pod2man memcached_servers.pod > memcached_server_push.3 + +memcached_server_list_free.3: memcached_server_st.pod + pod2man memcached_server_st.pod > memcached_server_list_free.3 + +memcached_server_list_count.3: memcached_server_st.pod + pod2man memcached_server_st.pod > memcached_server_list_count.3 + +memcached_server_list_append.3: memcached_server_st.pod + pod2man memcached_server_st.pod > memcached_server_list_append.3 + +memcached_servers_parse.3: memcached_server_st.pod + pod2man memcached_server_st.pod > memcached_servers_parse.3 + +memcached_verbosity.3: memcached_verbosity.pod + pod2man memcached_verbosity.pod > memcached_verbosity.3 + +memcached_behavior_get.3: memcached_behavior.pod + pod2man memcached_behavior.pod > memcached_behavior_get.3 + +memcached_behavior_set.3: memcached_behavior.pod + pod2man memcached_behavior.pod > memcached_behavior_set.3 + +memcached_stat.3: memcached_stats.pod + pod2man memcached_stats.pod > memcached_stat.3 + +memcached_stat_servername.3: memcached_stats.pod + pod2man memcached_stats.pod > memcached_stat_servername.3 + +memcached_stat_get_value.3: memcached_stats.pod + pod2man memcached_stats.pod > memcached_stat_get_value.3 + +memcached_stat_get_keys.3: memcached_stats.pod + pod2man memcached_stats.pod > memcached_stat_get_keys.3 + +memcp.1: memcp.pod + pod2man memcp.pod > memcp.1 + +memslap.1: memslap.pod + pod2man memslap.pod > memslap.1 + +memcat.1: memcat.pod + pod2man memcat.pod > memcat.1 + +memstat.1: memstat.pod + pod2man memstat.pod > memstat.1 + +memrm.1: memrm.pod + pod2man memrm.pod > memrm.1 + +memflush.1: memflush.pod + pod2man memflush.pod > memflush.1 + diff --git a/docs/libmemcached.pod b/docs/libmemcached.pod new file mode 100755 index 00000000..8840f5d3 --- /dev/null +++ b/docs/libmemcached.pod @@ -0,0 +1,57 @@ +=head1 NAME + +libmemcached - Client library for memcached + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include + +=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." (http://danga.com/memcached/) + +libmemcached has the aim of being a small, thread safe client library for +memcached. The code has all been written with an eye to allow for both web +and embedded usage. It handles the work behind route particular keys to +specifc servers that you specify (and values are matched based on server +order as supplied by you). See more about this via X. + +The aim is to support multiple routing and hashing methods. Currently only +two hashing methods are supported, a built quick routine, and MD5. For +routing a simple modulous method is used currently. + +All operations are performance against memcached_st structure. These +can either be dynamically allocated or statically allocated and initializd +by memcached_create(3). Functions have been written in order to encapsulate +the memcached_st (it is not recommended that you operate directly against +the structure). + +Nearly all functions return a memcached_return value. This is documented in +memcached_strerr(3). + +memcached_st structures are thread safe, but each thread must contain its own structure (aka if you want to share these among threads you must provide your own locking). No global variables are used in this library. + +Some features of the library must be enabled through memcached_behavior_set(3). +Hope you enjoy it! + + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=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_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) + +=cut + diff --git a/docs/libmemcached_examples.pod b/docs/libmemcached_examples.pod new file mode 100755 index 00000000..fadfa7f7 --- /dev/null +++ b/docs/libmemcached_examples.pod @@ -0,0 +1,115 @@ +=head1 NAME + +libmemcached_examples - Examples for libmemcached + +=head1 DESCRIPTION + +For full example, example test cases found in tests/*.c in the main +distribution. These are always up to date, and are used for each test run of +the library. + +=item Creating and Freeing structure + +memcached_st *memc; +memcached_return rc; +struct timeval start_time, end_time; + +memc= memcached_create(NULL); +...do stuff... +memcached_free(memc); + +The above code would create a connection and then free the connection when +finished. + +=item 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 we create a memc object that we then feed in a single +hosts into. In the for loop we build a memcached_server_st* that we then +later feed via memcached_server_push(3) into the memcached_st structure. + +We can reuse the memcached_server_st() object with multile memcached_st +structures. + +=item 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, (uint16_t)0); + assert(rc == MEMCACHED_SUCCESS); + } + + free(value); + +It is best practice to always look at the return value of any operation. + +=item Fetching multiple values + + memcached_return rc; + char *keys[]= {"fudge", "son", "food"}; + size_t key_length[]= {5, 3, 4}; + unsigned int x; + uint16_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 we freed values returned fromm memcached_fetch(3). The define +MEMCACHED_MAX_KEY is provided for usage. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1). + +=cut + diff --git a/docs/memcached_auto.pod b/docs/memcached_auto.pod new file mode 100755 index 00000000..66feefce --- /dev/null +++ b/docs/memcached_auto.pod @@ -0,0 +1,53 @@ +=head1 NAME + +memcached_increment, memcached_decrement + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include + +memcached_return memcached_increment(memcached_st *ptr, + char *key, size_t key_length, + unsigned int offset, + unsigned int *value); +memcached_return memcached_decrement(memcached_st *ptr, + char *key, size_t key_length, + unsigned int offset, + unsigned int *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 +servers to generate 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. + +=head1 RETURN + +memcached_increment() and memcached_decrement() return a memcached_return +value. For information on this value see memcached_strerr(3). + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_behavior.pod b/docs/memcached_behavior.pod new file mode 100755 index 00000000..3b33d7bf --- /dev/null +++ b/docs/memcached_behavior.pod @@ -0,0 +1,65 @@ +=head1 NAME + +memcached_behavior_get memcached_behavior_set + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include + +unsigned long long memcached_behavior_get(memcached_st *ptr, memcached_behavior flag); +memcached_return memcached_behavior_set(memcached_st *ptr, memcached_behavior flag, void *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, like , while being faster can also result in not entirely accurate +behavior (for instance memcached_set will always respond with +MEMCACHED_SUCCES). + +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. + +=item MEMCACHED_BEHAVIOR_NO_BLOCK, + +Causes libmemcached(3) to use asycronous IO. This is the fastest transport +available. + +=item MEMCACHED_BEHAVIOR_TCP_NODELAY, + +Turns on the no-delay feature for connecting sockets (may be faster in some +setups). + +=item MEMCACHED_BEHAVIOR_MD5_HASHING, + +Makes the default hashing algorithm for keys use RSA's MD5. + +=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 whether or not the behavior was enabled. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_create.pod b/docs/memcached_create.pod new file mode 100755 index 00000000..61132d05 --- /dev/null +++ b/docs/memcached_create.pod @@ -0,0 +1,46 @@ +=head1 NAME + +memcached_create, memcached_free + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include +memcached_st *memcached_create(memcached_st *ptr); +void memcached_free(memcached_st *ptr); + +=head1 DESCRIPTION + + +memcached_create() is used to create a memcached_st structure that will then +be used by other libmemcached functions to communicate with the server. You +should either pass a statically declared memcached_st to memcached_create or +a NULL. If a NULL passed in then a structure is allocated for you. + +To clean up memory associated with a 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. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_delete.pod b/docs/memcached_delete.pod new file mode 100755 index 00000000..562bdce7 --- /dev/null +++ b/docs/memcached_delete.pod @@ -0,0 +1,40 @@ +=head1 NAME + +memcached_delete + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include + +memcached_return memcached_delete(memcached_st *ptr, 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 a set number of seconds. + +=head1 RETURN + +memcached_delete() returns memcached_return. The value on success will be MEMCACHED_SUCCESS. For all errors check with memcached_strerror(). +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: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_flush.pod b/docs/memcached_flush.pod new file mode 100755 index 00000000..9f760799 --- /dev/null +++ b/docs/memcached_flush.pod @@ -0,0 +1,41 @@ +=head1 NAME + +memcached_flush + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include +memcached_return memcached_flush(memcached_st *ptr, time_t expiration); + +=head1 DESCRIPTION + + +memcached_flush() is used to wipe clean the contents of memcached servers. +It will either do this immediatly 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. Aka it will flush the servers in the order that they were +added. + +=head1 RETURN + +memcached_flush() returns memcached_return. The value on success will be MEMCACHED_SUCCESS. For all errors check with memcached_strerror(). + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_get.pod b/docs/memcached_get.pod new file mode 100755 index 00000000..f965d547 --- /dev/null +++ b/docs/memcached_get.pod @@ -0,0 +1,67 @@ +=head1 NAME + +memcached_get, memcached_mget, memcached_fetch + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include +char *memcached_get(memcached_st *ptr, char *key, size_t key_length, + size_t *value_length, + uint16_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_fetch(memcached_st *ptr, char *key, size_t *key_length, + size_t *value_length, uint16_t *flags, + memcached_return *error); + +=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, +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. + +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 asyncronously. memcached_fetch() is then used to retrieve any keys +found. No error is given on keys that are not found. + +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, +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. + +=head1 RETURN + +All objects returned must be freed by the calling application. +memcached_get() 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: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_quit.pod b/docs/memcached_quit.pod new file mode 100755 index 00000000..b438e3c0 --- /dev/null +++ b/docs/memcached_quit.pod @@ -0,0 +1,44 @@ +=head1 NAME + +memcached_quit + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include +void memcached_quit(memcached_st *ptr); + +=head1 DESCRIPTION + + +memcached_quit() will disconnect you from all currently connected servers. +It will also reset the state of the connection (aka any memcached_fetch you +are in the middle of will be terminated). This function is called +automatically when you call memcached_free() on the memcached_st structure. + +You do not need to call this on your own. All operations to change server +hashes and parameters will handle connections to the server for you. This +function is provided mainly so that you can timeout your connections or +reset connections during the middle of a memcached_fetch(). + +=head1 RETURN + +memcached_quit() returns memcached_return. The value on success will be MEMCACHED_SUCCESS. For all errors check with memcached_strerror(). + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_server_st.pod b/docs/memcached_server_st.pod new file mode 100755 index 00000000..32fb6ade --- /dev/null +++ b/docs/memcached_server_st.pod @@ -0,0 +1,60 @@ +=head1 NAME + +memcached_server_list_free, memcached_server_list_append, +memcached_server_list_count, memcached_servers_parse + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include + +void memcached_server_list_free(memcached_server_st *ptr); +memcached_server_st *memcached_server_list_append(memcached_server_st *ptr, + char *hostname, unsigned int port, + memcached_return *error); +unsigned int memcached_server_list_count(memcached_server_st *ptr); +memcached_server_st *memcached_servers_parse(char *server_strings); + +=head1 DESCRIPTION + + +libmemcached(3) operates on a list of hosts which are stored in +memcached_server_st structures. You should not modify these structures +directly. Functions are provided to modify these structures (and more can be +added, just ask!). + +memcached_server_list_free() deallocates all memory associated with the array +of memcached_server_st that you passed to it. + +memcached_server_list_append() adds a server to the end of a +memcached_server_st array. On error null will be returned and the +memcached_return pointer you passed into the function will be set with the +appropriate error. If the value of port is zero, it is set to the default +port of a memcached server. + +memcached_servers_parse() takes a string, the type that is used for the +command line applications, and parse it to an array of memcached_server_st. +The example is "localhost, foo:555, foo, bar". All hosts except foo:555 will +be set to the default port, while that host will have a port of 555. + +=head1 RETURN + +Varies, see particular functions. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_servers.pod b/docs/memcached_servers.pod new file mode 100755 index 00000000..3eace72e --- /dev/null +++ b/docs/memcached_servers.pod @@ -0,0 +1,58 @@ +=head1 NAME + +memcached_server_count, memcached_server_list, memcached_server_add, memcached_server_push + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include + +unsigned int memcached_server_count(memcached_st *ptr); +memcached_server_st *memcached_server_list(memcached_st *ptr); +memcached_return memcached_server_add(memcached_st *ptr, char *hostname, unsigned int port); +memcached_return memcached_server_push(memcached_st *ptr, memcached_server_st *list); + +=head1 DESCRIPTION + + +libmemcached(3) performs operations on a list of hosts. The order of these +hosts determine routing to keys. Functions are provided to add keys to +memcached_st structures. To manipulate lists of servers see server_st(3). + +memcached_server_count() provides you a count of the current number of +servers being used by a memcached_st structure. + +memcached_server_list() is used to provide an array of all connected hosts. +You are responsible for freeing this list (aka it is not a pointer to the +currently used structure). + +memcached_server_add() pushes a single server into the memcached_st +structure. This server will be placed at the end. Duplicate servers are +allowed, so duplication is not checked. + +memcached_server_push() pushes an array of memcached_server_st into the memcached_st +structure. These servers will be placed at the end. Duplicate servers are +allowed, so duplication is not checked. A copy is made of structure so the +list provided (and any operations on the list) are not saved. + +=head1 RETURN + +Varies, see particular functions. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_set.pod b/docs/memcached_set.pod new file mode 100755 index 00000000..77d5c140 --- /dev/null +++ b/docs/memcached_set.pod @@ -0,0 +1,68 @@ +=head1 NAME + +memcached_set, memcached_add, memcached_replace + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include +memcached_return memcached_set(memcached_st *ptr, char *key, size_t key_length, + char *value, size_t value_length, + time_t expiration, + uint16_t flags); +memcached_return memcached_add(memcached_st *ptr, char *key, size_t key_length, + char *value, size_t value_length, + time_t expiration, + uint16_t flags); +memcached_return memcached_replace(memcached_st *ptr, char *key, size_t key_length, + char *value, size_t value_length, + time_t expiration, + uint16_t flags); + +=head1 DESCRIPTION + +memcached_set() , memcached_add(), and memcached_replace() are all used to +store information on the server. All methods take a key, and its length to +store the object. Keys are currently limited to 250 charcterss by the +memcached server. You must also supply a value and a length. Optionally you +may support an expiration time for the object and a 16 byte value (it is +meant to be used as a bitmap). + +memcached_set() will write an object to the server. If an object already +exists it will overwrite what is in the server. If the object does not exist +it will be written. If you are using the non-blocking mode this function +will always return true unless a network error occurs. + +memcached_replace() replaces an object on the server. If the object is not +found on the server an error occurs. + +memcached_add() adds an object to the server. If the object is found on the +server an error occurs, otherwise the value is stored. + +memcached_set() with non-blocking IO is the fastest way to store data on the +server. + +=head1 RETURN + +All methods return a memcached_return value. On success the value will be +MEMCACHED_SUCCESS (see memcached_strerror() for more information on this). +For memcached_replace() and memcached_add() MEMCACHED_NOTSTORED is a +legitmate error in the case of a collision. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_stats.pod b/docs/memcached_stats.pod new file mode 100755 index 00000000..40bc183b --- /dev/null +++ b/docs/memcached_stats.pod @@ -0,0 +1,67 @@ +=head1 NAME + +memcached_stat memcached_stat_servername memcached_stat_get_value memcached_stat_get_keys + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include +memcached_stat_st *memcached_stat(memcached_st *ptr, char *args, memcached_return *error); +memcached_return memcached_stat_servername(memcached_stat_st *stat, char *args, + char *hostname, unsigned int port); +char *memcached_stat_get_value(memcached_st *ptr, memcached_stat_st *stat, + char *key, memcached_return *error); +char ** memcached_stat_get_keys(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 +memcached_stat_st structure. You are responsible for freeing this structure. +While it is possible to access the structure directly it is not advisable. +memcached_stat_get_value(3) has been provided to query the structure. + +memcached_stat() fetches an array of memcached_stat_st structures containing +the state of all available memcached servers. The return value must be freed +by the calling application. + +memcached_stat_servername() can be used standalone without a memcached_st to +obtain the state of a particular server. "args" is used to define a +particular state object (a list of these are not provided for by either +the memcached_stat_get_keys call nor are they defined in the memcached +protocol). You must specify the hostname and port fo the server you want to +obtain information on + +memcached_stat_get_value() returns the value of a particular state key. You +specify the key you wish to obtain (this key must be null terminated). + +memcached_stat_get_keys() returns a list of keys that the server has state +objects on. You are responsible for freeing this list. + +A command line tool, memstat(1) is provided so that you do not have to write +an application to do this. + +=head1 RETURN + +memcached_stat() returns memcached_return. The value on success will be MEMCACHED_SUCCESS. For all errors check with memcached_strerror(). +Any method returning a memcached_stat_st expects you to free the memory +allocated for it. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcached_strerror.pod b/docs/memcached_strerror.pod new file mode 100755 index 00000000..342d77fa --- /dev/null +++ b/docs/memcached_strerror.pod @@ -0,0 +1,42 @@ +=head1 NAME + +memcached_strerror + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include +char *memcached_strerror(memcached_st *ptr, memcached_return rc); + +=head1 DESCRIPTION + + +memcached_strerror() takes a memcached_return value and returns a string +describing the error. memcahed_return values are returned from nearly all +libmemcached functions. They are a set of ENUM values describing all +possibly success and failure operations possible in the library. + +memcached_return values are of an ENUM type so that you can set up responses +with switch/case and know that you are capturing all possible return values. + +=head1 RETURN + +memcached_strerror() returns a string describing a memcached_return value. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) + +=cut + diff --git a/docs/memcached_verbosity.pod b/docs/memcached_verbosity.pod new file mode 100755 index 00000000..ea20781d --- /dev/null +++ b/docs/memcached_verbosity.pod @@ -0,0 +1,36 @@ +=head1 NAME + +memcached_verbosity + +=head1 LIBRARY + +C Client Library for memcached (libmemcached, -lmemcached) + +=head1 SYNOPSIS + +#include +memcached_return memcached_verbosity(memcached_st *ptr, unsigned int verbosity); + +=head1 DESCRIPTION + + +memcached_verbosity() is used to modify the "verbosity" of all memcached servers. + +=head1 RETURN + +memcached_verbosity() returns memcached_return. The value on success will be MEMCACHED_SUCCESS. For all errors check with memcached_strerror(). + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) memcached_strerror(3) + +=cut + diff --git a/docs/memcat.pod b/docs/memcat.pod new file mode 100755 index 00000000..8897f591 --- /dev/null +++ b/docs/memcat.pod @@ -0,0 +1,32 @@ +=head1 NAME + +memcat - Copy a set of keys to stdout + +=head1 SYNOPSIS + +memcat [options] key key ... + +=head1 DESCRIPTION + +memcat is a tool designed to copy to stdout a single or mutiple set of keys. +It is designed to work similar to the standard UNIX cat utility. + +You can specify servers via the --servers option or memcat will use the +environmental variable MEMCACHED_SERVERS. + +For a full list of its operations run the tool with the --help option. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) + +=cut + diff --git a/docs/memcp.pod b/docs/memcp.pod new file mode 100755 index 00000000..43090ac9 --- /dev/null +++ b/docs/memcp.pod @@ -0,0 +1,35 @@ +=head1 NAME + +memcp - Copies files to a collection of memcached servers + +=head1 SYNOPSIS + +memcp [options] file file + +=head1 DESCRIPTION + +memcp operates similar to the standard unix cp command. Files will be stored +in the collection of memcached servers specified. Key names will be based on +the name of the file (which does not include its directory path). + +You can specify servers via the --servers option or memcat will use the +environmental variable MEMCACHED_SERVERS. If you specify neither of these +memcp will expect that the final value in the list passed to it is the name +of a server(s). + +For a full list of its operations run the tool with the --help option. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) + +=cut + diff --git a/docs/memflush.pod b/docs/memflush.pod new file mode 100755 index 00000000..1c239202 --- /dev/null +++ b/docs/memflush.pod @@ -0,0 +1,32 @@ +=head1 NAME + +memflush - Reset a server or list of servers + +=head1 SYNOPSIS + +memflush [options] + +=head1 DESCRIPTION + +memflush will reset the contents of a server or group of servers. This means +all data in these servers will be deleted. + +You can specify servers via the --servers option or memcat will use the +environmental variable MEMCACHED_SERVERS. + +For a full list of its operations run the tool with the --help option. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) + +=cut + diff --git a/docs/memrm.pod b/docs/memrm.pod new file mode 100755 index 00000000..f8f8a865 --- /dev/null +++ b/docs/memrm.pod @@ -0,0 +1,32 @@ +=head1 NAME + +memrm - Remove a key(s) from a collection of memcached servers + +=head1 SYNOPSIS + +memrm [options] key key ... + +=head1 DESCRIPTION + +memrm is a tool designed to allow you to remove keys from a collection of +memcached servers. + +You can specify servers via the --servers option or memcat will use the +environmental variable MEMCACHED_SERVERS. + +For a full list of its operations run the tool with the --help option. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) + +=cut + diff --git a/docs/memslap.pod b/docs/memslap.pod new file mode 100755 index 00000000..540ca48e --- /dev/null +++ b/docs/memslap.pod @@ -0,0 +1,32 @@ +=head1 NAME + +memslap - Load testing and benchmarking tool for memcached + +=head1 SYNOPSIS + +memslap [options] + +=head1 DESCRIPTION + +memslap is a load generation and benchmark tool for the memcached server. It +can be used to simualte loads on memcached server clusters. + +You can specify servers via the --servers option or memcat will use the +environmental variable MEMCACHED_SERVERS. + +For a full list of its operations run the tool with the --help option. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) + +=cut + diff --git a/docs/memstat.pod b/docs/memstat.pod new file mode 100755 index 00000000..b5bbf624 --- /dev/null +++ b/docs/memstat.pod @@ -0,0 +1,32 @@ +=head1 NAME + +memstat - Display the operating status of a single or group of memcached servers + +=head1 SYNOPSIS + +memstat [options] + +=head1 DESCRIPTION + +memstat dumps the state of memcached servers. It displays all data to +stdout. + +You can specify servers via the --servers option or memcat will use the +environmental variable MEMCACHED_SERVERS. + +For a full list of its operations run the tool with the --help option. + +=head1 HOME + +To find out more information please check: http://tangent.org/552/libmemcached.html + +=head1 AUTHOR + +Brian Aker, brian@tangent.org + +=head1 SEE ALSO + +memcached(1) libmemcached(3) + +=cut + diff --git a/include/memcached.h b/include/memcached.h index 9df45603..f5378d9a 100644 --- a/include/memcached.h +++ b/include/memcached.h @@ -198,18 +198,16 @@ char *memcached_fetch(memcached_st *ptr, char *key, size_t *key_length, #define memcached_server_name(A,B) B.hostname #define memcached_server_port(A,B) B.port #define memcached_server_list(A) A->hosts -#define memcached_server_response_increment(A,B) A->hosts[B].stack_responses++ -#define memcached_server_response_decrement(A,B) A->hosts[B].stack_responses-- #define memcached_server_response_count(A,B) A->hosts[B].stack_responses memcached_return memcached_server_add(memcached_st *ptr, char *hostname, unsigned int port); +void memcached_server_list_free(memcached_server_st *ptr); +memcached_return memcached_server_push(memcached_st *ptr, memcached_server_st *list); memcached_server_st *memcached_server_list_append(memcached_server_st *ptr, char *hostname, unsigned int port, memcached_return *error); -void memcached_server_list_free(memcached_server_st *ptr); -memcached_return memcached_server_push(memcached_st *ptr, memcached_server_st *list); unsigned int memcached_server_list_count(memcached_server_st *ptr); memcached_server_st *memcached_servers_parse(char *server_strings); diff --git a/lib/common.h b/lib/common.h index 8440f412..f8565be7 100644 --- a/lib/common.h +++ b/lib/common.h @@ -34,4 +34,7 @@ memcached_return memcached_response(memcached_st *ptr, unsigned int memcached_generate_hash(memcached_st *ptr, char *key, size_t key_length); void memcached_quit_server(memcached_st *ptr, unsigned int server_key); +#define memcached_server_response_increment(A,B) A->hosts[B].stack_responses++ +#define memcached_server_response_decrement(A,B) A->hosts[B].stack_responses-- + #endif /* __COMMON_H__ */