[v3,2/2] manual/memory.texi: Document aligned_alloc.

Message ID 529470C6.6040809@linaro.org
State Accepted
Headers show

Commit Message

Will Newton Nov. 26, 2013, 9:58 a.m.
ChangeLog:

2013-11-06  Will Newton  <will.newton@linaro.org>

	* manual/memory.texi (Malloc Examples): Mention aligned_alloc.
	(Aligned Memory Blocks): Add documentation for aligned_alloc
	and suggest it as an alternative to posix_memalign.
	(Hooks for Malloc): Document __memalign_hook is also called
	for aligned_alloc.  (Summary of Malloc): Add summary for
	aligned alloc.  Document __memalign_hook is also called
	for aligned_alloc.
---
 manual/memory.texi | 63 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 47 insertions(+), 16 deletions(-)

Changes in v3:
 - Improve documentation of posix_memalign versus aligned_alloc based on review feedback

Comments

Paul Eggert Nov. 26, 2013, 8:52 p.m. | #1
Thanks, these two look good.
Ondřej Bílka Dec. 3, 2013, 3:30 p.m. | #2
On Tue, Nov 26, 2013 at 09:58:30AM +0000, Will Newton wrote:
> 
> ChangeLog:
> 
> 2013-11-06  Will Newton  <will.newton@linaro.org>
> 
> 	* manual/memory.texi (Malloc Examples): Mention aligned_alloc.
> 	(Aligned Memory Blocks): Add documentation for aligned_alloc
> 	and suggest it as an alternative to posix_memalign.
> 	(Hooks for Malloc): Document __memalign_hook is also called
> 	for aligned_alloc.  (Summary of Malloc): Add summary for
> 	aligned alloc.  Document __memalign_hook is also called
> 	for aligned_alloc.
> ---
>  manual/memory.texi | 63 ++++++++++++++++++++++++++++++++++++++++--------------
>  1 file changed, 47 insertions(+), 16 deletions(-)
> 
looks ok, first patch was already reviewed.
Will Newton Dec. 16, 2013, 2:53 p.m. | #3
On 26 November 2013 20:52, Paul Eggert <eggert@cs.ucla.edu> wrote:
> Thanks, these two look good.

I have now applied these patches.

Patch

diff --git a/manual/memory.texi b/manual/memory.texi
index 3d96f35..55a6a50 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -382,8 +382,8 @@  The block that @code{malloc} gives you is guaranteed to be aligned so
 that it can hold any type of data.  On @gnusystems{}, the address is
 always a multiple of eight on 32-bit systems, and a multiple of 16 on
 64-bit systems.  Only rarely is any higher boundary (such as a page
-boundary) necessary; for those cases, use @code{posix_memalign}
-(@pxref{Aligned Memory Blocks}).
+boundary) necessary; for those cases, use @code{aligned_alloc} or
+@code{posix_memalign} (@pxref{Aligned Memory Blocks}).

 Note that the memory located after the end of the block is likely to be
 in use for something else; perhaps a block already allocated by another
@@ -616,8 +616,31 @@  after calling @code{free} wastes memory.  The size threshold for
 The address of a block returned by @code{malloc} or @code{realloc} in
 @gnusystems{} is always a multiple of eight (or sixteen on 64-bit
 systems).  If you need a block whose address is a multiple of a higher
-power of two than that, use @code{posix_memalign}.  @code{posix_memalign}
-is declared in @file{stdlib.h}.
+power of two than that, use @code{aligned_alloc} or @code{posix_memalign}.
+@code{aligned_alloc} and @code{posix_memalign} are declared in
+@file{stdlib.h}.
+
+@comment stdlib.h
+@deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size})
+The @code{aligned_alloc} function allocates a block of @var{size} bytes whose
+address is a multiple of @var{alignment}.  The @var{alignment} must be a
+power of two and @var{size} must be a multiple of @var{alignment}.
+
+The @code{aligned_alloc} function returns a null pointer on error and sets
+@code{errno} to one of the following values:
+
+@table @code
+@item ENOMEM
+There was insufficient memory available to satisfy the request.
+
+@item EINVAL
+@var{alignment} is not a power of two.
+
+This function was introduced in @w{ISO C11} and hence may have better
+portability to modern non-POSIX systems than @code{posix_memalign}.
+@end table
+
+@end deftypefun

 @comment malloc.h
 @comment BSD
@@ -640,8 +663,8 @@  There was insufficient memory available to satisfy the request.

 @end table

-The @code{memalign} function is obsolete and @code{posix_memalign} should
-be used instead.
+The @code{memalign} function is obsolete and @code{aligned_alloc} or
+@code{posix_memalign} should be used instead.
 @end deftypefun

 @comment stdlib.h
@@ -667,7 +690,9 @@  There was insufficient memory available to satisfy the request.

 @end table

-This function was introduced in POSIX 1003.1d.
+This function was introduced in POSIX 1003.1d. Although this function is
+superseded by @code{aligned_alloc}, it is more portable to older POSIX
+systems that do not support @w{ISO C11}.
 @end deftypefun

 @comment malloc.h stdlib.h
@@ -687,8 +712,8 @@  valloc (size_t size)
 @ref{Query Memory Parameters} for more information about the memory
 subsystem.

-The @code{valloc} function is obsolete and @code{posix_memalign} should
-be used instead.
+The @code{valloc} function is obsolete and @code{aligned_alloc} or
+@code{posix_memalign} should be used instead.
 @end deftypefun

 @node Malloc Tunable Parameters
@@ -924,17 +949,19 @@  memory consumption of the program.
 @comment malloc.h
 @comment GNU
 @defvar __memalign_hook
-The value of this variable is a pointer to function that @code{memalign},
-@code{posix_memalign} and @code{valloc} use whenever they are called.
-You should define this function to look like @code{memalign}; that is, like:
+The value of this variable is a pointer to function that @code{aligned_alloc},
+@code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they
+are called. You should define this function to look like @code{aligned_alloc};
+that is, like:

 @smallexample
 void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller})
 @end smallexample

 The value of @var{caller} is the return address found on the stack when
-the @code{memalign}, @code{posix_memalign} or @code{valloc} functions are
-called.  This value allows you to trace the memory consumption of the program.
+the @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} or
+@code{valloc} functions are called.  This value allows you to trace the
+memory consumption of the program.
 @end defvar

 You must make sure that the function you install as a hook for one of
@@ -1140,6 +1167,10 @@  Space}.
 Allocate a block of @var{size} bytes, starting on a page boundary.
 @xref{Aligned Memory Blocks}.

+@item void *aligned_alloc (size_t @var{size}, size_t @var{alignment})
+Allocate a block of @var{size} bytes, starting on an address that is a
+multiple of @var{alignment}.  @xref{Aligned Memory Blocks}.
+
 @item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
 Allocate a block of @var{size} bytes, starting on an address that is a
 multiple of @var{alignment}.  @xref{Aligned Memory Blocks}.
@@ -1166,8 +1197,8 @@  A pointer to a function that @code{realloc} uses whenever it is called.
 A pointer to a function that @code{free} uses whenever it is called.

 @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller})
-A pointer to a function that @code{memalign}, @code{posix_memalign} and
-@code{valloc} use whenever they are called.
+A pointer to a function that @code{aligned_alloc}, @code{memalign},
+@code{posix_memalign} and @code{valloc} use whenever they are called.

 @item struct mallinfo mallinfo (void)
 Return information about the current dynamic memory usage.