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

Message ID 527A6F4E.4020006@linaro.org
State Superseded
Headers show

Commit Message

Will Newton Nov. 6, 2013, 4:33 p.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 | 59 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 44 insertions(+), 15 deletions(-)

Comments

Paul Eggert Nov. 6, 2013, 7:17 p.m. | #1
Looks pretty good.  Some suggestions:

> +This function was introduced in @w{ISO C11} and hence may have better
> +portability to modern non-POSIX systems than @code{posix_memalign}.

A similar note should be put in posix_memalign's documentation.
Something like this, perhaps?

  Although this function is superseded by @code{aligned_alloc}, it was
  standardized in POSIX.1-2004 and is more portable to older POSIX
  systems that do not support @w{ISO C11}.

> -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{posix_memalign} or
> +@code{aligned_alloc}.  @code{posix_memalign} and @code{aligned_alloc}
> +are declared in @file{stdlib.h}.

I would mention only aligned_alloc here; now that we have it, there's
no reason to recommend posix_memalign.

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

Likewise here.

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

And here.

> +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{memalign};

Change the last 'memalign' to 'aligned_alloc'.
Rich Felker Nov. 7, 2013, 3:44 a.m. | #2
On Wed, Nov 06, 2013 at 11:17:41AM -0800, Paul Eggert wrote:
> Looks pretty good.  Some suggestions:
> 
> > +This function was introduced in @w{ISO C11} and hence may have better
> > +portability to modern non-POSIX systems than @code{posix_memalign}.
> 
> A similar note should be put in posix_memalign's documentation.
> Something like this, perhaps?

It would also be nice to mention the danger of posix_memalign's
interface -- the void **-based interface encourages aliasing
violations of the form:

	char *p;
	int err = posix_memalign((void **)&p, 16, n);

As such, it should be deprecated.

Rich
Will Newton Nov. 7, 2013, 8:33 a.m. | #3
On 6 November 2013 19:17, Paul Eggert <eggert@cs.ucla.edu> wrote:
> Looks pretty good.  Some suggestions:
>
>> +This function was introduced in @w{ISO C11} and hence may have better
>> +portability to modern non-POSIX systems than @code{posix_memalign}.
>
> A similar note should be put in posix_memalign's documentation.
> Something like this, perhaps?
>
>   Although this function is superseded by @code{aligned_alloc}, it was
>   standardized in POSIX.1-2004 and is more portable to older POSIX
>   systems that do not support @w{ISO C11}.

Ok.

>> -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{posix_memalign} or
>> +@code{aligned_alloc}.  @code{posix_memalign} and @code{aligned_alloc}
>> +are declared in @file{stdlib.h}.
>
> I would mention only aligned_alloc here; now that we have it, there's
> no reason to recommend posix_memalign.

Perhaps, but I would rather get consensus on this. The majority of
code out there seems to be using posix_memalign and it is not
deprecated (i.e. it remains in currently applicable standards).
aligned_alloc seems pretty much unused AFAICT.

>> -The @code{memalign} function is obsolete and @code{posix_memalign} should
>> -be used instead.
>> +The @code{memalign} function is obsolete and @code{posix_memalign} or
>> +@code{aligned_alloc} should be used instead.
>
> Likewise here.
>
>> -The @code{valloc} function is obsolete and @code{posix_memalign} should
>> -be used instead.
>> +The @code{valloc} function is obsolete and @code{posix_memalign} or
>> +@code{aligned_alloc} should be used instead.
>
> And here.
>
>> +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{memalign};
>
> Change the last 'memalign' to 'aligned_alloc'.

The hook is called "__memalign_hook" so I'm not sure how much of an
improvement that is but I'll change it.

Thanks for the review!
Paul Eggert Nov. 7, 2013, 5:06 p.m. | #4
On 11/07/2013 12:33 AM, Will Newton wrote:
> The majority of
> code out there seems to be using posix_memalign and it is not
> deprecated (i.e. it remains in currently applicable standards).
> aligned_alloc seems pretty much unused AFAICT.

