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