X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fsource%2Flibmemcached%2Fmemcached_callback.rst;h=af89b1744ba7555164805bb3a7700bbe1952d776;hb=f875d401486e0e12d30b28e9d62220fdf6cd8561;hp=e0158f6f888f34320b4031847a54008b87d116da;hpb=e1833e25ab4a98f9a3f9f9268185af57b2280eaf;p=awesomized%2Flibmemcached diff --git a/docs/source/libmemcached/memcached_callback.rst b/docs/source/libmemcached/memcached_callback.rst index e0158f6f..af89b174 100644 --- a/docs/source/libmemcached/memcached_callback.rst +++ b/docs/source/libmemcached/memcached_callback.rst @@ -1,10 +1,6 @@ -Setting callbacks +Library callbacks ================= -Get and set a callback - -.. index:: object: memcached_st - SYNOPSIS -------- @@ -12,73 +8,94 @@ SYNOPSIS Compile and link with -lmemcached .. function:: memcached_return_t memcached_callback_set(memcached_st *ptr, memcached_callback_t flag, const void *data) - + + :param ptr: pointer to initialized `memcached_st` struct + :param flag: `memcached_callback_t` flag to set + :param data: data corresponding to `flag` + :returns: `memcached_return_t` indicating success + .. function:: void *memcached_callback_get(memcached_st *ptr, memcached_callback_t flag, memcached_return_t *error) + :param ptr: pointer to initialized `memcached_st` struct + :param flag: `memcached_callback_t` flag to query + :param error: pointer to `memcached_return_t` indicating success + :returns: the `data` previously set + .. c:type:: enum memcached_callback_t memcached_callback_t .. enum:: memcached_callback_t .. enumerator:: MEMCACHED_CALLBACK_CLEANUP_FUNCTION - When :func:`memcached_delete` is called this function will be executed. At - the point of its execution all connections are closed. + When `memcached_free` or `memcached_reset` is called this function + will be executed. At the point of its execution all connections are closed. + + Its signature is: + + .. type:: memcached_return_t (*memcached_cleanup_fn)(const memcached_st *ptr) + .. enumerator:: MEMCACHED_CALLBACK_CLONE_FUNCTION - When :func:`memcached_delete` is called this function will be executed. - At the point of its execution all connections are closed. + When `memcached_clone` is called this function will be executed. + + Its signature is: + + .. type:: memcached_return_t (*memcached_clone_fn)(memcached_st *destination, const memcached_st *source) .. enumerator:: MEMCACHED_CALLBACK_PREFIX_KEY - See `MEMCACHED_CALLBACK_NAMESPACE` + See `MEMCACHED_CALLBACK_NAMESPACE`. .. enumerator:: MEMCACHED_CALLBACK_NAMESPACE You can set a value which will be used to create a domain for your keys. - The value specified here will be prefixed to each of your keys. The value can - not be greater then `MEMCACHED_PREFIX_KEY_MAX_SIZE` - 1 and will - reduce `MEMCACHED_MAX_KEY` by the value of your key. + The value specified here will be prefixed to each of your keys. The + value can not be greater then :c:macro:`MEMCACHED_MAX_NAMESPACE` - 1 and + will reduce :c:macro:`MEMCACHED_MAX_KEY` by the value of your key. The prefix key is only applied to the primary key, not the master key. - `MEMCACHED_FAILURE` will be returned if no key is set. In the case of - a key which is too long, `MEMCACHED_BAD_KEY_PROVIDED` will be returned. + `MEMCACHED_FAILURE` will be returned if no key is set. In the case of a + key which is too long, `MEMCACHED_BAD_KEY_PROVIDED` will be returned. - If you set a value with the value being NULL then the prefix key is disabled. + If you set a value with the value being NULL then the prefix key is + disabled. .. enumerator:: MEMCACHED_CALLBACK_USER_DATA - This allows you to store a pointer to a specific piece of data. This can be - retrieved from inside of :func:`memcached_fetch_execute`. Cloning a - :type:`memcached_st` will copy the pointer to the clone. + This allows you to store a pointer to a specific piece of data. This can + be retrieved from inside of `memcached_fetch_execute`. Cloning a + `memcached_st` will copy the pointer to the clone. .. enumerator:: MEMCACHED_CALLBACK_MALLOC_FUNCTION .. deprecated:: <0.32 - Use :type:`memcached_set_memory_allocators` instead. + Use `memcached_set_memory_allocators` instead. .. enumerator:: MEMCACHED_CALLBACK_REALLOC_FUNCTION .. deprecated:: <0.32 - Use :type:`memcached_set_memory_allocators` instead. + Use `memcached_set_memory_allocators` instead. .. enumerator:: MEMCACHED_CALLBACK_FREE_FUNCTION .. deprecated:: <0.32 - Use :type:`memcached_set_memory_allocators` instead. + Use `memcached_set_memory_allocators` instead. .. enumerator:: MEMCACHED_CALLBACK_GET_FAILURE - This function implements the read through cache behavior. On failure of retrieval this callback will be called. - - 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. - - You must clone the :type:`memcached_st` in order to - make use of it. The value will be stored only if you return - `MEMCACHED_SUCCESS` or `MEMCACHED_BUFFERED`. Returning - `MEMCACHED_BUFFERED` will cause the object to be buffered and not sent - immediately (if this is the default behavior based on your connection setup - this will happen automatically). + This function implements the read through cache behavior. On failure of + retrieval this callback will be called. + + 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. + + You must clone the `memcached_st` in order to make use of it. The value + will be stored only if you return `MEMCACHED_SUCCESS` or + `MEMCACHED_BUFFERED`. Returning `MEMCACHED_BUFFERED` will cause the + object to be buffered and not sent immediately (if this is the default + behavior based on your connection setup this will happen automatically). The prototype for this is: @@ -86,7 +103,9 @@ SYNOPSIS .. enumerator:: MEMCACHED_CALLBACK_DELETE_TRIGGER - 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. + 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. The prototype for this is: @@ -95,32 +114,40 @@ SYNOPSIS DESCRIPTION ----------- -`libmemcached` can have callbacks set key execution points. These either -provide function calls at points in the code, or return pointers to -structures for particular usages. +`libmemcached` can have callbacks set key execution points. These either provide +function calls at points in the code, or return pointers to structures for +particular usages. -:func:`memcached_callback_get` takes a callback flag and returns the -structure or function set by :func:`memcached_callback_set`. +`memcached_callback_get` takes a callback flag and returns the structure or +function set by `memcached_callback_set`. -:func:`memcached_callback_set` changes the function/structure assigned by a -callback flag. No connections are reset. +`memcached_callback_set` changes the function/structure assigned by a callback +flag. No connections are reset. -You can use `MEMCACHED_CALLBACK_USER_DATA` to provide custom context -if required for any of the callbacks. +You can use `MEMCACHED_CALLBACK_USER_DATA` to provide custom context if required +for any of the callbacks. RETURN VALUE ------------ -:func:`memcached_callback_get` return the function or structure that was -provided. Upon error, nothing is set, null is returned, and the -:type:`memcached_return_t` argument is set to `MEMCACHED_FAILURE`. +`memcached_callback_get` returns the function or structure that was provided. +Upon error, nothing is set, NULL is returned, and the `memcached_return_t` +argument is set to `MEMCACHED_FAILURE`. -:func:`memcached_callback_set` returns `MEMCACHED_SUCCESS` upon -successful setting, otherwise `MEMCACHED_FAILURE` on error. +`memcached_callback_set` returns `MEMCACHED_SUCCESS` upon successful setting, +otherwise `MEMCACHED_FAILURE` on error. SEE ALSO -------- .. only:: man - :manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)` + :manpage:`memcached(1)` + :manpage:`libmemcached(3)` + :manpage:`memcached_strerror(3)` + +.. only:: html + + * :manpage:`memcached(1)` + * :doc:`../libmemcached` + * :doc:`memcached_strerror`