Fix for building docs.

[awesomized/libmemcached] / docs / source / memcached_memory_allocators.rst

diff --git a/docs/source/memcached_memory_allocators.rst b/docs/source/memcached_memory_allocators.rst
new file mode 100644 (file)
index 0000000..12a4ce5
--- /dev/null
+++ b/docs/source/memcached_memory_allocators.rst
@@ -0,0 +1,93 @@
+========================================
+Use custom allocators for embedded usage
+========================================
+
+.. index:: object: memcached_st
+
+Manage memory allocator functions
+
+--------
+SYNOPSIS
+--------
+
+
+#include <libmemcached/memcached.h>
+
+.. c:function:: memcached_return_t memcached_set_memory_allocators (memcached_st *ptr, memcached_malloc_fn mem_malloc, memcached_free_fn mem_free, memcached_realloc_fn mem_realloc, memcached_calloc_fn mem_calloc, void *context)
+
+.. c:function:: void memcached_get_memory_allocators (memcached_st *ptr, memcached_malloc_fn *mem_malloc, memcached_free_fn *mem_free, memcached_realloc_fn *mem_realloc, memcached_calloc_fn *mem_calloc)
+
+.. c:function:: void * memcached_get_memory_allocators_context(const memcached_st *ptr)
+
+.. c:function:: void * (*memcached_malloc_fn) (memcached_st *ptr, const size_t size, void *context)
+
+.. c:function:: void * (*memcached_realloc_fn) (memcached_st *ptr, void *mem, const size_t size, void *context)
+
+.. c:function:: void (*memcached_free_fn) (memcached_st *ptr, void *mem, void *context)
+
+.. c:function:: void * (*memcached_calloc_fn) (memcached_st *ptr, size_t nelem, const size_t elsize, void *context)
+
+Compile and link with -lmemcached
+
+
+
+-----------
+DESCRIPTION
+-----------
+
+
+libmemcached(3) allows you to specify your own memory allocators, optimized
+for your application. This enables libmemcached to be used inside of applications that have their own malloc implementation.
+
+:c:func:`memcached_set_memory_allocators` is used to set the memory 
+allocators used by the memcached instance specified by ptr. Please note that 
+you cannot override only one of the memory allocators, you have to specify a 
+complete new set if you want to override one of them. All of the memory 
+allocation functions should behave as specified in the C99 standard. Specify 
+NULL as all functions to reset them to the default values.
+
+:c:func:`memcached_get_memory_allocators` is used to get the currently used 
+memory allocators by a mamcached handle.
+
+:c:func:`memcached_get_memory_allocators_context` returns the void \* that 
+was passed in during the call to :c:func:`memcached_set_memory_allocators`.
+
+The first argument to the memory allocator functions is a pointer to a
+memcached structure, the is passed as const and you will need to clone
+it in order to make use of any operation which would modify it.
+
+
+-----
+NOTES
+-----
+
+
+In version 0.38 all functions were modified to have a context void pointer
+passed to them. This was so that customer allocators could have their
+own space for memory.
+
+
+------
+RETURN
+------
+
+
+:c:func:`memcached_set_memory_allocators` return :c:type:`MEMCACHED_SUCCESS` 
+upon success, and :c:type:`MEMCACHED_FAILURE` if you don't pass a complete set 
+of function pointers.
+
+
+----
+HOME
+----
+
+
+To find out more information please check:
+`http://libmemcached.org/ <http://libmemcached.org/>`_
+
+
+--------
+SEE ALSO
+--------
+
+:manpage:`memcached(1)` :manpage:`libmemcached(3)` :manpage:`memcached_strerror(3)`