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