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

   1 =head1 NAME
   2
   3 memcached_pool_create, memcached_pool_destroy, memcached_pool_push, memcached_pool_pop - Manage pools
   4
   5 =head1 LIBRARY
   6
   7 C Client Library for memcached (libmemcachedutil, -lmemcachedutil)
   8
   9 =head1 SYNOPSIS
  10
  11   #include <libmemcached/memcached_pool.h>
  12
  13   memcached_pool_st *memcached_pool_create(memcached_st* mmc, int initial, int max);
  14   memcached_st* memcached_pool_destroy(memcached_pool_st* pool);
  15
  16   memcached_st* memcached_pool_pop(memcached_pool_st* pool, bool block, memcached_return *rc);
  17   memcached_return memcached_pool_push(memcached_pool_st* pool, memcached_st *mmc);
  18
  19   memcached_st *memcached_create (memcached_st *ptr);
  20
  21
  22 =head1 DESCRIPTION
  23
  24 memcached_pool_create() is used to create a connection pool of objects you
  25 may use to remove the overhead of using memcached_clone for short
  26 lived C<memcached_st> objects. The mmc argument should be an
  27 initialised C<memcached_st> structure, and a successfull invocation of
  28 memcached_pool_create takes full ownership of the variable (until it
  29 is released by memcached_pool_destroy). The C<initial> argument
  30 specifies the initial size of the connection pool, and the C<max>
  31 argument specifies the maximum size the connection pool should grow
  32 to. Please note that the library will allocate a fixed size buffer
  33 scaled to the max size of the connection pool, so you should not pass
  34 MAXINT or some other large number here.
  35
  36 memcached_pool_destroy() is used to destroy the connection pool
  37 created with memcached_pool_create() and release all allocated
  38 resources. It will return the pointer to the C<memcached_st> structure
  39 passed as an argument to memcached_pool_create(), and returns the
  40 ownership of the pointer to the caller.
  41
  42 memcached_pool_pop() is used to grab a connection structure from the
  43 connection pool. The block argument specifies if the function should
  44 block and wait for a connection structure to be available if we try
  45 to exceed the maximum size.
  46
  47 memcached_pool_push() is used to return a connection structure back to the pool.
  48
  49 =head1 RETURN
  50
  51 memcached_pool_create() returns a pointer to the newly created
  52 memcached_pool_st structure. On an allocation failure, it returns
  53 NULL.
  54
  55 memcached_pool_destroy() returns the pointer (and ownership) to the
  56 memcached_st structure used to create the pool. If connections are in
  57 use it returns NULL.
  58
  59 memcached_pool_pop() returns a pointer to a memcached_st structure
  60 from the pool (or NULL if an allocation cannot be satisfied).
  61
  62 memcached_pool_push() returns MEMCACHED_SUCCESS upon success.
  63
  64 =head1 HOME
  65
  66 To find out more information please check:
  67 L<http://tangent.org/552/libmemcached.html>
  68
  69 =head1 AUTHOR
  70
  71 Trond Norbye, E<lt>trond.norbye@sun.comE<gt>
  72
  73 =head1 SEE ALSO
  74
  75 memcached(1) libmemcached(3) memcached_create(3) memcached_free(3) libmemcachedutil(3)
  76
  77 =cut