X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fsource%2Flibmemcached%2Fmemcached_cas.rst;h=ce490b21ae24eb962fe553d4e396d8807c778740;hb=8691d09c0c8905ce8624fbd60dea859f65ecc22a;hp=da198ce9b419ddccd502138452c53ad75a4d8c16;hpb=28c4d79e109e11d7d2a9f3189de57da28302ec68;p=awesomized%2Flibmemcached diff --git a/docs/source/libmemcached/memcached_cas.rst b/docs/source/libmemcached/memcached_cas.rst index da198ce9..ce490b21 100644 --- a/docs/source/libmemcached/memcached_cas.rst +++ b/docs/source/libmemcached/memcached_cas.rst @@ -1,71 +1,83 @@ -==================================================== Working with data on the server in an atomic fashion ==================================================== -.. index:: object: memcached_st - - --------- SYNOPSIS -------- - #include + Compile and link with -lmemcached .. function:: 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) .. function:: 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) -Compile and link with -lmemcached + :param ptr: pointer to an initialized `memcached_st` struct + :param group_key: key namespace + :param group_key_length: length of the `group_key` without any trailing zero + :param key: the key to check + :param key_length: the length of the `key` without any trailing zero + :param value: the value to set + :param value_length: the length of the `value` without any trailing zero + :param expiration: expiration time as unix timestamp or relative time in seconds + :param flags: 16 bit flags + :param cas: the ``cas`` value to compare + :returns: `memcached_return_t` indicating success - ------------ DESCRIPTION ----------- -:func:`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 :func:`memcached_result_cas` on a memcached_result_st(3) -structure. At the point that this note was written cas is still buggy in memcached. -Turning on tests for it in libmemcached(3) is optional. Please see -:func:`memcached_set` for information on how to do this. - -:func:`memcached_cas_by_key` method behaves in a similar method as the non -key methods. The difference is that it uses the group_key parameter -to map objects to particular servers. - -:func:`memcached_cas` is tested 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 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, -`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 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 `MEMCACHED_WRITE_FAILURE` will be returned. - - ------- -RETURN ------- - - -All methods return a value of type :type:`memcached_return_t`. +`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` structure. + +`memcached_cas_by_key` method behaves in a similar way as the non key methods. +The difference is that it uses the ``group_key`` parameter to map objects to +particular servers. + +`memcached_cas` is tested 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 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, +`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 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 `MEMCACHED_WRITE_FAILURE` +will be returned. + +RETURN VALUE +------------ + +All methods return a value of type `memcached_return_t`. On success the value will be `MEMCACHED_SUCCESS`. -Use :func:`memcached_strerror` to translate this value to a printable +Use `memcached_strerror` to translate this value to a printable string. - --------- SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` :manpage:`memcached_set(3)` :manpage:`memcached_append(3)` :manpage:`memcached_add(3)` :manpage:`memcached_prepend(3)` :manpage:`memcached_replace(3)` - + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + :manpage:`memcached_set(3)` + :manpage:`memcached_append(3)` + :manpage:`memcached_add(3)` + :manpage:`memcached_prepend(3)` + :manpage:`memcached_replace(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_set` + * :doc:`memcached_append` + * :doc:`memcached_strerror`