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

   1 Creating and destroying a memcached_st
   2 ======================================
   3
   4 SYNOPSIS
   5 --------
   6
   7 #include <libmemcached/memcached.h>
   8   Compile and link with -lmemcached
   9
  10 .. type:: struct memcached_st memcached_st
  11
  12 .. function:: memcached_st* memcached_create(memcached_st *ptr)
  13
  14     :param ptr: pointer to user-allocated `memcached_st` struct or null pointer
  15     :returns: pointer to initialized `memcached_st` struct
  16
  17 .. function:: void memcached_free(memcached_st *ptr)
  18
  19     :param ptr: pointer to initialized `memcached_st` struct to destroy and possibly free
  20
  21 .. function:: memcached_st* memcached_clone(memcached_st *destination, memcached_st *source)
  22
  23     :param destination: pointer to user-allocated `memcached_st` struct or null pointer
  24     :param source: pointer to initialized `memcached_st` struct to copy from
  25     :returns: pointer to newly initialized `destination`, copied from `source`
  26
  27 .. function:: void memcached_servers_reset(memcached_st *ptr)
  28
  29     :param ptr: pointer to initialized `memcached_st` struct
  30
  31 DESCRIPTION
  32 -----------
  33
  34 `memcached_create` is used to create a `memcached_st` structure that will then
  35 be used by other `libmemcached` functions to communicate with the server. You
  36 should either pass a statically declared `memcached_st` to `memcached_create` or
  37 a NULL. If a NULL passed in then a structure is allocated for you.
  38
  39 Please note, when you write new application use `memcached` over
  40 `memcached_create`.
  41
  42 `memcached_clone` is similar to `memcached_create` but it copies the defaults
  43 and list of servers from the source `memcached_st` pointer. If you pass a null
  44 as the argument for the source to clone, it is the same as a call to
  45 `memcached_create`. If the destination argument is NULL a `memcached_st` will be
  46 allocated for you.
  47
  48 `memcached_servers_reset` allows you to zero out the list of servers that the
  49 `memcached_st` has.
  50
  51 To clean up memory associated with a `memcached_st` structure you should pass it
  52 to `memcached_free` when you are finished using it. `memcached_free` is the only
  53 way to make sure all memory is deallocated when you finish using the structure.
  54
  55 You may wish to avoid using `memcached_create` or `memcached_clone` with a stack
  56 based allocation. The most common issues related to ABI safety involve heap
  57 allocated structures.
  58
  59 RETURN VALUE
  60 ------------
  61
  62 `memcached_create` returns a pointer to the `memcached_st` that was created (or
  63 initialized). On an allocation failure, it returns NULL.
  64
  65 `memcached_clone` returns a pointer to the `memcached_st` that was created (or
  66 initialized). On an allocation failure, it returns NULL.
  67
  68 SEE ALSO
  69 --------
  70
  71 .. only:: man
  72
  73     :manpage:`memcached(1)`
  74     :manpage:`libmemcached(3)`
  75
  76 .. only:: html
  77
  78     * :manpage:`memcached(1)`
  79     * :doc:`../libmemcached`