git.m6w6.name Git - awesomized/libmemcached/blob - docs/memcached_pool.rst

   1 ============================
   2 Working with memcached pools
   3 ============================
   4
   5 --------
   6 SYNOPSIS
   7 --------
   8
   9 #include <libmemcached/memcached_pool.h>
  10
  11 .. c:type:: memcached_pool_st
  12
  13 .. c:function:: memcached_pool_st* memcached_pool(const char *option_string, size_t option_string_length)
  14
  15 .. c:function:: memcached_pool_st* memcached_pool_create(memcached_st* mmc, int initial, int max)
  16 .. deprecated:: 0.46
  17    Use :c:func:`memcached_pool()`
  18
  19 .. c:function:: memcached_st* memcached_pool_destroy(memcached_pool_st* pool)
  20
  21 .. c:function:: memcached_st* memcached_pool_pop(memcached_pool_st* pool, bool block, memcached_return_t *rc)
  22 .. deprecated:: 0.53
  23    Use :c:func:`memcached_pool_fetch()`
  24
  25 .. c:function:: memcached_st* memcached_pool_fetch(memcached_pool_st*, struct timespec* relative_time, memcached_return_t* rc);
  26
  27 .. versionadded:: 0.53
  28    Synonym for memcached_pool_pop()
  29
  30 .. c:function:: memcached_return_t memcached_pool_push(memcached_pool_st* pool, memcached_st *mmc)
  31 .. deprecated:: 0.53
  32    Use :c:func:`memcached_pool_push()`
  33
  34 .. c:function:: memcached_return_t memcached_pool_release(memcached_pool_st* pool, memcached_st* mmc);
  35 .. versionadded:: 0.53
  36    Synonym for memcached_pool_push().
  37
  38 .. c:function:: memcached_return_t memcached_pool_behavior_set(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t data)
  39
  40 .. c:function:: memcached_return_t memcached_pool_behavior_get(memcached_pool_st *pool, memcached_behavior_t flag, uint64_t *value)
  41
  42 Compile and link with -lmemcachedutil -lmemcached
  43
  44 -----------
  45 DESCRIPTION
  46 -----------
  47
  48
  49 :c:func:`memcached_pool()` is used to create a connection pool of objects you
  50 may use to remove the overhead of using memcached_clone for short lived
  51 :c:type:`memcached_st` objects. Please see :doc:`libmemcached_configuration` for details on the format of the configuration string.
  52
  53 :c:func:`memcached_pool_destroy()` is used to destroy the connection pool
  54 created with :c:func:`memcached_pool_create()` and release all allocated
  55 resources. It will return the pointer to the :c:type:`memcached_st` structure
  56 passed as an argument to :c:func:`memcached_pool_create()`, and returns the ownership of the pointer to the caller when created with :c:func:`memcached_pool_create()`, otherwise NULL is returned..
  57
  58 :c:func:`memcached_pool_fetch()` is used to fetch a connection structure from the
  59 connection pool. The relative_time argument specifies if the function should
  60 block and wait for a connection structure to be available if we try
  61 to exceed the maximum size. You need to specify time in relative time.
  62
  63 :c:func:`memcached_pool_release()` is used to return a connection structure back to the pool.
  64
  65 :c:func:`memcached_pool_behavior_get()` and :c:func:`memcached_pool_behavior_set()` is used to get/set behavior flags on all connections in the pool.
  66
  67 Both :c:func:`memcached_pool_release()` and :c:func:`memcached_pool_fetch()` are thread safe.
  68
  69 ------
  70 RETURN
  71 ------
  72
  73 :c:func:`memcached_pool_destroy()` returns the pointer (and ownership) to the :c:type:`memcached_st` structure used to create the pool. If connections are in use it returns NULL.
  74
  75 :c:func:`memcached_pool_pop()` returns a pointer to a :c:type:`memcached_st` structure from the pool (or NULL if an allocation cannot be satisfied).
  76
  77 :c:func:`memcached_pool_release()` returns :c:type:`MEMCACHED_SUCCESS` upon success.
  78
  79 :c:func:`memcached_pool_behavior_get()` and :c:func:`memcached_pool_behavior_get()` returns :c:type:`MEMCACHED_SUCCESS` upon success.
  80
  81 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.
  82
  83 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.
  84
  85
  86 ----
  87 HOME
  88 ----
  89
  90
  91 To find out more information please check:
  92 `http://libmemcached.org/ <http://libmemcached.org/>`_
  93
  94
  95 ------
  96 AUTHOR
  97 ------
  98
  99
 100 Brian Aker, <brian@tangent.org>
 101
 102 Trond Norbye, <trond.norbye@gmail.com>
 103
 104
 105 --------
 106 SEE ALSO
 107 --------
 108
 109 :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` :manpage:`libmemcached_configuration(3)`