[basic.stc.dynamic] - C++17 → C++20

Files changed (1) hide show

tmp/tmp3b1klpq8/{from.md → to.md} +123 -113

tmp/tmp3b1klpq8/{from.md → to.md} RENAMED Viewed

@@ -1,40 +1,39 @@
-### Dynamic storage duration <a id="basic.stc.dynamic">[[basic.stc.dynamic]]</a>
-Objects can be created dynamically during program execution (
-[[intro.execution]]), using *new-expression*s ([[expr.new]]), and
-destroyed using *delete-expression*s ([[expr.delete]]). A
-C++implementation provides access to, and management of, dynamic storage
-via the global *allocation functions* `operator new` and `operator
 new[]` and the global *deallocation functions* `operator
 delete` and `operator delete[]`.
 [*Note 1*: The non-allocating forms described in
 [[new.delete.placement]] do not perform allocation or
 deallocation. — *end note*]
 The library provides default definitions for the global allocation and
 deallocation functions. Some global allocation and deallocation
-functions are replaceable ([[new.delete]]). A C++program shall provide
-at most one definition of a replaceable allocation or deallocation
 function. Any such function definition replaces the default version
-provided in the library ([[replacement.functions]]). The following
-allocation and deallocation functions ([[support.dynamic]]) are
-implicitly declared in global scope in each translation unit of a
-program.
 ``` cpp
-void* operator new(std::size_t);
-void* operator new(std::size_t, std::align_val_t);
 void operator delete(void*) noexcept;
 void operator delete(void*, std::size_t) noexcept;
 void operator delete(void*, std::align_val_t) noexcept;
 void operator delete(void*, std::size_t, std::align_val_t) noexcept;
-void* operator new[](std::size_t);
-void* operator new[](std::size_t, std::align_val_t);
 void operator delete[](void*) noexcept;
 void operator delete[](void*, std::size_t) noexcept;
 void operator delete[](void*, std::align_val_t) noexcept;
 void operator delete[](void*, std::size_t, std::align_val_t) noexcept;
@@ -45,152 +44,165 @@ These implicit declarations introduce only the function names `operator`
 `delete[]`.
 [*Note 2*: The implicit declarations do not introduce the names `std`,
 `std::size_t`, `std::align_val_t`, or any other names that the library
 uses to declare these names. Thus, a *new-expression*,
-*delete-expression* or function call that refers to one of these
-functions without including the header `<new>` is well-formed. However,
-referring to `std` or `std::size_t` or `std::align_val_t` is ill-formed
-unless the name has been declared by including the appropriate
-header. — *end note*]
 Allocation and/or deallocation functions may also be declared and
-defined for any class ([[class.free]]).
-Any allocation and/or deallocation functions defined in a C++program,
-including the default versions in the library, shall conform to the
-semantics specified in  [[basic.stc.dynamic.allocation]] and
-[[basic.stc.dynamic.deallocation]].
-#### Allocation functions <a id="basic.stc.dynamic.allocation">[[basic.stc.dynamic.allocation]]</a>
 An allocation function shall be a class member function or a global
 function; a program is ill-formed if an allocation function is declared
 in a namespace scope other than global scope or declared static in
 global scope. The return type shall be `void*`. The first parameter
-shall have type `std::size_t` ([[support.types]]). The first parameter
-shall not have an associated default argument ([[dcl.fct.default]]).
-The value of the first parameter shall be interpreted as the requested
-size of the allocation. An allocation function can be a function
-template. Such a template shall declare its return type and first
-parameter as specified above (that is, template parameter types shall
-not be used in the return type and first parameter type). Template
-allocation functions shall have two or more parameters.
-The allocation function attempts to allocate the requested amount of
-storage. If it is successful, it shall return the address of the start
-of a block of storage whose length in bytes shall be at least as large
-as the requested size. There are no constraints on the contents of the
-allocated storage on return from the allocation function. The order,
-contiguity, and initial value of storage allocated by successive calls
-to an allocation function are unspecified. The pointer returned shall be
-suitably aligned so that it can be converted to a pointer to any
-suitable complete object type ([[new.delete.single]]) and then used to
-access the object or array in the storage allocated (until the storage
-is explicitly deallocated by a call to a corresponding deallocation
-function). Even if the size of the space requested is zero, the request
-can fail. If the request succeeds, the value returned shall be a
-non-null pointer value ([[conv.ptr]]) `p0` different from any
-previously returned value `p1`, unless that value `p1` was subsequently
-passed to an `operator` `delete`. Furthermore, for the library
-allocation functions in  [[new.delete.single]] and
-[[new.delete.array]], `p0` shall represent the address of a block of
-storage disjoint from the storage for any other object accessible to the
-caller. The effect of indirecting through a pointer returned as a
-request for zero size is undefined.[^13]
 An allocation function that fails to allocate storage can invoke the
-currently installed new-handler function ([[new.handler]]), if any.
-[*Note 1*:  A program-supplied allocation function can obtain the
 address of the currently installed `new_handler` using the
-`std::get_new_handler` function ([[set.new.handler]]). — *end note*]
-If an allocation function that has a non-throwing exception
-specification ([[except.spec]]) fails to allocate storage, it shall
-return a null pointer. Any other allocation function that fails to
-allocate storage shall indicate failure only by throwing an exception (
-[[except.throw]]) of a type that would match a handler (
-[[except.handle]]) of type `std::bad_alloc` ([[bad.alloc]]).
 A global allocation function is only called as the result of a new
-expression ([[expr.new]]), or called directly using the function call
-syntax ([[expr.call]]), or called indirectly through calls to the
-functions in the C++standard library.
-[*Note 2*: In particular, a global allocation function is not called to
-allocate storage for objects with static storage duration (
-[[basic.stc.static]]), for objects or references with thread storage
-duration ([[basic.stc.thread]]), for objects of type `std::type_info` (
-[[expr.typeid]]), or for an exception object (
-[[except.throw]]). — *end note*]
-#### Deallocation functions <a id="basic.stc.dynamic.deallocation">[[basic.stc.dynamic.deallocation]]</a>
 Deallocation functions shall be class member functions or global
 functions; a program is ill-formed if deallocation functions are
 declared in a namespace scope other than global scope or declared static
 in global scope.
-Each deallocation function shall return `void` and its first parameter
-shall be `void*`. A deallocation function may have more than one
-parameter. A *usual deallocation function* is a deallocation function
-that has:
-- exactly one parameter; or
-- exactly two parameters, the type of the second being either
-  `std::align_val_t` or `std::size_t` [^14]; or
-- exactly three parameters, the type of the second being `std::size_t`
-  and the type of the third being `std::align_val_t`.
-A deallocation function may be an instance of a function template.
-Neither the first parameter nor the return type shall depend on a
-template parameter.
-[*Note 1*: That is, a deallocation function template shall have a first
-parameter of type `void*` and a return type of `void` (as specified
-above). — *end note*]
-A deallocation function template shall have two or more function
-parameters. A template instance is never a usual deallocation function,
-regardless of its signature.
 If a deallocation function terminates by throwing an exception, the
 behavior is undefined. The value of the first argument supplied to a
 deallocation function may be a null pointer value; if so, and if the
 deallocation function is one supplied in the standard library, the call
 has no effect.
 If the argument given to a deallocation function in the standard library
-is a pointer that is not the null pointer value ([[conv.ptr]]), the
 deallocation function shall deallocate the storage referenced by the
 pointer, ending the duration of the region of storage.
-#### Safely-derived pointers <a id="basic.stc.dynamic.safety">[[basic.stc.dynamic.safety]]</a>
 A *traceable pointer object* is
-- an object of an object pointer type ([[basic.compound]]), or
 - an object of an integral type that is at least as large as
   `std::intptr_t`, or
-- a sequence of elements in an array of narrow character type (
-  [[basic.fundamental]]), where the size and alignment of the sequence
   match those of some object pointer type.
-A pointer value is a *safely-derived pointer* to a dynamic object only
-if it has an object pointer type and it is one of the following:
-- the value returned by a call to the C++standard library implementation
-  of `::operator new(std::{}size_t)` or
-  `::operator new(std::size_t, std::align_val_t)` ;[^15]
 - the result of taking the address of an object (or one of its
   subobjects) designated by an lvalue resulting from indirection through
   a safely-derived pointer value;
-- the result of well-defined pointer arithmetic ([[expr.add]]) using a
   safely-derived pointer value;
-- the result of a well-defined pointer conversion ([[conv.ptr]],
-  [[expr.cast]]) of a safely-derived pointer value;
 - the result of a `reinterpret_cast` of a safely-derived pointer value;
 - the result of a `reinterpret_cast` of an integer representation of a
   safely-derived pointer value;
 - the value of an object whose value was copied from a traceable pointer
   object, where at the time of the copy the source object contained a
@@ -216,17 +228,15 @@ An implementation may have *relaxed pointer safety*, in which case the
 validity of a pointer value does not depend on whether it is a
 safely-derived pointer value. Alternatively, an implementation may have
 *strict pointer safety*, in which case a pointer value referring to an
 object with dynamic storage duration that is not a safely-derived
 pointer value is an invalid pointer value unless the referenced complete
-object has previously been declared reachable (
-[[util.dynamic.safety]]).
-[*Note 1*: The effect of using an invalid pointer value (including
-passing it to a deallocation function) is undefined, see
-[[basic.stc.dynamic.deallocation]]. This is true even if the
-unsafely-derived pointer value might compare equal to some
-safely-derived pointer value. — *end note*]
 It is *implementation-defined* whether an implementation has relaxed or
 strict pointer safety.

+#### Dynamic storage duration <a id="basic.stc.dynamic">[[basic.stc.dynamic]]</a>
+Objects can be created dynamically during program execution
+[[intro.execution]], using *new-expression*s [[expr.new]], and destroyed
+using *delete-expression*s [[expr.delete]]. A C++ implementation
+provides access to, and management of, dynamic storage via the global
+*allocation functions* `operator new` and `operator
 new[]` and the global *deallocation functions* `operator
 delete` and `operator delete[]`.
 [*Note 1*: The non-allocating forms described in
 [[new.delete.placement]] do not perform allocation or
 deallocation. — *end note*]
 The library provides default definitions for the global allocation and
 deallocation functions. Some global allocation and deallocation
+functions are replaceable [[new.delete]]. A C++ program shall provide at
+most one definition of a replaceable allocation or deallocation
 function. Any such function definition replaces the default version
+provided in the library [[replacement.functions]]. The following
+allocation and deallocation functions [[support.dynamic]] are implicitly
+declared in global scope in each translation unit of a program.
 ``` cpp
