[v2,1/2] manual/memory.texi: Bring aligned allocation docs up to date.

Message ID 527A6F48.5040803@linaro.org
State Superseded
Headers show

Commit Message

Will Newton Nov. 6, 2013, 4:33 p.m.
The current documentation suggests using memalign and valloc which
are now considered obsolete, so suggest using posix_memalign instead.
Also document the possible error return and errno values for memalign
and posix_memalign and improve documentation of __memalign_hook.

ChangeLog:

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

	* manual/memory.texi (Malloc Examples): Clarify default
	alignment documentation.  Suggest posix_memalign rather
	than memalign or valloc.
	(Aligned Memory Blocks): Remove suggestion to use memalign
	or valloc.  Remove obsolete comment about BSD.
	Document memalign errno values and mark the function obsolete.
	Document posix_memalign returned error codes.  Mark valloc
	as obsolete.  (Hooks for Malloc): __memalign_hook is also
	called for posix_memalign and valloc.
	(Summary of Malloc): Add posix_memalign to function summary.
	__memalign_hook is also called for posix_memalign and valloc.
---
 manual/memory.texi | 61 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 44 insertions(+), 17 deletions(-)

Changes in v2:
 - Fix incorrect errno definitions

Comments

Will Newton Nov. 20, 2013, 11:08 a.m. | #1
On 6 November 2013 16:33, Will Newton <will.newton@linaro.org> wrote:
>
> The current documentation suggests using memalign and valloc which
> are now considered obsolete, so suggest using posix_memalign instead.
> Also document the possible error return and errno values for memalign
> and posix_memalign and improve documentation of __memalign_hook.
>
> ChangeLog:
>
> 2013-11-06  Will Newton  <will.newton@linaro.org>
>
>         * manual/memory.texi (Malloc Examples): Clarify default
>         alignment documentation.  Suggest posix_memalign rather
>         than memalign or valloc.
>         (Aligned Memory Blocks): Remove suggestion to use memalign
>         or valloc.  Remove obsolete comment about BSD.
>         Document memalign errno values and mark the function obsolete.
>         Document posix_memalign returned error codes.  Mark valloc
>         as obsolete.  (Hooks for Malloc): __memalign_hook is also
>         called for posix_memalign and valloc.
>         (Summary of Malloc): Add posix_memalign to function summary.
>         __memalign_hook is also called for posix_memalign and valloc.
> ---
>  manual/memory.texi | 61 +++++++++++++++++++++++++++++++++++++++---------------
>  1 file changed, 44 insertions(+), 17 deletions(-)
>
> Changes in v2:
>  - Fix incorrect errno definitions

Ping?
Ondřej Bílka Nov. 20, 2013, 11:25 a.m. | #2
On Wed, Nov 20, 2013 at 11:08:45AM +0000, Will Newton wrote:
> On 6 November 2013 16:33, Will Newton <will.newton@linaro.org> wrote:
> >
> > The current documentation suggests using memalign and valloc which
> > are now considered obsolete, so suggest using posix_memalign instead.
> > Also document the possible error return and errno values for memalign
> > and posix_memalign and improve documentation of __memalign_hook.
> >
> > ChangeLog:
> >
> > 2013-11-06  Will Newton  <will.newton@linaro.org>
> >
> >         * manual/memory.texi (Malloc Examples): Clarify default
> >         alignment documentation.  Suggest posix_memalign rather
> >         than memalign or valloc.
> >         (Aligned Memory Blocks): Remove suggestion to use memalign
> >         or valloc.  Remove obsolete comment about BSD.
> >         Document memalign errno values and mark the function obsolete.
> >         Document posix_memalign returned error codes.  Mark valloc
> >         as obsolete.  (Hooks for Malloc): __memalign_hook is also
> >         called for posix_memalign and valloc.
> >         (Summary of Malloc): Add posix_memalign to function summary.
> >         __memalign_hook is also called for posix_memalign and valloc.
> > ---
> >  manual/memory.texi | 61 +++++++++++++++++++++++++++++++++++++++---------------
> >  1 file changed, 44 insertions(+), 17 deletions(-)
> >
> > Changes in v2:
> >  - Fix incorrect errno definitions
> 
> Ping?
> 

Looks ok,

A minor nit is that if we aim for completeness then pvalloc is currently
undocumented. It could be added as separate patch or should we keep it
undocumented?
Will Newton Nov. 20, 2013, 1:15 p.m. | #3
On 20 November 2013 11:25, Ondřej Bílka <neleai@seznam.cz> wrote:
> On Wed, Nov 20, 2013 at 11:08:45AM +0000, Will Newton wrote:
>> On 6 November 2013 16:33, Will Newton <will.newton@linaro.org> wrote:
>> >
>> > The current documentation suggests using memalign and valloc which
>> > are now considered obsolete, so suggest using posix_memalign instead.
>> > Also document the possible error return and errno values for memalign
>> > and posix_memalign and improve documentation of __memalign_hook.
>> >
>> > ChangeLog:
>> >
>> > 2013-11-06  Will Newton  <will.newton@linaro.org>
>> >
>> >         * manual/memory.texi (Malloc Examples): Clarify default
>> >         alignment documentation.  Suggest posix_memalign rather
>> >         than memalign or valloc.
>> >         (Aligned Memory Blocks): Remove suggestion to use memalign
>> >         or valloc.  Remove obsolete comment about BSD.
>> >         Document memalign errno values and mark the function obsolete.
>> >         Document posix_memalign returned error codes.  Mark valloc
>> >         as obsolete.  (Hooks for Malloc): __memalign_hook is also
>> >         called for posix_memalign and valloc.
>> >         (Summary of Malloc): Add posix_memalign to function summary.
>> >         __memalign_hook is also called for posix_memalign and valloc.
>> > ---
>> >  manual/memory.texi | 61 +++++++++++++++++++++++++++++++++++++++---------------
>> >  1 file changed, 44 insertions(+), 17 deletions(-)
>> >
>> > Changes in v2:
>> >  - Fix incorrect errno definitions
>>
>> Ping?
>>
>
> Looks ok,
>
> A minor nit is that if we aim for completeness then pvalloc is currently
> undocumented. It could be added as separate patch or should we keep it
> undocumented?

