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

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