+[[nodiscard]] void* operator new(std::size_t);
+[[nodiscard]] void* operator new(std::size_t, std::align_val_t);
 void operator delete(void*) noexcept;
 void operator delete(void*, std::size_t) noexcept;
 void operator delete(void*, std::align_val_t) noexcept;
 void operator delete(void*, std::size_t, std::align_val_t) noexcept;
+[[nodiscard]] void* operator new[](std::size_t);
+[[nodiscard]] void* operator new[](std::size_t, std::align_val_t);
 void operator delete[](void*) noexcept;
 void operator delete[](void*, std::size_t) noexcept;
 void operator delete[](void*, std::align_val_t) noexcept;
 void operator delete[](void*, std::size_t, std::align_val_t) noexcept;
 `delete[]`.
 [*Note 2*: The implicit declarations do not introduce the names `std`,
 `std::size_t`, `std::align_val_t`, or any other names that the library
 uses to declare these names. Thus, a *new-expression*,
+*delete-expression*, or function call that refers to one of these
+functions without importing or including the header `<new>` is
+well-formed. However, referring to `std` or `std::size_t` or
+`std::align_val_t` is ill-formed unless the name has been declared by
+importing or including the appropriate header. — *end note*]
 Allocation and/or deallocation functions may also be declared and
+defined for any class [[class.free]].
+If the behavior of an allocation or deallocation function does not
+satisfy the semantic constraints specified in
+[[basic.stc.dynamic.allocation]] and
+[[basic.stc.dynamic.deallocation]], the behavior is undefined.
+##### Allocation functions <a id="basic.stc.dynamic.allocation">[[basic.stc.dynamic.allocation]]</a>
 An allocation function shall be a class member function or a global
 function; a program is ill-formed if an allocation function is declared
 in a namespace scope other than global scope or declared static in
 global scope. The return type shall be `void*`. The first parameter