This is mainly because posix_memalign has been there for
years and aligned_alloc is new.  The newer interface is clearly better,
and the documentation shouldn't recommend the worse interface.

It's no big deal; if you want to mention both,
go ahead -- but please at least mention aligned_alloc first.

This thread reminded me to change GNU Emacs to prefer aligned_alloc to
posix_memalign if available.  Thanks!

http://bzr.savannah.gnu.org/lh/emacs/trunk/revision/115014
Will Newton Nov. 7, 2013, 5:37 p.m. | #5
On 7 November 2013 17:06, Paul Eggert <eggert@cs.ucla.edu> wrote:
> On 11/07/2013 12:33 AM, Will Newton wrote:
>> The majority of
>> code out there seems to be using posix_memalign and it is not
>> deprecated (i.e. it remains in currently applicable standards).
>> aligned_alloc seems pretty much unused AFAICT.
>
> This is mainly because posix_memalign has been there for
> years and aligned_alloc is new.  The newer interface is clearly better,
> and the documentation shouldn't recommend the worse interface.

True, but the question of which is "better" also involves which is
more portable to currently deployed systems IMO, and I do not have a
feel for whether aligned_alloc is actually out there and usable on a
wide variety of systems. C11 is only a couple of years old and only in
the last few years have we seen a widespread push to use C99 idioms
and even now there are projects that avoid C99.
Ondřej Bílka Nov. 7, 2013, 6:48 p.m. | #6
On Thu, Nov 07, 2013 at 05:37:59PM +0000, Will Newton wrote:
> On 7 November 2013 17:06, Paul Eggert <eggert@cs.ucla.edu> wrote:
> > On 11/07/2013 12:33 AM, Will Newton wrote:
> >> The majority of
> >> code out there seems to be using posix_memalign and it is not
> >> deprecated (i.e. it remains in currently applicable standards).
> >> aligned_alloc seems pretty much unused AFAICT.
> >
> > This is mainly because posix_memalign has been there for
> > years and aligned_alloc is new.  The newer interface is clearly better,
> > and the documentation shouldn't recommend the worse interface.
> 
> True, but the question of which is "better" also involves which is
> more portable to currently deployed systems IMO, and I do not have a
> feel for whether aligned_alloc is actually out there and usable on a
> wide variety of systems. C11 is only a couple of years old and only in
> the last few years have we seen a widespread push to use C99 idioms
> and even now there are projects that avoid C99.
> 
Portability depends on tools available. As one can by configure script

#define aligned_alloc memalign

portability is not issue here.

As heretic thougth issue here is that changing configure scripts takes
time and skill and most of time is duplication of work.

Somebody should create and maintain a autoautoconf project that would
generate header with compatibility definitions of functions that are not
present.

Second part is that converting to new interfaces also should be easy but
is not. Converting from obsolete functions to new ones is a repetive
task so there should be a program to do it.

These transformations should be easily done by coccinelle (example for
bzero is below), it is matter of writing collection of transformations,
put it in one place and propagate it to get used.

@@ expression e1, e2; @@

- bzero (e1, e2)
+ memset (e1, 0, e2)

Patch

diff --git a/manual/memory.texi b/manual/memory.texi
index 3d96f35..7281545 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{posix_memalign} or
+@code{aligned_alloc} (@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{posix_memalign} or
+@code{aligned_alloc}.  @code{posix_memalign} and @code{aligned_alloc}
+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{posix_memalign} or
+@code{aligned_alloc} should be used instead.
 @end deftypefun

 @comment stdlib.h
@@ -687,8 +710,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{posix_memalign} or
+@code{aligned_alloc} should be used instead.
 @end deftypefun

 @node Malloc Tunable Parameters
@@ -924,17 +947,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{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}, @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 +1165,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 +1195,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.