X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fmemcached_set.rst;h=db668b22c7439a028d28cf2514176362d8a7490b;hb=1269230d28c43a67a51b74a5b42fd906be6a172a;hp=d0dbbd267c652476568c4011415e366673b9c7d6;hpb=f285e1b3821f56a8983b5ce9fb1a0070e7bb0a1c;p=m6w6%2Flibmemcached diff --git a/docs/memcached_set.rst b/docs/memcached_set.rst index d0dbbd26..db668b22 100644 --- a/docs/memcached_set.rst +++ b/docs/memcached_set.rst @@ -1,135 +1,43 @@ -.. highlight:: perl +========================================================= +Store, replace, add, or atomically add data to the server +========================================================= +.. index:: object: memcached_st -memcached_set, memcached_add, memcached_replace -*********************************************** - - -Store value on server - - -******* -LIBRARY -******* +-------- +SYNOPSIS +-------- -C Client Library for memcached (libmemcached, -lmemcached) +#include + +.. c:function:: memcached_return_t memcached_set (memcached_st *ptr, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags); -******** -SYNOPSIS -******** +.. c:function:: memcached_return_t memcached_add (memcached_st *ptr, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags); +.. c:function:: memcached_return_t memcached_replace (memcached_st *ptr, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags); +.. c:function:: memcached_return_t memcached_set_by_key(memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags); -.. code-block:: perl +.. c:function:: memcached_return_t memcached_add_by_key(memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags); - #include - - memcached_return_t - memcached_set (memcached_st *ptr, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags); - - memcached_return_t - memcached_add (memcached_st *ptr, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags); - - memcached_return_t - memcached_replace (memcached_st *ptr, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags); - - memcached_return_t - memcached_prepend(memcached_st *ptr, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags) - - memcached_return_t - memcached_append(memcached_st *ptr, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags) - memcached_return_t - memcached_cas(memcached_st *ptr, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags, - uint64_t cas); - - memcached_return_t - memcached_set_by_key(memcached_st *ptr, - const char *master_key, size_t master_key_length, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags); - - memcached_return_t - memcached_add_by_key(memcached_st *ptr, - const char *master_key, size_t master_key_length, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags); - - memcached_return_t - memcached_replace_by_key(memcached_st *ptr, - const char *master_key, size_t master_key_length, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags); - - memcached_return_t - memcached_prepend_by_key(memcached_st *ptr, - const char *master_key, size_t master_key_length, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags); - - memcached_return_t - memcached_append_by_key(memcached_st *ptr, - const char *master_key, size_t master_key_length, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags); - - memcached_return_t - memcached_cas_by_key(memcached_st *ptr, - const char *master_key, size_t master_key_length, - const char *key, size_t key_length, - const char *value, size_t value_length, - time_t expiration, - uint32_t flags, - uint64_t cas); +.. c:function:: memcached_return_t memcached_replace_by_key(memcached_st *ptr, const char *group_key, size_t group_key_length, const char *key, size_t key_length, const char *value, size_t value_length, time_t expiration, uint32_t flags); +Compile and link with -lmemcached -*********** +----------- 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 characters by the -memcached(1) 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). +store the object. Keys are currently limited to 250 characters when using either a version of memcached(1) which is 1.4 or below, or when using the text protocol. +You must supply both a value and a length. Optionally you +may test an expiration time for the object and a 16 byte value (it is +meant to be used as a bitmap). "flags" is a 4byte space that is stored alongside of the main value. Many sub libraries make use of this field, so in most cases users should avoid making use of it. 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 @@ -142,35 +50,28 @@ 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_prepend() places a segment of data before the last piece of data -stored. Currently expiration and key are not used in the server. - -memcached_append() places a segment of data at the end of the last piece of -data stored. Currently expiration and key are not used in the server. - memcached_cas() overwrites data in the server as long as the "cas" value is still the same in the server. You can get the cas value of a result by calling memcached_result_cas() on a memcached_result_st(3) structure. At the point -that this note was written cas is still buggy in memached. Turning on support +that this note was written cas is still buggy in memached. Turning on tests for it in libmemcached(3) is optional. Please see memcached_set() for information on how to do this. -memcached_set_by_key(), memcached_add_by_key(), memcached_replace_by_key(), -memcached_prepend_by_key(), memcached_append_by_key_by_key(), -memcached_cas_by_key() methods all behave in a similar method as the non key -methods. The difference is that they use their master_key parameter to map +memcached_set_by_key(), memcached_add_by_key(), and memcached_replace_by_key() +methods all behave in a similar method as the non key +methods. The difference is that they use their group_key parameter to map objects to particular servers. If you are looking for performance, memcached_set() with non-blocking IO is the fastest way to store data on the server. -All of the above functions are supported with the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ -behavior enabled. But when using these operations with this behavior on, there +All of the above functions are testsed with the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ +behavior enabled. However, when using these operations with this behavior on, there are limits to the size of the payload being sent to the server. The reason for -these limits is that the Memcahed Server does not allow multi-datagram requests +these limits is that the Memcached Server does not allow multi-datagram requests and the current server implementation sets a datagram size to 1400 bytes. Due to protocol overhead, the actual limit of the user supplied data is less than -1400 bytes and depends on the protocol in use as well as the operation being +1400 bytes and depends on the protocol in use as, well as the operation being executed. When running with the binary protocol, \ `` MEMCACHED_BEHAVIOR_BINARY_PROTOCOL``\ , the size of the key,value, flags and expiry combined may not exceed 1368 bytes. When running with the ASCII protocol, the exact limit fluctuates depending on @@ -182,9 +83,9 @@ total size of the command, including overhead, exceeds 1400 bytes, a \ ``MEMCACH will be returned. -****** +------ RETURN -****** +------ All methods return a value of type \ ``memcached_return_t``\ . @@ -195,27 +96,19 @@ For memcached_replace() and memcached_add(), \ ``MEMCACHED_NOTSTORED``\ is a legitmate error in the case of a collision. -**** +---- HOME -**** +---- To find out more information please check: -`https://launchpad.net/libmemcached `_ - - -****** -AUTHOR -****** - - -Brian Aker, +`http://libmemcached.org/ `_ -******** +-------- SEE ALSO -******** +-------- -memcached(1) libmemached(3) memcached_strerror(3) +memcached(1) libmemached(3) memcached_strerror(3) memcached_prepend(3) memcached_cas(3) memcached_append(3)