diff mbox series

clarify nonaliasing property of attribute malloc (PR 99295)

Message ID fc8340eb-1611-eecf-fc37-94ea5433fd07@gmail.com
State New
Headers show
Series clarify nonaliasing property of attribute malloc (PR 99295) | expand

Commit Message

Martin Sebor March 1, 2021, 5:45 p.m. UTC 
The documentation change made for pr83023 - branch probabilities
pessimize malloc, introduced an ambiguity into the description of
attribute malloc pointed out in pr99295.

The change suggests that GCC assumes that most calls only to malloc
and calloc but not to realloc return non-null.  Subsequent changes
exacerbated this problem by inserting additional text in between.

The attached change rewords the description to avoid this unintended
reading.

Martin

Comments

Richard Biener March 2, 2021, 10:41 a.m. UTC | #1 
On Mon, Mar 1, 2021 at 7:32 PM Martin Sebor via Gcc-patches
<gcc-patches@gcc.gnu.org> wrote:
>
> The documentation change made for pr83023 - branch probabilities
> pessimize malloc, introduced an ambiguity into the description of
> attribute malloc pointed out in pr99295.
>
> The change suggests that GCC assumes that most calls only to malloc
> and calloc but not to realloc return non-null.  Subsequent changes
> exacerbated this problem by inserting additional text in between.
>
> The attached change rewords the description to avoid this unintended
> reading.

OK.

Richard.

>
> Martin
diff mbox series

Patch

PR middle-end/99295 - documentation on __attribute__((malloc)) is wrong

gcc/ChangeLog:

	PR middle-end/99295
	* doc/extend.texi (attribute malloc): Reword and clarify nonaliasing
	property.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 02578cd953f..0debf84e726 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -3240,7 +3240,9 @@  calls.
 Attribute @code{malloc} indicates that a function is @code{malloc}-like,
 i.e., that the pointer @var{P} returned by the function cannot alias any
 other pointer valid when the function returns, and moreover no
-pointers to valid objects occur in any storage addressed by @var{P}.
+pointers to valid objects occur in any storage addressed by @var{P}. In
+addition, the GCC predicts that a function with the attribute returns
+non-null in most cases.
 
 Independently, the form of the attribute with one or two arguments
 associates @code{deallocator} as a suitable deallocation function for
@@ -3248,13 +3250,14 @@  pointers returned from the @code{malloc}-like function.  @var{ptr-index}
 denotes the positional argument to which when the pointer is passed in
 calls to @code{deallocator} has the effect of deallocating it.
 
-Using the attribute with no arguments is designed to improve optimization.
-The compiler predicts that a function with the attribute returns non-null
-in most cases.  Functions like @code{malloc} and @code{calloc} have this
-property because they return a pointer to uninitialized or zeroed-out
-storage.  However, functions like @code{realloc} do not have this property,
-as they may return pointers to storage containing pointers to existing
-objects.
+Using the attribute with no arguments is designed to improve optimization
+by relying on the aliasing property it implies.  Functions like @code{malloc}
+and @code{calloc} have this property because they return a pointer to
+uninitialized or zeroed-out, newly obtained storage.  However, functions
+like @code{realloc} do not have this property, as they may return pointers
+to storage containing pointers to existing objects.  Additionally, since
+all such functions are assumed to return null only infrequently, callers
+can be optimized based on that assumption.
 
 Associating a function with a @var{deallocator} helps detect calls to
 mismatched allocation and deallocation functions and diagnose them under