From patchwork Sat Feb 13 02:46:07 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Frysinger X-Patchwork-Id: 10849 X-Patchwork-Delegate: vapier@gentoo.org Received: (qmail 49318 invoked by alias); 13 Feb 2016 02:46:21 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 49272 invoked by uid 89); 13 Feb 2016 02:46:12 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.0 required=5.0 tests=BAYES_00, RP_MATCHES_RCVD, SPF_PASS autolearn=ham version=3.3.2 spammy=Pages, considerations, subsection, @subsection X-HELO: smtp.gentoo.org From: Mike Frysinger To: libc-alpha@sourceware.org Subject: [PATCH] manual: memory: document support custom allocators Date: Fri, 12 Feb 2016 21:46:07 -0500 Message-Id: <1455331567-12658-1-git-send-email-vapier@gentoo.org> While glibc has long officially supported replacing things like malloc, it hasn't really been documented. The calloc section happens to have a small aside, but doesn't provide enough info. Create a new section that explicitly lays out what is supported. --- manual/memory.texi | 47 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/manual/memory.texi b/manual/memory.texi index 700555e..e1426f1 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -18,6 +18,7 @@ and allocation of real memory. * Memory Allocation:: Allocating storage for your program data * Resizing the Data Segment:: @code{brk}, @code{sbrk} * Locking Pages:: Preventing page faults +* Custom Allocators:: Using different memory allocators at runtime @end menu Memory mapped I/O is not discussed in this chapter. @xref{Memory-mapped I/O}. @@ -577,6 +578,9 @@ ptr = (char *) malloc (length + 1); @noindent @xref{Representation of Strings}, for more information about this. +If you wish to replace the @code{malloc} function with your own +implementation, be sure to read the @ref{Custom Allocators} section. + @node Malloc Examples @subsubsection Examples of @code{malloc} @@ -707,6 +711,9 @@ There is no point in freeing blocks at the end of a program, because all of the program's space is given back to the system when the process terminates. +If you wish to replace the @code{free} function with your own +implementation, be sure to read the @ref{Custom Allocators} section. + @node Changing Block Size @subsubsection Changing the Size of a Block @cindex changing the size of a block (@code{malloc}) @@ -815,6 +822,9 @@ necessitates copying it, so it can fail if no other space is available. If the new size you specify is the same as the old size, @code{realloc} is guaranteed to change nothing and return the same address that you gave. +If you wish to replace the @code{realloc} function with your own +implementation, be sure to read the @ref{Custom Allocators} section. + @node Allocating Cleared Space @subsubsection Allocating Cleared Space @@ -862,10 +872,8 @@ calloc (size_t count, size_t eltsize) @} @end smallexample -But in general, it is not guaranteed that @code{calloc} calls -@code{malloc} internally. Therefore, if an application provides its own -@code{malloc}/@code{realloc}/@code{free} outside the C library, it -should always define @code{calloc}, too. +If you wish to replace the @code{calloc} function with your own +implementation, be sure to read the @ref{Custom Allocators} section. @node Efficiency and Malloc @subsubsection Efficiency Considerations for @code{malloc} @@ -3280,8 +3288,39 @@ calls can fail, so there are no specific @code{errno} values. @end deftypefun +@node Custom Allocators +@section Custom Allocators +The @glibcadj{} memory allocator is designed to allow implementations to +provide their own replacement. I.e. You want to write your own @code{malloc} +function or use a library like tcmalloc or jemalloc, and all @glibcadj{} code +will call into this for memory requests. However, care must be taken to make +this work correctly. + +@menu +* Function Replacements:: List of functions that must be implemented +@end menu + +@node Function Replacements +@subsection API for custom allocators + +Your replacement must implement all of these functions. If you omit any of +them, correct behavior cannot be guaranteed. This is because some functions +might not internally call the others. E.g. @code{calloc} might not call +@code{malloc}, so passing the returned pointer to @code{free} can confuse the +allocator. + +@itemize @bullet +@item @code{malloc} @xref{Basic Allocation} +@item @code{free} @xref{Freeing after Malloc} +@item @code{realloc} @xref{Changing Block Size} +@item @code{calloc} @xref{Allocating Cleared Space} +@item @code{memalign} @xref{Aligned Memory Blocks} +@end itemize +All other memory functions that the @glibcadj{} provides will utilize the +ones listed above. You may replace them, but the @glibcadj{} will not call +them directly, only through the aforementioned list. @ignore @c This was never actually implemented. -zw