- tmp/tmpfmxfgg6k/{from.md → to.md} +96 -108
tmp/tmpfmxfgg6k/{from.md → to.md}
RENAMED
|
@@ -7,50 +7,47 @@ delete`. If the value of an alignment argument passed to any of these
|
|
| 7 |
functions is not a valid alignment value, the behavior is undefined.
|
| 8 |
|
| 9 |
#### Single-object forms <a id="new.delete.single">[[new.delete.single]]</a>
|
| 10 |
|
| 11 |
``` cpp
|
| 12 |
-
void* operator new(std::size_t size);
|
| 13 |
-
void* operator new(std::size_t size, std::align_val_t alignment);
|
| 14 |
```
|
| 15 |
|
| 16 |
-
*Effects:* The allocation functions
|
| 17 |
-
called by a *new-expression*
|
| 18 |
storage. The second form is called for a type with new-extended
|
| 19 |
-
alignment, and
|
| 20 |
-
form is called otherwise, and allocates storage suitably aligned to
|
| 21 |
-
represent any object of that size provided the object’s type does not
|
| 22 |
-
have new-extended alignment.
|
| 23 |
|
| 24 |
*Replaceable:* A C++ program may define functions with either of these
|
| 25 |
function signatures, and thereby displace the default versions defined
|
| 26 |
by the C++ standard library.
|
| 27 |
|
| 28 |
*Required behavior:* Return a non-null pointer to suitably aligned
|
| 29 |
-
storage
|
| 30 |
This requirement is binding on any replacement versions of these
|
| 31 |
functions.
|
| 32 |
|
| 33 |
*Default behavior:*
|
| 34 |
|
| 35 |
- Executes a loop: Within the loop, the function first attempts to
|
| 36 |
allocate the requested storage. Whether the attempt involves a call to
|
| 37 |
the C standard library functions `malloc` or `aligned_alloc` is
|
| 38 |
unspecified.
|
| 39 |
- Returns a pointer to the allocated storage if the attempt is
|
| 40 |
-
successful. Otherwise, if the current
|
| 41 |
-
|
| 42 |
-
`bad_alloc`.
|
| 43 |
- Otherwise, the function calls the current `new_handler`
|
| 44 |
-
function
|
| 45 |
repeats.
|
| 46 |
- The loop terminates when an attempt to allocate the requested storage
|
| 47 |
is successful or when a called `new_handler` function does not return.
|
| 48 |
|
| 49 |
``` cpp
|
| 50 |
-
void* operator new(std::size_t size, const std::nothrow_t&) noexcept;
|
| 51 |
-
void* operator new(std::size_t size, std::align_val_t alignment,
|
|
|
|
| 52 |
```
|
| 53 |
|
| 54 |
*Effects:* Same as above, except that these are called by a placement
|
| 55 |
version of a *new-expression* when a C++ program prefers a null pointer
|
| 56 |
result as an error indication, instead of a `bad_alloc` exception.
|
|
@@ -58,11 +55,11 @@ result as an error indication, instead of a `bad_alloc` exception.
|
|
| 58 |
*Replaceable:* A C++ program may define functions with either of these
|
| 59 |
function signatures, and thereby displace the default versions defined
|
| 60 |
by the C++ standard library.
|
| 61 |
|
| 62 |
*Required behavior:* Return a non-null pointer to suitably aligned
|
| 63 |
-
storage
|
| 64 |
these nothrow versions of `operator new` returns a pointer obtained as
|
| 65 |
if acquired from the (possibly replaced) corresponding non-placement
|
| 66 |
function. This requirement is binding on any replacement versions of
|
| 67 |
these functions.
|
| 68 |
|
|
@@ -85,13 +82,13 @@ void operator delete(void* ptr) noexcept;
|
|
| 85 |
void operator delete(void* ptr, std::size_t size) noexcept;
|
| 86 |
void operator delete(void* ptr, std::align_val_t alignment) noexcept;
|
| 87 |
void operator delete(void* ptr, std::size_t size, std::align_val_t alignment) noexcept;
|
| 88 |
```
|
| 89 |
|
| 90 |
-
*Effects:* The deallocation
|
| 91 |
-
|
| 92 |
-
|
| 93 |
|
| 94 |
*Replaceable:* A C++ program may define functions with any of these
|
| 95 |
function signatures, and thereby displace the default versions defined
|
| 96 |
by the C++ standard library.
|
| 97 |
|
|
@@ -102,26 +99,26 @@ define the corresponding version without the `size` parameter.
|
|
| 102 |
|
| 103 |
[*Note 1*: The default behavior below may change in the future, which
|
| 104 |
will require replacing both deallocation functions when replacing the
|
| 105 |
allocation function. — *end note*]
|
| 106 |
|
| 107 |
-
*
|
| 108 |
-
|
| 109 |
-
|
| 110 |
`operator new(std::size_t, std::align_val_t)` which has not been
|
| 111 |
invalidated by an intervening call to `operator delete`.
|
| 112 |
|
| 113 |
-
*
|
| 114 |
-
safety
|
| 115 |
-
|
| 116 |
|
| 117 |
-
*
|
| 118 |
-
|
| 119 |
-
|
| 120 |
-
|
| 121 |
-
`
|
| 122 |
-
|
| 123 |
|
| 124 |
*Required behavior:* A call to an `operator delete` with a `size`
|
| 125 |
parameter may be changed to a call to the corresponding
|
| 126 |
`operator delete` without a `size` parameter, without affecting memory
|
| 127 |
allocation.
|
|
@@ -148,53 +145,48 @@ reclaimed storage will be allocated by subsequent calls to
|
|
| 148 |
``` cpp
|
| 149 |
void operator delete(void* ptr, const std::nothrow_t&) noexcept;
|
| 150 |
void operator delete(void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;
|
| 151 |
```
|
| 152 |
|
| 153 |
-
*Effects:* The deallocation
|
| 154 |
-
|
| 155 |
-
|
| 156 |
-
|
| 157 |
-
an exception.
|
| 158 |
|
| 159 |
*Replaceable:* A C++ program may define functions with either of these
|
| 160 |
function signatures, and thereby displace the default versions defined
|
| 161 |
by the C++ standard library.
|
| 162 |
|
| 163 |
-
*
|
| 164 |
-
|
| 165 |
-
|
| 166 |
`operator new(std::size_t, std::align_val_t)` which has not been
|
| 167 |
invalidated by an intervening call to `operator delete`.
|
| 168 |
|
| 169 |
-
*
|
| 170 |
-
safety
|
| 171 |
-
|
| 172 |
|
| 173 |
-
*
|
| 174 |
-
|
| 175 |
-
|
| 176 |
-
|
| 177 |
-
`ptr`.
|
| 178 |
|
| 179 |
*Default behavior:* Calls `operator delete(ptr)`, or
|
| 180 |
`operator delete(ptr, alignment)`, respectively.
|
| 181 |
|
| 182 |
#### Array forms <a id="new.delete.array">[[new.delete.array]]</a>
|
| 183 |
|
| 184 |
``` cpp
|
| 185 |
-
void* operator new[](std::size_t size);
|
| 186 |
-
void* operator new[](std::size_t size, std::align_val_t alignment);
|
| 187 |
```
|
| 188 |
|
| 189 |
-
*Effects:* The allocation functions
|
| 190 |
-
called by the array form of a *new-expression*
|
| 191 |
-
|
| 192 |
-
|
| 193 |
-
alignment. The first form is called otherwise, and allocates storage
|
| 194 |
-
suitably aligned to represent any array object of that size or smaller,
|
| 195 |
-
provided the object’s type does not have new-extended alignment. [^33]
|
| 196 |
|
| 197 |
*Replaceable:* A C++ program may define functions with either of these
|
| 198 |
function signatures, and thereby displace the default versions defined
|
| 199 |
by the C++ standard library.
|
| 200 |
|
|
@@ -204,12 +196,13 @@ functions.
|
|
| 204 |
|
| 205 |
*Default behavior:* Returns `operator new(size)`, or
|
| 206 |
`operator new(size, alignment)`, respectively.
|
| 207 |
|
| 208 |
``` cpp
|
| 209 |
-
void* operator new[](std::size_t size, const std::nothrow_t&) noexcept;
|
| 210 |
-
void* operator new[](std::size_t size, std::align_val_t alignment,
|
|
|
|
| 211 |
```
|
| 212 |
|
| 213 |
*Effects:* Same as above, except that these are called by a placement
|
| 214 |
version of a *new-expression* when a C++ program prefers a null pointer
|
| 215 |
result as an error indication, instead of a `bad_alloc` exception.
|
|
@@ -217,11 +210,11 @@ result as an error indication, instead of a `bad_alloc` exception.
|
|
| 217 |
*Replaceable:* A C++ program may define functions with either of these
|
| 218 |
function signatures, and thereby displace the default versions defined
|
| 219 |
by the C++ standard library.
|
| 220 |
|
| 221 |
*Required behavior:* Return a non-null pointer to suitably aligned
|
| 222 |
-
storage
|
| 223 |
these nothrow versions of `operator new[]` returns a pointer obtained as
|
| 224 |
if acquired from the (possibly replaced) corresponding non-placement
|
| 225 |
function. This requirement is binding on any replacement versions of
|
| 226 |
these functions.
|
| 227 |
|
|
@@ -235,13 +228,13 @@ void operator delete[](void* ptr) noexcept;
|
|
| 235 |
void operator delete[](void* ptr, std::size_t size) noexcept;
|
| 236 |
void operator delete[](void* ptr, std::align_val_t alignment) noexcept;
|
| 237 |
void operator delete[](void* ptr, std::size_t size, std::align_val_t alignment) noexcept;
|
| 238 |
```
|
| 239 |
|
| 240 |
-
*Effects:* The deallocation
|
| 241 |
-
|
| 242 |
-
|
| 243 |
|
| 244 |
*Replaceable:* A C++ program may define functions with any of these
|
| 245 |
function signatures, and thereby displace the default versions defined
|
| 246 |
by the C++ standard library.
|
| 247 |
|
|
@@ -252,26 +245,26 @@ define the corresponding version without the `size` parameter.
|
|
| 252 |
|
| 253 |
[*Note 1*: The default behavior below may change in the future, which
|
| 254 |
will require replacing both deallocation functions when replacing the
|
| 255 |
allocation function. — *end note*]
|
| 256 |
|
| 257 |
-
*
|
| 258 |
-
|
| 259 |
-
|
| 260 |
`operator new[](std::size_t, std::align_val_t)` which has not been
|
| 261 |
invalidated by an intervening call to `operator delete[]`.
|
| 262 |
|
| 263 |
-
*
|
| 264 |
-
safety
|
| 265 |
-
|
| 266 |
|
| 267 |
-
*
|
| 268 |
-
|
| 269 |
-
|
| 270 |
-
|
| 271 |
-
`
|
| 272 |
-
|
| 273 |
|
| 274 |
*Required behavior:* A call to an `operator delete[]` with a `size`
|
| 275 |
parameter may be changed to a call to the corresponding
|
| 276 |
`operator delete[]` without a `size` parameter, without affecting memory
|
| 277 |
allocation.
|
|
@@ -289,48 +282,46 @@ function.
|
|
| 289 |
``` cpp
|
| 290 |
void operator delete[](void* ptr, const std::nothrow_t&) noexcept;
|
| 291 |
void operator delete[](void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;
|
| 292 |
```
|
| 293 |
|
| 294 |
-
*Effects:* The deallocation
|
| 295 |
-
|
| 296 |
-
|
| 297 |
-
|
| 298 |
-
throws an exception.
|
| 299 |
|
| 300 |
*Replaceable:* A C++ program may define functions with either of these
|
| 301 |
function signatures, and thereby displace the default versions defined
|
| 302 |
by the C++ standard library.
|
| 303 |
|
| 304 |
-
*
|
| 305 |
-
|
| 306 |
-
|
| 307 |
`operator new[](std::size_t, std::align_val_t)` which has not been
|
| 308 |
invalidated by an intervening call to `operator delete[]`.
|
| 309 |
|
| 310 |
-
*
|
| 311 |
-
safety
|
| 312 |
-
|
| 313 |
|
| 314 |
-
*
|
| 315 |
-
|
| 316 |
-
|
| 317 |
-
|
| 318 |
-
`ptr`.
|
| 319 |
|
| 320 |
*Default behavior:* Calls `operator delete[](ptr)`, or
|
| 321 |
`operator delete[](ptr, alignment)`, respectively.
|
| 322 |
|
| 323 |
#### Non-allocating forms <a id="new.delete.placement">[[new.delete.placement]]</a>
|
| 324 |
|
| 325 |
-
These functions are reserved; a C++program may not define functions
|
| 326 |
-
displace the versions in the C++standard library
|
| 327 |
-
provisions of [[basic.stc.dynamic]] do not apply to these reserved
|
| 328 |
placement forms of `operator new` and `operator delete`.
|
| 329 |
|
| 330 |
``` cpp
|
| 331 |
-
void* operator new(std::size_t size, void* ptr) noexcept;
|
| 332 |
```
|
| 333 |
|
| 334 |
*Returns:* `ptr`.
|
| 335 |
|
| 336 |
*Remarks:* Intentionally performs no other action.
|
|
@@ -345,11 +336,11 @@ Something* p = new (place) Something();
|
|
| 345 |
```
|
| 346 |
|
| 347 |
— *end example*]
|
| 348 |
|
| 349 |
``` cpp
|
| 350 |
-
void* operator new[](std::size_t size, void* ptr) noexcept;
|
| 351 |
```
|
| 352 |
|
| 353 |
*Returns:* `ptr`.
|
| 354 |
|
| 355 |
*Remarks:* Intentionally performs no other action.
|
|
@@ -358,43 +349,40 @@ void* operator new[](std::size_t size, void* ptr) noexcept;
|
|
| 358 |
void operator delete(void* ptr, void*) noexcept;
|
| 359 |
```
|
| 360 |
|
| 361 |
*Effects:* Intentionally performs no action.
|
| 362 |
|
| 363 |
-
*
|
| 364 |
-
safety
|
| 365 |
-
|
| 366 |
|
| 367 |
*Remarks:* Default function called when any part of the initialization
|
| 368 |
in a placement *new-expression* that invokes the library’s non-array
|
| 369 |
-
placement operator new terminates by throwing an
|
| 370 |
-
exception ([[expr.new]]).
|
| 371 |
|
| 372 |
``` cpp
|
| 373 |
void operator delete[](void* ptr, void*) noexcept;
|
| 374 |
```
|
| 375 |
|
| 376 |
*Effects:* Intentionally performs no action.
|
| 377 |
|
| 378 |
-
*
|
| 379 |
-
safety
|
| 380 |
-
|
| 381 |
|
| 382 |
*Remarks:* Default function called when any part of the initialization
|
| 383 |
in a placement *new-expression* that invokes the library’s array
|
| 384 |
-
placement operator new terminates by throwing an
|
| 385 |
-
exception ([[expr.new]]).
|
| 386 |
|
| 387 |
#### Data races <a id="new.delete.dataraces">[[new.delete.dataraces]]</a>
|
| 388 |
|
| 389 |
For purposes of determining the existence of data races, the library
|
| 390 |
versions of `operator new`, user replacement versions of global
|
| 391 |
`operator new`, the C standard library functions `aligned_alloc`,
|
| 392 |
`calloc`, and `malloc`, the library versions of `operator delete`, user
|
| 393 |
replacement versions of `operator delete`, the C standard library
|
| 394 |
function `free`, and the C standard library function `realloc` shall not
|
| 395 |
-
introduce a data race
|
| 396 |
that allocate or deallocate a particular unit of storage shall occur in
|
| 397 |
a single total order, and each such deallocation call shall happen
|
| 398 |
-
before
|
| 399 |
-
order.
|
| 400 |
|
|
|
|
| 7 |
functions is not a valid alignment value, the behavior is undefined.
|
| 8 |
|
| 9 |
#### Single-object forms <a id="new.delete.single">[[new.delete.single]]</a>
|
| 10 |
|
| 11 |
``` cpp
|
| 12 |
+
[[nodiscard]] void* operator new(std::size_t size);
|
| 13 |
+
[[nodiscard]] void* operator new(std::size_t size, std::align_val_t alignment);
|
| 14 |
```
|
| 15 |
|
| 16 |
+
*Effects:* The allocation functions [[basic.stc.dynamic.allocation]]
|
| 17 |
+
called by a *new-expression*[[expr.new]] to allocate `size` bytes of
|
| 18 |
storage. The second form is called for a type with new-extended
|
| 19 |
+
alignment, and the first form is called otherwise.
|
|
|
|
|
|
|
|
|
|
| 20 |
|
| 21 |
*Replaceable:* A C++ program may define functions with either of these
|
| 22 |
function signatures, and thereby displace the default versions defined
|
| 23 |
by the C++ standard library.
|
| 24 |
|
| 25 |
*Required behavior:* Return a non-null pointer to suitably aligned
|
| 26 |
+
storage [[basic.stc.dynamic]], or else throw a `bad_alloc` exception.
|
| 27 |
This requirement is binding on any replacement versions of these
|
| 28 |
functions.
|
| 29 |
|
| 30 |
*Default behavior:*
|
| 31 |
|
| 32 |
- Executes a loop: Within the loop, the function first attempts to
|
| 33 |
allocate the requested storage. Whether the attempt involves a call to
|
| 34 |
the C standard library functions `malloc` or `aligned_alloc` is
|
| 35 |
unspecified.
|
| 36 |
- Returns a pointer to the allocated storage if the attempt is
|
| 37 |
+
successful. Otherwise, if the current `new_handler`
|
| 38 |
+
[[get.new.handler]] is a null pointer value, throws `bad_alloc`.
|
|
|
|
| 39 |
- Otherwise, the function calls the current `new_handler`
|
| 40 |
+
function [[new.handler]]. If the called function returns, the loop
|
| 41 |
repeats.
|
| 42 |
- The loop terminates when an attempt to allocate the requested storage
|
| 43 |
is successful or when a called `new_handler` function does not return.
|
| 44 |
|
| 45 |
``` cpp
|
| 46 |
+
[[nodiscard]] void* operator new(std::size_t size, const std::nothrow_t&) noexcept;
|
| 47 |
+
[[nodiscard]] void* operator new(std::size_t size, std::align_val_t alignment,
|
| 48 |
+
const std::nothrow_t&) noexcept;
|
| 49 |
```
|
| 50 |
|
| 51 |
*Effects:* Same as above, except that these are called by a placement
|
| 52 |
version of a *new-expression* when a C++ program prefers a null pointer
|
| 53 |
result as an error indication, instead of a `bad_alloc` exception.
|
|
|
|
| 55 |
*Replaceable:* A C++ program may define functions with either of these
|
| 56 |
function signatures, and thereby displace the default versions defined
|
| 57 |
by the C++ standard library.
|
| 58 |
|
| 59 |
*Required behavior:* Return a non-null pointer to suitably aligned
|
| 60 |
+
storage [[basic.stc.dynamic]], or else return a null pointer. Each of
|
| 61 |
these nothrow versions of `operator new` returns a pointer obtained as
|
| 62 |
if acquired from the (possibly replaced) corresponding non-placement
|
| 63 |
function. This requirement is binding on any replacement versions of
|
| 64 |
these functions.
|
| 65 |
|
|
|
|
| 82 |
void operator delete(void* ptr, std::size_t size) noexcept;
|
| 83 |
void operator delete(void* ptr, std::align_val_t alignment) noexcept;
|
| 84 |
void operator delete(void* ptr, std::size_t size, std::align_val_t alignment) noexcept;
|
| 85 |
```
|
| 86 |
|
| 87 |
+
*Effects:* The deallocation functions [[basic.stc.dynamic.deallocation]]
|
| 88 |
+
called by a *delete-expression*[[expr.delete]] to render the value of
|
| 89 |
+
`ptr` invalid.
|
| 90 |
|
| 91 |
*Replaceable:* A C++ program may define functions with any of these
|
| 92 |
function signatures, and thereby displace the default versions defined
|
| 93 |
by the C++ standard library.
|
| 94 |
|
|
|
|
| 99 |
|
| 100 |
[*Note 1*: The default behavior below may change in the future, which
|
| 101 |
will require replacing both deallocation functions when replacing the
|
| 102 |
allocation function. — *end note*]
|
| 103 |
|
| 104 |
+
*Preconditions:* `ptr` is a null pointer or its value represents the
|
| 105 |
+
address of a block of memory allocated by an earlier call to a (possibly
|
| 106 |
+
replaced) `operator new(std::size_t)` or
|
| 107 |
`operator new(std::size_t, std::align_val_t)` which has not been
|
| 108 |
invalidated by an intervening call to `operator delete`.
|
| 109 |
|
| 110 |
+
*Preconditions:* If an implementation has strict pointer
|
| 111 |
+
safety [[basic.stc.dynamic.safety]] then `ptr` is a safely-derived
|
| 112 |
+
pointer.
|
| 113 |
|
| 114 |
+
*Preconditions:* If the `alignment` parameter is not present, `ptr` was
|
| 115 |
+
returned by an allocation function without an `alignment` parameter. If
|
| 116 |
+
present, the `alignment` argument is equal to the `alignment` argument
|
| 117 |
+
passed to the allocation function that returned `ptr`. If present, the
|
| 118 |
+
`size` argument is equal to the `size` argument passed to the allocation
|
| 119 |
+
function that returned `ptr`.
|
| 120 |
|
| 121 |
*Required behavior:* A call to an `operator delete` with a `size`
|
| 122 |
parameter may be changed to a call to the corresponding
|
| 123 |
`operator delete` without a `size` parameter, without affecting memory
|
| 124 |
allocation.
|
|
|
|
| 145 |
``` cpp
|
| 146 |
void operator delete(void* ptr, const std::nothrow_t&) noexcept;
|
| 147 |
void operator delete(void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;
|
| 148 |
```
|
| 149 |
|
| 150 |
+
*Effects:* The deallocation functions [[basic.stc.dynamic.deallocation]]
|
| 151 |
+
called by the implementation to render the value of `ptr` invalid when
|
| 152 |
+
the constructor invoked from a nothrow placement version of the
|
| 153 |
+
*new-expression* throws an exception.
|
|
|
|
| 154 |
|
| 155 |
*Replaceable:* A C++ program may define functions with either of these
|
| 156 |
function signatures, and thereby displace the default versions defined
|
| 157 |
by the C++ standard library.
|
| 158 |
|
| 159 |
+
*Preconditions:* `ptr` is a null pointer or its value represents the
|
| 160 |
+
address of a block of memory allocated by an earlier call to a (possibly
|
| 161 |
+
replaced) `operator new(std::size_t)` or
|
| 162 |
`operator new(std::size_t, std::align_val_t)` which has not been
|
| 163 |
invalidated by an intervening call to `operator delete`.
|
| 164 |
|
| 165 |
+
*Preconditions:* If an implementation has strict pointer
|
| 166 |
+
safety [[basic.stc.dynamic.safety]] then `ptr` is a safely-derived
|
| 167 |
+
pointer.
|
| 168 |
|
| 169 |
+
*Preconditions:* If the `alignment` parameter is not present, `ptr` was
|
| 170 |
+
returned by an allocation function without an `alignment` parameter. If
|
| 171 |
+
present, the `alignment` argument is equal to the `alignment` argument
|
| 172 |
+
passed to the allocation function that returned `ptr`.
|
|
|
|
| 173 |
|
| 174 |
*Default behavior:* Calls `operator delete(ptr)`, or
|
| 175 |
`operator delete(ptr, alignment)`, respectively.
|
| 176 |
|
| 177 |
#### Array forms <a id="new.delete.array">[[new.delete.array]]</a>
|
| 178 |
|
| 179 |
``` cpp
|
| 180 |
+
[[nodiscard]] void* operator new[](std::size_t size);
|
| 181 |
+
[[nodiscard]] void* operator new[](std::size_t size, std::align_val_t alignment);
|
| 182 |
```
|
| 183 |
|
| 184 |
+
*Effects:* The allocation functions [[basic.stc.dynamic.allocation]]
|
| 185 |
+
called by the array form of a *new-expression*[[expr.new]] to allocate
|
| 186 |
+
`size` bytes of storage. The second form is called for a type with
|
| 187 |
+
new-extended alignment, and the first form is called otherwise. [^33]
|
|
|
|
|
|
|
|
|
|
| 188 |
|
| 189 |
*Replaceable:* A C++ program may define functions with either of these
|
| 190 |
function signatures, and thereby displace the default versions defined
|
| 191 |
by the C++ standard library.
|
| 192 |
|
|
|
|
| 196 |
|
| 197 |
*Default behavior:* Returns `operator new(size)`, or
|
| 198 |
`operator new(size, alignment)`, respectively.
|
| 199 |
|
| 200 |
``` cpp
|
| 201 |
+
[[nodiscard]] void* operator new[](std::size_t size, const std::nothrow_t&) noexcept;
|
| 202 |
+
[[nodiscard]] void* operator new[](std::size_t size, std::align_val_t alignment,
|
| 203 |
+
const std::nothrow_t&) noexcept;
|
| 204 |
```
|
| 205 |
|
| 206 |
*Effects:* Same as above, except that these are called by a placement
|
| 207 |
version of a *new-expression* when a C++ program prefers a null pointer
|
| 208 |
result as an error indication, instead of a `bad_alloc` exception.
|
|
|
|
| 210 |
*Replaceable:* A C++ program may define functions with either of these
|
| 211 |
function signatures, and thereby displace the default versions defined
|
| 212 |
by the C++ standard library.
|
| 213 |
|
| 214 |
*Required behavior:* Return a non-null pointer to suitably aligned
|
| 215 |
+
storage [[basic.stc.dynamic]], or else return a null pointer. Each of
|
| 216 |
these nothrow versions of `operator new[]` returns a pointer obtained as
|
| 217 |
if acquired from the (possibly replaced) corresponding non-placement
|
| 218 |
function. This requirement is binding on any replacement versions of
|
| 219 |
these functions.
|
| 220 |
|
|
|
|
| 228 |
void operator delete[](void* ptr, std::size_t size) noexcept;
|
| 229 |
void operator delete[](void* ptr, std::align_val_t alignment) noexcept;
|
| 230 |
void operator delete[](void* ptr, std::size_t size, std::align_val_t alignment) noexcept;
|
| 231 |
```
|
| 232 |
|
| 233 |
+
*Effects:* The deallocation functions [[basic.stc.dynamic.deallocation]]
|
| 234 |
+
called by the array form of a *delete-expression* to render the value of
|
| 235 |
+
`ptr` invalid.
|
| 236 |
|
| 237 |
*Replaceable:* A C++ program may define functions with any of these
|
| 238 |
function signatures, and thereby displace the default versions defined
|
| 239 |
by the C++ standard library.
|
| 240 |
|
|
|
|
| 245 |
|
| 246 |
[*Note 1*: The default behavior below may change in the future, which
|
| 247 |
will require replacing both deallocation functions when replacing the
|
| 248 |
allocation function. — *end note*]
|
| 249 |
|
| 250 |
+
*Preconditions:* `ptr` is a null pointer or its value represents the
|
| 251 |
+
address of a block of memory allocated by an earlier call to a (possibly
|
| 252 |
+
replaced) `operator new[](std::size_t)` or
|
| 253 |
`operator new[](std::size_t, std::align_val_t)` which has not been
|
| 254 |
invalidated by an intervening call to `operator delete[]`.
|
| 255 |
|
| 256 |
+
*Preconditions:* If an implementation has strict pointer
|
| 257 |
+
safety [[basic.stc.dynamic.safety]] then `ptr` is a safely-derived
|
| 258 |
+
pointer.
|
| 259 |
|
| 260 |
+
*Preconditions:* If the `alignment` parameter is not present, `ptr` was
|
| 261 |
+
returned by an allocation function without an `alignment` parameter. If
|
| 262 |
+
present, the `alignment` argument is equal to the `alignment` argument
|
| 263 |
+
passed to the allocation function that returned `ptr`. If present, the
|
| 264 |
+
`size` argument is equal to the `size` argument passed to the allocation
|
| 265 |
+
function that returned `ptr`.
|
| 266 |
|
| 267 |
*Required behavior:* A call to an `operator delete[]` with a `size`
|
| 268 |
parameter may be changed to a call to the corresponding
|
| 269 |
`operator delete[]` without a `size` parameter, without affecting memory
|
| 270 |
allocation.
|
|
|
|
| 282 |
``` cpp
|
| 283 |
void operator delete[](void* ptr, const std::nothrow_t&) noexcept;
|
| 284 |
void operator delete[](void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;
|
| 285 |
```
|
| 286 |
|
| 287 |
+
*Effects:* The deallocation functions [[basic.stc.dynamic.deallocation]]
|
| 288 |
+
called by the implementation to render the value of `ptr` invalid when
|
| 289 |
+
the constructor invoked from a nothrow placement version of the array
|
| 290 |
+
*new-expression* throws an exception.
|
|
|
|
| 291 |
|
| 292 |
*Replaceable:* A C++ program may define functions with either of these
|
| 293 |
function signatures, and thereby displace the default versions defined
|
| 294 |
by the C++ standard library.
|
| 295 |
|
| 296 |
+
*Preconditions:* `ptr` is a null pointer or its value represents the
|
| 297 |
+
address of a block of memory allocated by an earlier call to a (possibly
|
| 298 |
+
replaced) `operator new[](std::size_t)` or
|
| 299 |
`operator new[](std::size_t, std::align_val_t)` which has not been
|
| 300 |
invalidated by an intervening call to `operator delete[]`.
|
| 301 |
|
| 302 |
+
*Preconditions:* If an implementation has strict pointer
|
| 303 |
+
safety [[basic.stc.dynamic.safety]] then `ptr` is a safely-derived
|
| 304 |
+
pointer.
|
| 305 |
|
| 306 |
+
*Preconditions:* If the `alignment` parameter is not present, `ptr` was
|
| 307 |
+
returned by an allocation function without an `alignment` parameter. If
|
| 308 |
+
present, the `alignment` argument is equal to the `alignment` argument
|
| 309 |
+
passed to the allocation function that returned `ptr`.
|
|
|
|
| 310 |
|
| 311 |
*Default behavior:* Calls `operator delete[](ptr)`, or
|
| 312 |
`operator delete[](ptr, alignment)`, respectively.
|
| 313 |
|
| 314 |
#### Non-allocating forms <a id="new.delete.placement">[[new.delete.placement]]</a>
|
| 315 |
|
| 316 |
+
These functions are reserved; a C++ program may not define functions
|
| 317 |
+
that displace the versions in the C++ standard library [[constraints]].
|
| 318 |
+
The provisions of [[basic.stc.dynamic]] do not apply to these reserved
|
| 319 |
placement forms of `operator new` and `operator delete`.
|
| 320 |
|
| 321 |
``` cpp
|
| 322 |
+
[[nodiscard]] void* operator new(std::size_t size, void* ptr) noexcept;
|
| 323 |
```
|
| 324 |
|
| 325 |
*Returns:* `ptr`.
|
| 326 |
|
| 327 |
*Remarks:* Intentionally performs no other action.
|
|
|
|
| 336 |
```
|
| 337 |
|
| 338 |
— *end example*]
|
| 339 |
|
| 340 |
``` cpp
|
| 341 |
+
[[nodiscard]] void* operator new[](std::size_t size, void* ptr) noexcept;
|
| 342 |
```
|
| 343 |
|
| 344 |
*Returns:* `ptr`.
|
| 345 |
|
| 346 |
*Remarks:* Intentionally performs no other action.
|
|
|
|
| 349 |
void operator delete(void* ptr, void*) noexcept;
|
| 350 |
```
|
| 351 |
|
| 352 |
*Effects:* Intentionally performs no action.
|
| 353 |
|
| 354 |
+
*Preconditions:* If an implementation has strict pointer
|
| 355 |
+
safety [[basic.stc.dynamic.safety]] then `ptr` is a safely-derived
|
| 356 |
+
pointer.
|
| 357 |
|
| 358 |
*Remarks:* Default function called when any part of the initialization
|
| 359 |
in a placement *new-expression* that invokes the library’s non-array
|
| 360 |
+
placement operator new terminates by throwing an exception [[expr.new]].
|
|
|
|
| 361 |
|
| 362 |
``` cpp
|
| 363 |
void operator delete[](void* ptr, void*) noexcept;
|
| 364 |
```
|
| 365 |
|
| 366 |
*Effects:* Intentionally performs no action.
|
| 367 |
|
| 368 |
+
*Preconditions:* If an implementation has strict pointer
|
| 369 |
+
safety [[basic.stc.dynamic.safety]] then `ptr` is a safely-derived
|
| 370 |
+
pointer.
|
| 371 |
|
| 372 |
*Remarks:* Default function called when any part of the initialization
|
| 373 |
in a placement *new-expression* that invokes the library’s array
|
| 374 |
+
placement operator new terminates by throwing an exception [[expr.new]].
|
|
|
|
| 375 |
|
| 376 |
#### Data races <a id="new.delete.dataraces">[[new.delete.dataraces]]</a>
|
| 377 |
|
| 378 |
For purposes of determining the existence of data races, the library
|
| 379 |
versions of `operator new`, user replacement versions of global
|
| 380 |
`operator new`, the C standard library functions `aligned_alloc`,
|
| 381 |
`calloc`, and `malloc`, the library versions of `operator delete`, user
|
| 382 |
replacement versions of `operator delete`, the C standard library
|
| 383 |
function `free`, and the C standard library function `realloc` shall not
|
| 384 |
+
introduce a data race [[res.on.data.races]]. Calls to these functions
|
| 385 |
that allocate or deallocate a particular unit of storage shall occur in
|
| 386 |
a single total order, and each such deallocation call shall happen
|
| 387 |
+
before [[intro.multithread]] the next allocation (if any) in this order.
|
|
|
|
| 388 |
|