+shall have type `std::size_t` [[support.types]]. The first parameter
+shall not have an associated default argument [[dcl.fct.default]]. The
+value of the first parameter is interpreted as the requested size of the
+allocation. An allocation function can be a function template. Such a
+template shall declare its return type and first parameter as specified
+above (that is, template parameter types shall not be used in the return
+type and first parameter type). Template allocation functions shall have
+two or more parameters.
+An allocation function attempts to allocate the requested amount of
+storage. If it is successful, it returns the address of the start of a
+block of storage whose length in bytes is at least as large as the
+requested size. The order, contiguity, and initial value of storage
+allocated by successive calls to an allocation function are unspecified.
+Even if the size of the space requested is zero, the request can fail.
+If the request succeeds, the value returned by a replaceable allocation
+function is a non-null pointer value [[basic.compound]] `p0` different
+from any previously returned value `p1`, unless that value `p1` was
+subsequently passed to a replaceable deallocation function. Furthermore,
+for the library allocation functions in  [[new.delete.single]] and
+[[new.delete.array]], `p0` represents the address of a block of storage
+disjoint from the storage for any other object accessible to the caller.
+The effect of indirecting through a pointer returned from a request for
+zero size is undefined.[^14]
+For an allocation function other than a reserved placement allocation
+function [[new.delete.placement]], the pointer returned on a successful
+call shall represent the address of storage that is aligned as follows:
+- If the allocation function takes an argument of type
+  `std::align_val_t`, the storage will have the alignment specified by
+  the value of this argument.
+- Otherwise, if the allocation function is named `operator new[]`, the
+  storage is aligned for any object that does not have new-extended
+  alignment [[basic.align]] and is no larger than the requested size.
+- Otherwise, the storage is aligned for any object that does not have
+  new-extended alignment and is of the requested size.
 An allocation function that fails to allocate storage can invoke the
