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

   1 =================
   2 Setting callbacks
   3 =================
   4
   5
   6 Get and set a callback
   7
   8
   9 -------
  10 LIBRARY
  11 -------
  12
  13
  14 C Client Library for memcached (libmemcached, -lmemcached)
  15
  16
  17 --------
  18 SYNOPSIS
  19 --------
  20
  21 #include <libmemcached/memcached.h>
  22
  23 .. c:function:: memcached_return_t memcached_callback_set (memcached_st *ptr, memcached_callback_t flag, void *data);
  24
  25 .. c:function:: void * memcached_callback_get (memcached_st *ptr, memcached_callback_t flag, memcached_return_t *error);
  26
  27
  28
  29 -----------
  30 DESCRIPTION
  31 -----------
  32
  33
  34 libmemcached(3) can have callbacks set key execution points. These either
  35 provide function calls at points in the code, or return pointers to
  36 structures for particular usages.
  37
  38 memcached_callback_get() takes a callback flag and returns the structure or
  39 function set by memcached_callback_set().
  40
  41 memcached_callback_set() changes the function/structure assigned by a
  42 callback flag. No connections are reset.
  43
  44 You can use MEMCACHED_CALLBACK_USER_DATA to provide custom context if required for any
  45 of the callbacks
  46
  47
  48 .. c:var:: MEMCACHED_CALLBACK_CLEANUP_FUNCTION
  49
  50  When memcached_delete() is called this function will be excuted. At the
  51  point of its execution all connections have been closed.
  52
  53
  54
  55 .. c:var:: MEMCACHED_CALLBACK_CLONE_FUNCTION
  56
  57  When memcached_delete() is called this function will be excuted. At the
  58  point of its execution all connections have been closed.
  59
  60
  61
  62 .. c:var:: MEMCACHED_CALLBACK_PREFIX_KEY
  63
  64  You can set a value which will be used to create a domain for your keys.
  65  The value specified here will be prefixed to each of your keys. The value can not
  66  be greater then MEMCACHED_PREFIX_KEY_MAX_SIZE - 1 and will reduce MEMCACHED_MAX_KEY by
  67  the value of your key. The prefix key is only applied to the primary key,
  68  not the master key. MEMCACHED_FAILURE will be returned if no key is set. In the case
  69  of a key which is too long MEMCACHED_BAD_KEY_PROVIDED will be returned.
  70
  71  If you set a value with the value being NULL then the prefix key is disabled.
  72
  73
  74 .. c:var:: MEMCACHED_CALLBACK_USER_DATA
  75
  76  This allows you to store a pointer to a specifc piece of data. This can be
  77  retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st
  78  will copy the pointer to the clone.
  79
  80
  81
  82 .. c:var:: MEMCACHED_CALLBACK_MALLOC_FUNCTION
  83
  84  DEPRECATED: use memcached_set_memory_allocators instead.
  85
  86
  87
  88 .. c:var:: MEMCACHED_CALLBACK_REALLOC_FUNCTION
  89
  90  DEPRECATED: use memcached_set_memory_allocators instead.
  91
  92
  93
  94 .. c:var:: MEMCACHED_CALLBACK_FREE_FUNCTION
  95
  96  DEPRECATED: use memcached_set_memory_allocators instead.
  97
  98
  99
 100 .. c:var:: MEMCACHED_CALLBACK_GET_FAILURE
 101
 102  This function implements the read through cache behavior. On failure of retrieval this callback will be called.
 103  You are responsible for populating the result object provided. This result object will then be stored in the server and
 104  returned to the calling process. You must clone the memcached_st in order to
 105  make use of it. The value will be stored only if you return
 106  MEMCACHED_SUCCESS or MEMCACHED_BUFFERED. Returning MEMCACHED_BUFFERED will
 107  cause the object to be buffered and not sent immediatly (if this is the default behavior based on your connection setup this will happen automatically).
 108
 109  The prototype for this is:
 110  memcached_return_t (\*memcached_trigger_key)(memcached_st \*ptr, char \*key, size_t key_length, memcached_result_st \*result);
 111
 112
 113
 114 .. c:var:: MEMCACHED_CALLBACK_DELETE_TRIGGER
 115
 116 This function implements a trigger upon successful deletion of a key. The memcached_st structure will need to be cloned in order to make use of it.
 117
 118 The prototype for this is: typedef memcached_return_t (\*memcached_trigger_delete_key)(memcached_st \*ptr, char \*key, size_t key_length);
 119
 120
 121
 122
 123 ------
 124 RETURN
 125 ------
 126
 127
 128 memcached_callback_get() return the function or structure that was provided.
 129 Upon error, nothing is set, null is returned, and the memcached_return_t
 130 argument is set to MEMCACHED_FAILURE.
 131
 132 memcached_callback_set() returns MEMCACHED_SUCCESS upon successful setting,
 133 otherwise MEMCACHED_FAILURE on error.
 134
 135
 136 ----
 137 HOME
 138 ----
 139
 140
 141 To find out more information please check:
 142 `http://libmemcached.org/ <http://libmemcached.org/>`_
 143
 144
 145 ------
 146 AUTHOR
 147 ------
 148
 149
 150 Brian Aker, <brian@tangent.org>
 151
 152
 153 --------
 154 SEE ALSO
 155 --------
 156
 157
 158 :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`