From 11d863f7195a8a9e4eac570767950683c1ddf3b7 Mon Sep 17 00:00:00 2001 From: Eric Lambert Date: Tue, 10 Mar 2009 09:16:33 +0100 Subject: [PATCH] Document UDP behavior --- docs/memcached_behavior.pod | 20 ++++++++++++++++++++ docs/memcached_get.pod | 6 ++++++ docs/memcached_servers.pod | 17 +++++++++++++++-- docs/memcached_set.pod | 18 ++++++++++++++++++ docs/memcached_stats.pod | 4 +++- docs/memcached_version.pod | 6 ++++-- 6 files changed, 66 insertions(+), 5 deletions(-) diff --git a/docs/memcached_behavior.pod b/docs/memcached_behavior.pod index 2ff1fb97..bce0b9e8 100755 --- a/docs/memcached_behavior.pod +++ b/docs/memcached_behavior.pod @@ -37,6 +37,26 @@ 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 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, +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 diff --git a/docs/memcached_get.pod b/docs/memcached_get.pod index 0a2edeea..e96a9259 100755 --- a/docs/memcached_get.pod +++ b/docs/memcached_get.pod @@ -104,6 +104,12 @@ as memcached_get() and memcached_mget(). The difference is that they take a master key that is used for determining which server an object was stored if key partitioning was used for storage. +All of the above functions are not supported when the C +has been set. Executing any of these functions with this behavior on will result in +C being returned or, for those functions which do not return +a C, the error function parameter will be set to +C. + =head1 RETURN All objects returned must be freed by the calling application. diff --git a/docs/memcached_servers.pod b/docs/memcached_servers.pod index 0e26e37d..05dd98ed 100755 --- a/docs/memcached_servers.pod +++ b/docs/memcached_servers.pod @@ -20,6 +20,11 @@ C Client Library for memcached (libmemcached, -lmemcached) const char *hostname, unsigned int port); + memcached_return + memcached_server_add_udp (memcached_st *ptr, + const char *hostname, + unsigned int port); + memcached_return memcached_server_add_unix_socket (memcached_st *ptr, const char *socket); @@ -47,9 +52,17 @@ memcached_server_list() is used to provide an array of all defined 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 C +memcached_server_add() pushes a single TCP server into the C +structure. This server will be placed at the end. Duplicate servers are +allowed, so duplication is not checked. Executing this function with the +C behavior set will result in a +C. + +memcached_server_add_udp() pushes a single UDP server into the C structure. This server will be placed at the end. Duplicate servers are -allowed, so duplication is not checked. +allowed, so duplication is not checked. Executing this function with out +setting the C behavior will result in a +C. memcached_server_add_unix_socket() pushes a single UNIX socket into the C structure. This UNIX socket will be placed at the end. diff --git a/docs/memcached_set.pod b/docs/memcached_set.pod index 5e7ac186..0d9a7e1f 100755 --- a/docs/memcached_set.pod +++ b/docs/memcached_set.pod @@ -143,6 +143,24 @@ 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 C +behavior 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, C< 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 C +will be returned. + + =head1 RETURN All methods return a value of type C. diff --git a/docs/memcached_stats.pod b/docs/memcached_stats.pod index 33784cfd..cd486046 100755 --- a/docs/memcached_stats.pod +++ b/docs/memcached_stats.pod @@ -38,7 +38,9 @@ While it is possible to access the structure directly it is not advisable. memcached_stat() fetches an array of C structures containing the state of all available memcached servers. The return value must be freed -by the calling application. +by the calling application. If called with the C +behavior set, a NULL value is returned and the error parameter is set to +C. memcached_stat_servername() can be used standalone without a C to obtain the state of a particular server. "args" is used to define a diff --git a/docs/memcached_version.pod b/docs/memcached_version.pod index 7f502a6e..84cf7f3e 100755 --- a/docs/memcached_version.pod +++ b/docs/memcached_version.pod @@ -36,8 +36,10 @@ A string with the version of libmemcached driver is returned from memcached_lib_version() A value of type C is returned from memcached_version() -On success that value will be C. -Use memcached_strerror() to translate this value to a printable string. +On success that value will be C. If called with the +C behavior set, the value C +will be returned. Use memcached_strerror() to translate this value to +a printable string. =head1 HOME -- 2.30.2