+currently installed new-handler function [[new.handler]], if any.
+[*Note 3*:  A program-supplied allocation function can obtain the
 address of the currently installed `new_handler` using the
+`std::get_new_handler` function [[get.new.handler]]. — *end note*]
+An allocation function that has a non-throwing exception specification
+[[except.spec]] indicates failure by returning a null pointer value. Any
+other allocation function never returns a null pointer value and
+indicates failure only by throwing an exception [[except.throw]] of a
+type that would match a handler [[except.handle]] of type
+`std::bad_alloc` [[bad.alloc]].
 A global allocation function is only called as the result of a new
+expression [[expr.new]], or called directly using the function call
+syntax [[expr.call]], or called indirectly to allocate storage for a
+coroutine state [[dcl.fct.def.coroutine]], or called indirectly through
+calls to the functions in the C++ standard library.
+[*Note 4*: In particular, a global allocation function is not called to
+allocate storage for objects with static storage duration
+[[basic.stc.static]], for objects or references with thread storage
+duration [[basic.stc.thread]], for objects of type `std::type_info`
+[[expr.typeid]], or for an exception object
+[[except.throw]]. — *end note*]
+##### Deallocation functions <a id="basic.stc.dynamic.deallocation">[[basic.stc.dynamic.deallocation]]</a>
 Deallocation functions shall be class member functions or global
 functions; a program is ill-formed if deallocation functions are
 declared in a namespace scope other than global scope or declared static
 in global scope.
