core: add ability to customize memory allocator

This patch is composed by the work done in
https://github.com/libuv/libuv/pull/231 and
https://github.com/libuv/libuv/pull/287 plus some changes by yours
truly.

Thanks @beevik and @mattsta for their work on this!

PR-URL: https://github.com/libuv/libuv/pull/368
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/src/misc.rst b/docs/src/misc.rst
index 54681f70..fb5a8a40 100644
--- a/docs/src/misc.rst
+++ b/docs/src/misc.rst
@@ -26,6 +26,26 @@ Data types
         .. note::
             On Windows this field is ULONG.
 
+.. c:type:: void* (*uv_malloc_func)(size_t size)
+
+        Replacement function for :man:`malloc(3)`.
+        See :c:func:`uv_replace_allocator`.
+
+.. c:type::  void* (*uv_realloc_func)(void* ptr, size_t size)
+
+        Replacement function for :man:`realloc(3)`.
+        See :c:func:`uv_replace_allocator`.
+
+.. c:type::  void* (*uv_calloc_func)(size_t count, size_t size)
+
+        Replacement function for :man:`calloc(3)`.
+        See :c:func:`uv_replace_allocator`.
+
+.. c:type:: void (*uv_free_func)(void* ptr)
+
+        Replacement function for :man:`free(3)`.
+        See :c:func:`uv_replace_allocator`.
+
 .. c:type:: uv_file
 
     Cross platform representation of a file handle.
@@ -126,6 +146,26 @@ API
     Returns the libuv version number as a string. For non-release versions
     "-pre" is appended, so the version number could be "1.2.3-pre".
 
+.. c:function:: int uv_replace_allocator(uv_malloc_func malloc_func, uv_realloc_func realloc_func, uv_calloc_func calloc_func, uv_free_func free_func)
+
+    .. versionadded:: 1.6.0
+
+    Override the use of the standard library's :man:`malloc(3)`,
+    :man:`calloc(3)`, :man:`realloc(3)`, :man:`free(3)`, memory allocation
+    functions.
+
+    This function must be called before any other libuv function is called or
+    after all resources have been freed and thus libuv doesn't reference
+    any allocated memory chunk.
+
+    On success, it returns 0, if any of the function pointers is NULL it
+    returns UV_EINVAL.
+
+    .. warning:: There is no protection against changing the allocator multiple
+                 times. If the user changes it they are responsible for making
+                 sure the allocator is changed while no memory was allocated with
+                 the previous allocator, or that they are compatible.
+
 .. c:function:: uv_buf_t uv_buf_init(char* base, unsigned int len)
 
     Constructor for :c:type:`uv_buf_t`.