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

   1 Setting callbacks
   2 =================
   3
   4 Get and set a callback
   5
   6 .. index:: object: memcached_st
   7
   8 SYNOPSIS
   9 --------
  10
  11 #include <libmemcached/memcached.h>
  12   Compile and link with -lmemcached
  13
  14 .. function:: memcached_return_t memcached_callback_set(memcached_st *ptr, memcached_callback_t flag, const void *data)
  15
  16 .. function:: void *memcached_callback_get(memcached_st *ptr, memcached_callback_t flag, memcached_return_t *error)
  17
  18 .. c:type:: enum memcached_callback_t memcached_callback_t
  19
  20 .. enum:: memcached_callback_t
  21
  22     .. enumerator:: MEMCACHED_CALLBACK_CLEANUP_FUNCTION
  23
  24         When :func:`memcached_delete` is called this function will be executed. At
  25         the point of its execution all connections are closed.
  26
  27     .. enumerator:: MEMCACHED_CALLBACK_CLONE_FUNCTION
  28
  29         When :func:`memcached_delete` is called this function will be executed.
  30         At the point of its execution all connections are closed.
  31
  32     .. enumerator:: MEMCACHED_CALLBACK_PREFIX_KEY
  33
  34         See `MEMCACHED_CALLBACK_NAMESPACE`
  35
  36     .. enumerator:: MEMCACHED_CALLBACK_NAMESPACE
  37
  38         You can set a value which will be used to create a domain for your keys.
  39         The value specified here will be prefixed to each of your keys. The value can
  40         not be greater then `MEMCACHED_PREFIX_KEY_MAX_SIZE` - 1 and will
  41         reduce `MEMCACHED_MAX_KEY` by the value of your key.
  42
  43         The prefix key is only applied to the primary key, not the master key.
  44         `MEMCACHED_FAILURE` will be returned if no key is set. In the case of
  45         a key which is too long, `MEMCACHED_BAD_KEY_PROVIDED` will be returned.
  46
  47         If you set a value with the value being NULL then the prefix key is disabled.
  48
  49     .. enumerator:: MEMCACHED_CALLBACK_USER_DATA
  50
  51         This allows you to store a pointer to a specific piece of data. This can be
  52         retrieved from inside of :func:`memcached_fetch_execute`. Cloning a
  53         :type:`memcached_st` will copy the pointer to the clone.
  54
  55     .. enumerator:: MEMCACHED_CALLBACK_MALLOC_FUNCTION
  56
  57         .. deprecated:: <0.32
  58            Use :type:`memcached_set_memory_allocators` instead.
  59
  60     .. enumerator:: MEMCACHED_CALLBACK_REALLOC_FUNCTION
  61
  62         .. deprecated:: <0.32
  63            Use :type:`memcached_set_memory_allocators` instead.
  64
  65     .. enumerator:: MEMCACHED_CALLBACK_FREE_FUNCTION
  66
  67         .. deprecated:: <0.32
  68            Use :type:`memcached_set_memory_allocators` instead.
  69
  70     .. enumerator:: MEMCACHED_CALLBACK_GET_FAILURE
  71
  72         This function implements the read through cache behavior. On failure of retrieval this callback will be called.
  73
  74         You are responsible for populating the result object provided. This result object will then be stored in the server and returned to the calling process.
  75
  76         You must clone the :type:`memcached_st` in order to
  77         make use of it. The value will be stored only if you return
  78         `MEMCACHED_SUCCESS` or `MEMCACHED_BUFFERED`. Returning
  79         `MEMCACHED_BUFFERED` will cause the object to be buffered and not sent
  80         immediately (if this is the default behavior based on your connection setup
  81         this will happen automatically).
  82
  83         The prototype for this is:
  84
  85         .. type:: memcached_return_t (*memcached_trigger_key)(memcached_st *ptr, char *key, size_t key_length, memcached_result_st *result)
  86
  87     .. enumerator:: MEMCACHED_CALLBACK_DELETE_TRIGGER
  88
  89         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.
  90
  91         The prototype for this is:
  92
  93         .. type:: memcached_return_t (*memcached_trigger_delete_key)(memcached_st *ptr, char *key, size_t key_length)
  94
  95 DESCRIPTION
  96 -----------
  97
  98 `libmemcached` can have callbacks set key execution points. These either
  99 provide function calls at points in the code, or return pointers to
 100 structures for particular usages.
 101
 102 :func:`memcached_callback_get` takes a callback flag and returns the
 103 structure or function set by :func:`memcached_callback_set`.
 104
 105 :func:`memcached_callback_set` changes the function/structure assigned by a
 106 callback flag. No connections are reset.
 107
 108 You can use `MEMCACHED_CALLBACK_USER_DATA` to provide custom context
 109 if required for any of the callbacks.
 110
 111 RETURN VALUE
 112 ------------
 113
 114 :func:`memcached_callback_get` return the function or structure that was
 115 provided. Upon error, nothing is set, null is returned, and the
 116 :type:`memcached_return_t` argument is set to `MEMCACHED_FAILURE`.
 117
 118 :func:`memcached_callback_set` returns `MEMCACHED_SUCCESS` upon
 119 successful setting, otherwise `MEMCACHED_FAILURE` on error.
 120
 121 SEE ALSO
 122 --------
 123
 124 .. only:: man
 125
 126   :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`