N2801 - Wording for Sized Memory Deallocation

David Goldblatt, Facebook (davidtgoldblatt@gmail.com)

2021-08-30

Summary

WG14 straw polls on N2699 (Sized Memory Deallocation) indicated directional support and support for its choice of names. Author homework was:

This is the promised paper.

Requested changes

These are the changes WG14 requested.

Paragraph 2 in each section has been changed from "If ptr is the result obtained from a call ..." to "If ptr is a null pointer or the result obtained from a call ...". This fixes the issue pointed out by Joseph Myers on the reflector, that the previous wording unintentionally made sized deallocation of null pointers undefined behavior if those pointers did not come from an allocation function (a divergence from existing implementations and other languages).

In the same paragraphs, "Otherwise, the result is undefined" has been changed to "Otherwise, the behavior is undefined". This is clearer, since these functions return void; there's not "result" per se.

Wording candidate 1

To be added to the memory management functions section (7.22.3, relative to n2596), with X and Y filled in by the editor as appropriate. This is the version with the minimal edits suggested in previous discussion.

7.22.3.X The free_sized function

Synopsis

1.

#include <stdlib.h>
void free_sized(void *ptr, size_t size);

Description

2. If ptr is a null pointer or the result obtained from a call to malloc(size), realloc(old_ptr, size), or calloc(nmemb, memb_size), where nmemb * memb_size is equal to size, this function behaves equivalently to free(ptr). Otherwise, the behavior is undefined.

3. NOTE: A conforming implementation may simply ignore size and call free.

4. NOTE: The result of an aligned_alloc call may not be passed to free_sized.

5. Implementations may provide extensions to query the usable size of an allocation, or to determine the usable size of the allocation that would result if a request for some other size were to succeed. Such implementations should allow passing the resulting usable size as the size parameter, and provide functionality equivalent to free in such cases.

Returns

6. The free_sized function returns no value.

7.22.3.Y The free_aligned_sized function

Synopsis

1.

#include <stdlib.h>
void free_aligned_sized(void *ptr, size_t alignment, size_t size);

Description

2. If ptr is a null pointer or the result obtained from a call to aligned_alloc(alignment, size), this function behaves equivalently to free(ptr). Otherwise, the behavior is undefined.

3. NOTE: A conforming implementation may simply ignore size and alignment and call free.

4. NOTE: The result of a malloc, calloc, or realloc call may not be passed to free_aligned_sized.

5. Implementations may provide extensions to query the usable size of an allocation, or to determine the usable size of the allocation that would result if a request for some other size were to succeed. Such implementations should allow passing the resulting usable size as the size parameter, and provide functionality equivalent to free in such cases.

Returns

6. The free_aligned_sized function returns no value.

Wording candidate 2

In review, Robert Seacord suggested some additional wording clarifications:

This wording makes those changes (in addition to those above).

7.22.3.X The free_sized function

Synopsis

1.

#include <stdlib.h>
void free_sized(void *ptr, size_t size);

Description

2. If ptr is a null pointer or the result obtained from a call to malloc, realloc, or calloc, where size is equal to the requested allocation size, this function is equivalent to free(ptr). Otherwise, the behavior is undefined.

3. NOTE: A conforming implementation may ignore size and call free.

4. NOTE: The result of an aligned_alloc call may not be passed to free_sized.

5. Implementations may provide extensions to query the usable size of an allocation, or to determine the usable size of the allocation that would result if a request for some other size were to succeed. Such implementations should allow passing the resulting usable size as the size parameter, and provide functionality equivalent to free in such cases.

Returns

6. The free_sized function returns no value.

7.22.3.Y The free_aligned_sized function

Synopsis

1.

#include <stdlib.h>
void free_aligned_sized(void *ptr, size_t alignment, size_t size);

Description

2. If ptr is a null pointer or the result obtained from a call to aligned_alloc(alignment, size), where alignment is equal to the requested allocation alignment and size is equal to the requested allocation size, this function is equivalent to free(ptr). Otherwise, the behavior is undefined.

3. NOTE: A conforming implementation may ignore size and alignment and call free.

4. NOTE: The result of a malloc, calloc, or realloc call may not be passed to free_aligned_sized.

5. Implementations may provide extensions to query the usable size of an allocation, or to determine the usable size of the allocation that would result if a request for some other size were to succeed. Such implementations should allow passing the resulting usable size as the size parameter, and provide functionality equivalent to free in such cases.

Returns

6. The free_aligned_sized function returns no value.