Document UDP behavior

diff --git a/docs/memcached_behavior.pod b/docs/memcached_behavior.pod
index 2ff1fb970966d5c229bfc012f057637ef491038c..bce0b9e84c92d395df01cf465b12902ed5e40bd0 100755 (executable)
--- 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<MEMCACHED_NOT_SUPPORTED> 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<MEMCACHED_INVALID_HOST_PROTOCOL>,
+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 0a2edeea7361d7f7ddb9792e61a97b422d803791..e96a92597f178cad86c8ab4899740a920aef8c6a 100755 (executable)
--- 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<MEMCACHED_BEHAVIOR_USE_UDP>
+has been set. Executing any of these functions with this behavior on will result in 
+C<MEMCACHED_NOT_SUPPORTED> being returned or, for those functions which do not return
+a C<memcached_return>, the error function parameter will be set to 
+C<MEMCACHED_NOT_SUPPORTED>.
+
 =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 0e26e37d58e83938c55828854e7d514485e71175..05dd98ed22dd3d40d90257a548ee835a3fccba8c 100755 (executable)
--- 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_st>
+memcached_server_add() pushes a single TCP server into the C<memcached_st>
+structure. This server will be placed at the end. Duplicate servers are
+allowed, so duplication is not checked. Executing this function with the
+C<MEMCACHED_BEHAVIOR_USE_UDP> behavior set will result in a 
+C<MEMCACHED_INVALID_HOST_PROTOCOL>.
+
+memcached_server_add_udp() pushes a single UDP server into the C<memcached_st>
 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<MEMCACHED_BEHAVIOR_USE_UDP> behavior will result in a 
+C<MEMCACHED_INVALID_HOST_PROTOCOL>.
 
 memcached_server_add_unix_socket() pushes a single UNIX socket into the 
 C<memcached_st> structure. This UNIX socket will be placed at the end. 

diff --git a/docs/memcached_set.pod b/docs/memcached_set.pod
index 5e7ac18626e2ef8bccc660c86b2a5182bc8cdc2e..0d9a7e1f4865c40a8847dab1b3164a7ae40ad304 100755 (executable)
--- 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<MEMCACHED_BEHAVIOR_USE_UDP>
+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<MEMCACHED_WRITE_FAILURE>
+will be returned.
+
+
 =head1 RETURN
 
 All methods return a value of type C<memcached_return>.

diff --git a/docs/memcached_stats.pod b/docs/memcached_stats.pod
index 33784cfd9c5cbaa0e01c60b845fab8f6a329066a..cd486046ba36c3ee95d9fc8c67cc36988121862e 100755 (executable)
--- 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<memcached_stat_st> 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<MEMCACHED_BEHAVIOR_USE_UDP>
+behavior set, a NULL value is returned and the error parameter is set to 
+C<MEMCACHED_NOT_SUPPORTED>.
 
 memcached_stat_servername() can be used standalone without a C<memcached_st> 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 7f502a6e78015d7fe5c51f940db09cad9b7918c8..84cf7f3ec5dfd3da07bf9029ddcecc72a20448c1 100755 (executable)
--- 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<memcached_return> is returned from memcached_version()
-On success that value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
+On success that value will be C<MEMCACHED_SUCCESS>. If called with the
+C<MEMCACHED_BEHAVIOR_USE_UDP> behavior set, the value C<MEMCACHED_NOT_SUPPORTED> 
+will be returned. Use memcached_strerror() to translate this value to 
+a printable string.
 
 =head1 HOME