X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fman%2Fmemcached_cas_by_key.3;h=04da99ef456131ef746be9f92f1a42aa451114bd;hb=2ba52818375fa389a777cf3a2ab3a0249d8a7864;hp=b60ef23124abb2ece128d084c0358e8774cff20d;hpb=f285e1b3821f56a8983b5ce9fb1a0070e7bb0a1c;p=m6w6%2Flibmemcached diff --git a/docs/man/memcached_cas_by_key.3 b/docs/man/memcached_cas_by_key.3 index b60ef231..04da99ef 100644 --- a/docs/man/memcached_cas_by_key.3 +++ b/docs/man/memcached_cas_by_key.3 @@ -1,6 +1,6 @@ -.TH "MEMCACHED_CAS_BY_KEY" "3" "April 07, 2011" "0.47" "libmemcached" +.TH "MEMCACHED_CAS_BY_KEY" "3" "October 18, 2011" "1.01" "libmemcached" .SH NAME -memcached_cas_by_key \- libmemcached Documentation +memcached_cas_by_key \- Storing and Replacing Data . .nr rst2man-indent-level 0 . @@ -30,187 +30,62 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .\" Man page generated from reStructeredText. . -.sp -Store value on server -.SH LIBRARY -.sp -C Client Library for memcached (libmemcached, \-lmemcached) .SH SYNOPSIS .sp -.nf -.ft C #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); -.ft P -.fi +.INDENT 0.0 +.TP +.B 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); +.UNINDENT +.INDENT 0.0 +.TP +.B memcached_return_t memcached_cas_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, uint64_t cas); +.UNINDENT +.sp +Compile and link with \-lmemcached .SH DESCRIPTION .sp -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). -.sp -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. -.sp -memcached_replace() replaces an object on the server. If the object is not -found on the server an error occurs. -.sp -memcached_add() adds an object to the server. If the object is found on the -server an error occurs, otherwise the value is stored. -.sp -memcached_prepend() places a segment of data before the last piece of data -stored. Currently expiration and key are not used in the server. -.sp -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. -.sp -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 -for it in libmemcached(3) is optional. Please see memcached_set() for -information on how to do this. -.sp -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 -objects to particular servers. -.sp -If you are looking for performance, memcached_set() with non\-blocking IO is -the fastest way to store data on the server. -.sp -All of the above functions are supported with the \fBMEMCACHED_BEHAVIOR_USE_UDP\fPbehavior enabled. But 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 -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 -executed. When running with the binary protocol, \(ga\(ga MEMCACHED_BEHAVIOR_BINARY_PROTOCOL\(ga\(ga, -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 -which function is being executed and whether the function is a cas operation -or not. For non\-cas ASCII set operations, there are at least 1335 bytes available -to split among the key, key_prefix, and value; for cas ASCII operations there are -at least 1318 bytes available to split among the key, key_prefix and value. If the -total size of the command, including overhead, exceeds 1400 bytes, a \fBMEMCACHED_WRITE_FAILURE\fPwill be returned. +\fBmemcached_cas()\fP 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 \fBmemcached_result_cas()\fP on a memcached_result_st(3) +structure. At the point that this note was written cas is still buggy in memached. Turning on tests for it in libmemcached(3) is optional. Please see +\fBmemcached_set()\fP for information on how to do this. +.sp +\fBmemcached_cas_by_key()\fP method behaves in a similar method as the non +key methods. The difference is that it uses the \fBgroup_key\fP parameter +to map objects to particular servers. +.sp +\fBmemcached_cas()\fP is testsed with the \fBMEMCACHED_BEHAVIOR_USE_UDP\fP 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 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 executed. When running with the binary protocol, +\fBMEMCACHED_BEHAVIOR_BINARY_PROTOCOL\fP, 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 which function is +being executed and whether the function is a cas operation or not. For +non\-cas ASCII set operations, there are at least 1335 bytes available to +split among the key, key_prefix, and value; for cas ASCII operations there +are at least 1318 bytes available to split among the key, key_prefix and value. If the total size of the command, including overhead, exceeds 1400 bytes, a \fBMEMCACHED_WRITE_FAILURE\fP will be returned. .SH RETURN .sp All methods return a value of type \fBmemcached_return_t\fP. On success the value will be \fBMEMCACHED_SUCCESS\fP. -Use memcached_strerror() to translate this value to a printable string. -.sp -For memcached_replace() and memcached_add(), \fBMEMCACHED_NOTSTORED\fP is a -legitmate error in the case of a collision. +Use \fBmemcached_strerror()\fP to translate this value to a printable +string. .SH HOME .sp To find out more information please check: -\fI\%https://launchpad.net/libmemcached\fP -.SH AUTHOR -.sp -Brian Aker, <\fI\%brian@tangent.org\fP> +\fI\%http://libmemcached.org/\fP .SH SEE ALSO .sp -memcached(1) libmemached(3) memcached_strerror(3) +\fImemcached(1)\fP \fIlibmemached(3)\fP \fImemcached_strerror(3)\fP \fImemcached_set(3)\fP \fImemcached_append(3)\fP \fImemcached_add(3)\fP \fImemcached_prepend(3)\fP \fImemcached_replace(3)\fP .SH AUTHOR Brian Aker .SH COPYRIGHT -2011, Brian Aker +2011, Brian Aker DataDifferential, http://datadifferential.com/ .\" Generated by docutils manpage writer. .\" .