Yes, I would consider documenting pvalloc in a follow on patch.
Paul Eggert Nov. 20, 2013, 7:23 p.m. | #4
This version of the patch suggests posix_memalign,
and doesn't mention aligned_alloc at all.  The documentation
should suggest aligned_alloc first, and posix_memalign second.
aligned_alloc is the better interface and is part of C11 so it'll
be available on more platforms eventually; posix_memalign
is also worth mentioning as it's available on more platforms
now.
Will Newton Nov. 21, 2013, 9:04 a.m. | #5
On 20 November 2013 19:23, Paul Eggert <eggert@cs.ucla.edu> wrote:

Hi Paul,

> This version of the patch suggests posix_memalign,
> and doesn't mention aligned_alloc at all.  The documentation
> should suggest aligned_alloc first, and posix_memalign second.
> aligned_alloc is the better interface and is part of C11 so it'll
> be available on more platforms eventually; posix_memalign
> is also worth mentioning as it's available on more platforms
> now.

I submitted a second patch to add aligned_alloc documentation. I can
certainly squash them together if you think that makes more sense.
Paul Eggert Nov. 21, 2013, 10:15 p.m. | #6
On 11/21/2013 01:04 AM, Will Newton wrote:
> I submitted a second patch to add aligned_alloc documentation. I can
> certainly squash them together if you think that makes more sense.

It's OK to keep them separate, but please submit them as a pair,
since they should both go in at the same time.  Currently I see
an updated:

[PATCH v2 1/2] manual/memory.texi: Bring aligned allocation docs up to date.
https://sourceware.org/ml/libc-alpha/2013-11/msg00151.html

along with a non-updated:

[PATCH 2/2] manual/memory.texi: Document aligned_alloc.
https://sourceware.org/ml/libc-alpha/2013-11/msg00152.html

with an unresolved comment at:

https://sourceware.org/ml/libc-alpha/2013-11/msg00172.html

Thanks.

Patch

diff --git a/manual/memory.texi b/manual/memory.texi
index a80f87c..3d96f35 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -380,10 +380,10 @@  savestring (const char *ptr, size_t len)

 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 most systems, and a multiple of 16 on
+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{memalign},
-@code{posix_memalign} or @code{valloc} (@pxref{Aligned Memory Blocks}).
+boundary) necessary; for those cases, use @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,14 +616,8 @@  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{memalign}, @code{posix_memalign}, or
-@code{valloc}.  @code{memalign} is declared in @file{malloc.h} and
-@code{posix_memalign} is declared in @file{stdlib.h}.
-
-With @theglibc{}, you can use @code{free} to free the blocks that
-@code{memalign}, @code{posix_memalign}, and @code{valloc} return.  That
-does not work in BSD, however---BSD does not provide any way to free
-such blocks.
+power of two than that, use @code{posix_memalign}.  @code{posix_memalign}
+is declared in @file{stdlib.h}.

 @comment malloc.h
 @comment BSD
@@ -633,6 +627,21 @@  address is a multiple of @var{boundary}.  The @var{boundary} must be a
 power of two!  The function @code{memalign} works by allocating a
 somewhat larger block, and then returning an address within the block
 that is on the specified boundary.
+
+The @code{memalign} 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.
+
+@end table
+
+The @code{memalign} function is obsolete and @code{posix_memalign} should
+be used instead.
 @end deftypefun

 @comment stdlib.h
@@ -647,6 +656,16 @@  parameter @var{alignment}: the value must be a power of two multiple of
 If the function succeeds in allocation memory a pointer to the allocated
 memory is returned in @code{*@var{memptr}} and the return value is zero.
 Otherwise the function returns an error value indicating the problem.
+The possible error values returned are:
+
+@table @code
+@item ENOMEM
+There was insufficient memory available to satisfy the request.
+
+@item EINVAL
+@var{alignment} is not a power of two multiple of @code{sizeof (void *)}.
+
+@end table

 This function was introduced in POSIX 1003.1d.
 @end deftypefun
@@ -667,6 +686,9 @@  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.
 @end deftypefun

 @node Malloc Tunable Parameters
@@ -902,17 +924,17 @@  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}
-uses whenever it is 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{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:

 @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} function was called.  This value allows you to trace the
-memory consumption of the program.
+the @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
@@ -1118,6 +1140,10 @@  Space}.
 Allocate a block of @var{size} bytes, starting on a page boundary.
 @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}.
+
 @item void *memalign (size_t @var{size}, size_t @var{boundary})
 Allocate a block of @var{size} bytes, starting on an address that is a
 multiple of @var{boundary}.  @xref{Aligned Memory Blocks}.
@@ -1140,7 +1166,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} uses whenever it is called.
+A pointer to a function that @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.