docs: libmemcachedutil

[awesomized/libmemcached] / docs / source / libmemcachedutil / memcached_pool.rst

diff --git a/docs/source/libmemcachedutil/memcached_pool.rst b/docs/source/libmemcachedutil/memcached_pool.rst
index d089147b0813d765a92ec5701da62ef32a80d53a..3b954e3a78799e4607b9ed7310dc1e71f59de8e0 100644 (file)
--- a/docs/source/libmemcachedutil/memcached_pool.rst
+++ b/docs/source/libmemcachedutil/memcached_pool.rst
@@ -11,22 +11,48 @@ SYNOPSIS
 
 .. function:: memcached_pool_st* memcached_pool(const char *option_string, size_t option_string_length)
 
+    :param option_string: :doc:`configuration </libmemcached/configuration>` string
+    :param option_string_length: length of `options_string` without any trailing zero byte
+    :returns: allocated and initialized `memcached_pool_st` instance on success or nullptr on failure
+
 .. function:: memcached_st* memcached_pool_destroy(memcached_pool_st* pool)
 
-.. function:: memcached_st* memcached_pool_fetch(memcached_pool_st*, struct timespec* relative_time, memcached_return_t* rc)
+    :param pool: initialized `memcached_pool_st` instance to free
+    :returns: pointer to the 'master' `memcached_st` instance by legacy
+
+.. function:: memcached_st* memcached_pool_fetch(memcached_pool_st* pool, struct timespec* relative_time, memcached_return_t* rc)
 
     .. versionadded:: 0.53
        Synonym for memcached_pool_pop
 
+    :param pool: initialized `memcached_pool_st` instance
+    :param relative_time: time to block thread and wait for a connection to become available when pool size is exceeded, unless nullptr
+    :param rc: out pointer to `memcached_return_t`
+    :returns: pointer to an available `memcached_st` instance
+
 .. function:: memcached_return_t memcached_pool_release(memcached_pool_st* pool, memcached_st* mmc)
 
     .. versionadded:: 0.53
        Synonym for memcached_pool_push.
 
+    :param pool: initialized `memcached_pool_st` instance
+    :param mmc: the `memcached_st` instance to return to the pool
+    :returns: `memcached_return_t` indicating success
+
 .. function:: memcached_return_t memcached_pool_behavior_set(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t data)
 
+    :param pool: initialized `memcached_pool_st` instance
+    :param flag: the :doc:`behavior </libmemcached/memcached_behavior>` to change
+    :param value: the value to set for `flag`
+    :returns: `memcached_return_t` indicating success
+
 .. function:: memcached_return_t memcached_pool_behavior_get(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t *value)
 
+    :param pool: initialized `memcached_pool_st` instance
+    :param flag: the :doc:`behavior </libmemcached/memcached_behavior>` to read
+    :param value: out pointer to receive the set value of `flag`
+    :returns: `memcached_return_t` indicating success
+
 .. function:: memcached_pool_st* memcached_pool_create(memcached_st* mmc, int initial, int max)
 
     .. deprecated:: 0.46
@@ -81,16 +107,20 @@ pool (or NULL if an allocation cannot be satisfied).
 
 `memcached_pool_release` returns `MEMCACHED_SUCCESS` upon success.
 
-`memcached_pool_behavior_get` and `memcached_pool_behavior_get` returns
+`memcached_pool_behavior_get` and `memcached_pool_behavior_get` return
 `MEMCACHED_SUCCESS` upon success.
 
-If any methods returns MEMCACHED_IN_PROGRESS then a lock on the pool could not
-be obtained. If any of the parameters passed to any of these functions is
-invalid, MEMCACHED_INVALID_ARGUMENTS will be returned.
+`memcached_pool_fetch` may return `MEMCACHED_TIMEOUT` if a timeout occurs while
+waiting for a free `memcached_st` instance, `MEMCACHED_NOTFOUND` if no `memcached_st`
+instance was available, respectively.
+
+.. note::
+    If any method returns `MEMCACHED_IN_PROGRESS` then a lock on the pool could not
+    be obtained.
+
+    If any of the parameters passed to any of these functions is
+    invalid, `MEMCACHED_INVALID_ARGUMENTS` will be returned.
 
-memcached_pool_fetch may return MEMCACHED_TIMEOUT if a timeout occurs while
-waiting for a free memcached_st. MEMCACHED_NOTFOUND if no memcached_st was
-available.
 
 SEE ALSO
 --------