+A deallocation function is a *destroying operator delete* if it has at
+least two parameters and its second parameter is of type
+`std::destroying_delete_t`. A destroying operator delete shall be a
+class member function named `operator delete`.
+[*Note 5*: Array deletion cannot use a destroying operator
+delete. — *end note*]
+Each deallocation function shall return `void`. If the function is a
+destroying operator delete declared in class type `C`, the type of its
+first parameter shall be `C*`; otherwise, the type of its first
+parameter shall be `void*`. A deallocation function may have more than
+one parameter. A *usual deallocation function* is a deallocation
+function whose parameters after the first are
+- optionally, a parameter of type `std::destroying_delete_t`, then
+- optionally, a parameter of type `std::size_t` [^15], then
+- optionally, a parameter of type `std::align_val_t`.
+A destroying operator delete shall be a usual deallocation function. A
+deallocation function may be an instance of a function template. Neither
+the first parameter nor the return type shall depend on a template
+parameter. A deallocation function template shall have two or more
+function parameters. A template instance is never a usual deallocation
+function, regardless of its signature.
 If a deallocation function terminates by throwing an exception, the
 behavior is undefined. The value of the first argument supplied to a
 deallocation function may be a null pointer value; if so, and if the
 deallocation function is one supplied in the standard library, the call
 has no effect.
 If the argument given to a deallocation function in the standard library
+is a pointer that is not the null pointer value [[basic.compound]], the
 deallocation function shall deallocate the storage referenced by the
 pointer, ending the duration of the region of storage.
+##### Safely-derived pointers <a id="basic.stc.dynamic.safety">[[basic.stc.dynamic.safety]]</a>
 A *traceable pointer object* is
+- an object of an object pointer type [[basic.compound]], or
 - an object of an integral type that is at least as large as
   `std::intptr_t`, or
+- a sequence of elements in an array of narrow character type
+  [[basic.fundamental]], where the size and alignment of the sequence
   match those of some object pointer type.
+A pointer value is a *safely-derived pointer* to an object with dynamic
+storage duration only if the pointer value has an object pointer type
+and is one of the following:
+- the value returned by a call to the C++ standard library
+ implementation of `::operator new(std::{}size_t)` or
+  `::operator new(std::size_t, std::align_val_t)` ;[^16]
 - the result of taking the address of an object (or one of its
   subobjects) designated by an lvalue resulting from indirection through
   a safely-derived pointer value;
+- the result of well-defined pointer arithmetic [[expr.add]] using a
+  safely-derived pointer value;
+- the result of a well-defined pointer conversion ([[conv.ptr]],
+  [[expr.type.conv]], [[expr.static.cast]], [[expr.cast]]) of a
   safely-derived pointer value;
 - the result of a `reinterpret_cast` of a safely-derived pointer value;
 - the result of a `reinterpret_cast` of an integer representation of a
   safely-derived pointer value;
 - the value of an object whose value was copied from a traceable pointer
   object, where at the time of the copy the source object contained a
 validity of a pointer value does not depend on whether it is a
 safely-derived pointer value. Alternatively, an implementation may have
 *strict pointer safety*, in which case a pointer value referring to an
 object with dynamic storage duration that is not a safely-derived
 pointer value is an invalid pointer value unless the referenced complete
+object has previously been declared reachable [[util.dynamic.safety]].
+[*Note 6*: The effect of using an invalid pointer value (including
+passing it to a deallocation function) is undefined, see  [[basic.stc]].
+This is true even if the unsafely-derived pointer value might compare
+equal to some safely-derived pointer value. — *end note*]
 It is *implementation-defined* whether an implementation has relaxed or
 strict pointer safety.

Diff to HTML by rtfpessoa