This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH] manual: memory: document support custom allocators
- From: ricaljasan <ricaljasan at pacific dot net>
- To: Mike Frysinger <vapier at gentoo dot org>
- Cc: libc-alpha at sourceware dot org
- Date: Sun, 14 Feb 2016 12:17:58 -0800
- Subject: Re: [PATCH] manual: memory: document support custom allocators
- Authentication-results: sourceware.org; auth=none
- References: <1455331567-12658-1-git-send-email-vapier at gentoo dot org>
On 02/12/2016 06:46 PM, Mike Frysinger wrote:
> 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.
+implementation, @pxref{Custom Allocators}.
That won't render correctly across all documentation types.
> +
> @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.
+implementation, @pxref{Custom Allocators}.
> +
> @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.
+implementation, @pxref{Custom Allocators}.
> +
> @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.
+implementation, @pxref{Custom Allocators}.
>
> @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}
+provide their own replacement---you can write your own @code{malloc}
I don't think Latin abbreviations should start a sentence. "Want" also
colors the subordinate clause in an odd way; I think "can" is more in
keeping with the intent.
> +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
+might not internally call the others. For example, @code{calloc} might
not call
Alternate strategy for avoiding the abbreviation.
> +@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
+All other memory functions @theglibc{} provides will utilize the
Not an adjective here. "That" is unnecessary.
> +ones listed above. You may replace them, but the @glibcadj{} will not call
+ones listed above. You may replace them, but @theglibc{} will not call
Same.
> +them directly, only through the aforementioned list.
>
> @ignore
> @c This was never actually implemented. -zw
>
My 2ï.
Rical