From patchwork Wed Nov 6 16:33:18 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Will Newton X-Patchwork-Id: 21388 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-pa0-f72.google.com (mail-pa0-f72.google.com [209.85.220.72]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id A8C7E20DB9 for ; Wed, 6 Nov 2013 16:33:23 +0000 (UTC) Received: by mail-pa0-f72.google.com with SMTP id rd3sf19255713pab.11 for ; Wed, 06 Nov 2013 08:33:22 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:message-id:date:from:user-agent :mime-version:to:cc:subject:x-original-sender :x-original-authentication-results:precedence:mailing-list:list-id :list-post:list-help:list-archive:list-unsubscribe:content-type :content-transfer-encoding; bh=CZkFbJ1qphHCwcuq03Qi0/0AH+1XbXf9KaqPfaF/xo0=; b=YixNINLDxR0c+8HURp5wWW0Hf7LcWXqu4Z25PUo879mpHpjW4MhErBq36GfnpiII41 frRPQduuKxlFuYyOVgWhbBd+YfU7MI1uo+QcNrpKwKTOInELK5o7xR1RfW9EYYJdIFN/ nGU2gKqpJS28+nqqK8MDDNg+LQ0juYfXbEa2oxj1NfzNifR9hFuNmQsIXZUBKKAmO0VM u6GLS/dsqi7EH9/RXrK+YJqbfU+557RRG94LU64/IyMm+6Ua9QUhffu8n+h4dtctZlmb bp2VPjIzyQ0Xtguw2sOfmsuexCRUROWAMqoY/AvByquyNhjwPGBirIOqg0947uuTBreA 3ifw== X-Gm-Message-State: ALoCoQmJG6RvD+Np8PoKaarmWt+jvv3mtsfwkqQ77Dmw2VvkjP0OY4yV9u92nWZhA/LP7MtLwmxW X-Received: by 10.66.117.170 with SMTP id kf10mr1486410pab.35.1383755602681; Wed, 06 Nov 2013 08:33:22 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.49.70.228 with SMTP id p4ls824129qeu.43.gmail; Wed, 06 Nov 2013 08:33:22 -0800 (PST) X-Received: by 10.52.36.40 with SMTP id n8mr2671379vdj.34.1383755602553; Wed, 06 Nov 2013 08:33:22 -0800 (PST) Received: from mail-vc0-f178.google.com (mail-vc0-f178.google.com [209.85.220.178]) by mx.google.com with ESMTPS id e6si8322123vcb.69.2013.11.06.08.33.22 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 06 Nov 2013 08:33:22 -0800 (PST) Received-SPF: neutral (google.com: 209.85.220.178 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) client-ip=209.85.220.178; Received: by mail-vc0-f178.google.com with SMTP id ie18so6819823vcb.37 for ; Wed, 06 Nov 2013 08:33:22 -0800 (PST) X-Received: by 10.52.35.136 with SMTP id h8mr2550733vdj.6.1383755602455; Wed, 06 Nov 2013 08:33:22 -0800 (PST) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patches@linaro.org Received: by 10.220.174.196 with SMTP id u4csp296090vcz; Wed, 6 Nov 2013 08:33:21 -0800 (PST) X-Received: by 10.14.32.196 with SMTP id o44mr4474276eea.43.1383755601405; Wed, 06 Nov 2013 08:33:21 -0800 (PST) Received: from mail-ea0-f182.google.com (mail-ea0-f182.google.com [209.85.215.182]) by mx.google.com with ESMTPS id e42si8687835eeo.117.2013.11.06.08.33.21 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 06 Nov 2013 08:33:21 -0800 (PST) Received-SPF: neutral (google.com: 209.85.215.182 is neither permitted nor denied by best guess record for domain of will.newton@linaro.org) client-ip=209.85.215.182; Received: by mail-ea0-f182.google.com with SMTP id o10so5165738eaj.27 for ; Wed, 06 Nov 2013 08:33:21 -0800 (PST) X-Received: by 10.14.246.11 with SMTP id p11mr4508796eer.9.1383755600903; Wed, 06 Nov 2013 08:33:20 -0800 (PST) Received: from localhost.localdomain (cpc6-seac21-2-0-cust453.7-2.cable.virginm.net. [82.1.113.198]) by mx.google.com with ESMTPSA id k7sm75745714eeg.13.2013.11.06.08.33.19 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Wed, 06 Nov 2013 08:33:20 -0800 (PST) Message-ID: <527A6F4E.4020006@linaro.org> Date: Wed, 06 Nov 2013 16:33:18 +0000 From: Will Newton User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130805 Thunderbird/17.0.8 MIME-Version: 1.0 To: libc-alpha@sourceware.org CC: Patch Tracking Subject: [PATCH 2/2] manual/memory.texi: Document aligned_alloc. X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: will.newton@linaro.org X-Original-Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.220.178 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Precedence: list Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org List-ID: X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , ChangeLog: 2013-11-06 Will Newton * 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(-) 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.