From Jason Turner

[new.delete.single]

C++14 → C++17 11.6 KB 168 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game
C++ Weekly: Ep 107 | Ep 471 | Ep 478

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpr_k_7mmh/{from.md → to.md} +91 -73
tmp/tmpr_k_7mmh/{from.md → to.md} RENAMED
@@ -1,28 +1,35 @@
1
  #### Single-object forms <a id="new.delete.single">[[new.delete.single]]</a>
2
 
3
  ``` cpp
4
  void* operator new(std::size_t size);
 
5
  ```
6
 
7
- *Effects:* The *allocation function* ([[basic.stc.dynamic.allocation]])
8
  called by a *new-expression* ([[expr.new]]) to allocate `size` bytes of
9
- storage suitably aligned to represent any object of that size.
 
 
 
 
10
 
11
- *Replaceable:* a C++program may define a function with this function
12
- signature that displaces the default version defined by the C++standard
13
- library.
14
 
15
  *Required behavior:* Return a non-null pointer to suitably aligned
16
  storage ([[basic.stc.dynamic]]), or else throw a `bad_alloc` exception.
17
- This requirement is binding on a replacement version of this function.
 
18
 
19
  *Default behavior:*
20
 
21
  - Executes a loop: Within the loop, the function first attempts to
22
  allocate the requested storage. Whether the attempt involves a call to
23
- the Standard C library function `malloc` is unspecified.
 
24
  - Returns a pointer to the allocated storage if the attempt is
25
  successful. Otherwise, if the current
26
  `new_handler` ([[get.new.handler]]) is a null pointer value, throws
27
  `bad_alloc`.
28
  - Otherwise, the function calls the current `new_handler`
@@ -31,125 +38,136 @@ This requirement is binding on a replacement version of this function.
31
  - The loop terminates when an attempt to allocate the requested storage
32
  is successful or when a called `new_handler` function does not return.
33
 
34
  ``` cpp
35
  void* operator new(std::size_t size, const std::nothrow_t&) noexcept;
 
36
  ```
37
 
38
- *Effects:* Same as above, except that it is called by a placement
39
  version of a *new-expression* when a C++program prefers a null pointer
40
  result as an error indication, instead of a `bad_alloc` exception.
41
 
42
- *Replaceable:* a C++program may define a function with this function
43
- signature that displaces the default version defined by the C++standard
44
- library.
45
 
46
  *Required behavior:* Return a non-null pointer to suitably aligned
47
- storage ([[basic.stc.dynamic]]), or else return a null pointer. This
48
- nothrow version of `operator new` returns a pointer obtained as if
49
- acquired from the (possibly replaced) ordinary version. This requirement
50
- is binding on a replacement version of this function.
 
51
 
52
- *Default behavior:* Calls `operator new(size)`. If the call returns
 
53
  normally, returns the result of that call. Otherwise, returns a null
54
  pointer.
55
 
 
 
56
  ``` cpp
57
  T* p1 = new T; // throws bad_alloc if it fails
58
  T* p2 = new(nothrow) T; // returns nullptr if it fails
59
  ```
60
 
 
 
61
  ``` cpp
62
  void operator delete(void* ptr) noexcept;
63
  void operator delete(void* ptr, std::size_t size) noexcept;
 
 
64
  ```
65
 
66
- *Effects:* The *deallocation
67
- function* ([[basic.stc.dynamic.deallocation]]) called by a
68
  *delete-expression* to render the value of `ptr` invalid.
69
 
70
- *Replaceable:* a C++program may define a function with signature
71
- `void operator delete(void* ptr) noexcept` that displaces the default
72
- version defined by the C++standard library. If this function (without
73
- `size` parameter) is defined, the program should also define
74
- `void operator delete(void* ptr, std::size_t size) noexcept`. If this
75
- function with `size` parameter is defined, the program shall also define
76
- the version without the `size` parameter. The default behavior below may
77
- change in the future, which will require replacing both deallocation
78
- functions when replacing the allocation function.
79
 
80
- *Requires:* *ptr* shall be a null pointer or its value shall be a value
81
- returned by an earlier call to the (possibly replaced)
82
- `operator new(std::size_t)` or
83
- `operator new(std::size_t,const std::nothrow_t&)` which has not been
84
- invalidated by an intervening call to `operator delete(void*)`.
 
 
 
 
 
 
 
 
 
85
 
86
  *Requires:* If an implementation has strict pointer
87
  safety ([[basic.stc.dynamic.safety]]) then `ptr` shall be a
88
  safely-derived pointer.
89
 
90
- *Requires:* If present, the `std::size_t size` argument shall equal the
91
- size argument passed to the allocation function that returned `ptr`.
 
 
 
 
92
 
93
- *Required behavior:* Calls to
94
- `operator delete(void* ptr, std::size_t size)` may be changed to calls
95
- to `operator delete(void* ptr)` without affecting memory allocation. A
96
- conforming implementation is for
 
 
97
  `operator delete(void* ptr, std::size_t size)` to simply call
98
- `operator delete(ptr)`.
99
 
100
- *Default behavior:* the function
101
- `operator delete(void* ptr, std::size_t size)` calls
102
- `operator delete(ptr)`. See the note in the above *Replaceable*
103
- paragraph.
 
 
104
 
105
  *Default behavior:* If `ptr` is null, does nothing. Otherwise, reclaims
106
  the storage allocated by the earlier call to `operator new`.
107
 
108
  *Remarks:* It is unspecified under what conditions part or all of such
109
  reclaimed storage will be allocated by subsequent calls to
110
- `operator new` or any of `calloc`, `malloc`, or `realloc`, declared in
111
- `<cstdlib>`.
112
 
113
  ``` cpp
114
  void operator delete(void* ptr, const std::nothrow_t&) noexcept;
115
- void operator delete(void* ptr, std::size_t size, const std::nothrow_t&) noexcept;
116
  ```
117
 
118
- *Effects:* The *deallocation
119
- function* ([[basic.stc.dynamic.deallocation]]) called by the
120
  implementation to render the value of `ptr` invalid when the constructor
121
  invoked from a nothrow placement version of the *new-expression* throws
122
  an exception.
123
 
124
- *Replaceable:* a C++program may define a function with signature
125
- `void operator delete(void* ptr, const std::nothrow_t&) noexcept` that
126
- displaces the default version defined by the C++standard library. If
127
- this function (without `size` parameter) is defined, the program should
128
- also define
129
- `void operator delete(void* ptr, std::size_t size, const std::nothrow_t&) noexcept`.
130
- If this function with `size` parameter is defined, the program shall
131
- also define the version without the `size` parameter. The default
132
- behavior below may change in the future, which will require replacing
133
- both deallocation functions when replacing the allocation function.
134
 
135
  *Requires:* If an implementation has strict pointer
136
  safety ([[basic.stc.dynamic.safety]]) then `ptr` shall be a
137
  safely-derived pointer.
138
 
139
- *Requires:* If present, the `std::size_t size` argument must equal the
140
- size argument passed to the allocation function that returned `ptr`.
 
 
 
141
 
142
- *Required behavior:* Calls to
143
- `operator delete(void* ptr, std::size_t size, const std::nothrow_t&)`
144
- may be changed to calls to
145
- `operator delete(void* ptr, const std::nothrow_t&)` without affecting
146
- memory allocation. A conforming implementation is for
147
- `operator delete(void* ptr, std::size_t size, const std::nothrow_t&)` to
148
- simply call `operator delete(void* ptr, const std::nothrow_t&)`.
149
-
150
- *Default behavior:*
151
- `operator delete(void* ptr, std::size_t size, const std::nothrow_t&)`
152
- calls `operator delete(ptr, std::nothrow)`, and
153
- `operator delete(void* ptr, const std::nothrow_t&)` calls
154
- `operator delete(ptr)`.
155
 
 
1
  #### Single-object forms <a id="new.delete.single">[[new.delete.single]]</a>
2
 
3
  ``` cpp
4
  void* operator new(std::size_t size);
5
+ void* operator new(std::size_t size, std::align_val_t alignment);
6
  ```
7
 
8
+ *Effects:* The allocation functions ([[basic.stc.dynamic.allocation]])
9
  called by a *new-expression* ([[expr.new]]) to allocate `size` bytes of
10
+ storage. The second form is called for a type with new-extended
11
+ alignment, and allocates storage with the specified alignment. The first
12
+ form is called otherwise, and allocates storage suitably aligned to
13
+ represent any object of that size provided the object’s type does not
14
+ have new-extended alignment.
15
 
16
+ *Replaceable:* A C++program may define functions with either of these
17
+ function signatures, and thereby displace the default versions defined
18
+ by the C++standard library.
19
 
20
  *Required behavior:* Return a non-null pointer to suitably aligned
21
  storage ([[basic.stc.dynamic]]), or else throw a `bad_alloc` exception.
22
+ This requirement is binding on any replacement versions of these
23
+ functions.
24
 
25
  *Default behavior:*
26
 
27
  - Executes a loop: Within the loop, the function first attempts to
28
  allocate the requested storage. Whether the attempt involves a call to
29
+ the C standard library functions `malloc` or `aligned_alloc` is
30
+ unspecified.
31
  - Returns a pointer to the allocated storage if the attempt is
32
  successful. Otherwise, if the current
33
  `new_handler` ([[get.new.handler]]) is a null pointer value, throws
34
  `bad_alloc`.
35
  - Otherwise, the function calls the current `new_handler`
 
38
  - The loop terminates when an attempt to allocate the requested storage
39
  is successful or when a called `new_handler` function does not return.
40
 
41
  ``` cpp
42
  void* operator new(std::size_t size, const std::nothrow_t&) noexcept;
43
+ void* operator new(std::size_t size, std::align_val_t alignment, const std::nothrow_t&) noexcept;
44
  ```
45
 
46
+ *Effects:* Same as above, except that these are called by a placement
47
  version of a *new-expression* when a C++program prefers a null pointer
48
  result as an error indication, instead of a `bad_alloc` exception.
49
 
50
+ *Replaceable:* A C++program may define functions with either of these
51
+ function signatures, and thereby displace the default versions defined
52
+ by the C++standard library.
53
 
54
  *Required behavior:* Return a non-null pointer to suitably aligned
55
+ storage ([[basic.stc.dynamic]]), or else return a null pointer. Each of
56
+ these nothrow versions of `operator new` returns a pointer obtained as
57
+ if acquired from the (possibly replaced) corresponding non-placement
58
+ function. This requirement is binding on any replacement versions of
59
+ these functions.
60
 
61
+ *Default behavior:* Calls `operator new(size)`, or
62
+ `operator new(size, alignment)`, respectively. If the call returns
63
  normally, returns the result of that call. Otherwise, returns a null
64
  pointer.
65
 
66
+ [*Example 1*:
67
+
68
  ``` cpp
69
  T* p1 = new T; // throws bad_alloc if it fails
70
  T* p2 = new(nothrow) T; // returns nullptr if it fails
71
  ```
72
 
73
+ — *end example*]
74
+
75
  ``` cpp
76
  void operator delete(void* ptr) noexcept;
77
  void operator delete(void* ptr, std::size_t size) noexcept;
78
+ void operator delete(void* ptr, std::align_val_t alignment) noexcept;
79
+ void operator delete(void* ptr, std::size_t size, std::align_val_t alignment) noexcept;
80
  ```
81
 
82
+ *Effects:* The deallocation
83
+ functions ([[basic.stc.dynamic.deallocation]]) called by a
84
  *delete-expression* to render the value of `ptr` invalid.
85
 
86
+ *Replaceable:* A C++program may define functions with any of these
87
+ function signatures, and thereby displace the default versions defined
88
+ by the C++standard library.
 
 
 
 
 
 
89
 
90
+ If a function without a `size` parameter is defined, the program should
91
+ also define the corresponding function with a `size` parameter. If a
92
+ function with a `size` parameter is defined, the program shall also
93
+ define the corresponding version without the `size` parameter.
94
+
95
+ [*Note 1*: The default behavior below may change in the future, which
96
+ will require replacing both deallocation functions when replacing the
97
+ allocation function. — *end note*]
98
+
99
+ *Requires:* `ptr` shall be a null pointer or its value shall represent
100
+ the address of a block of memory allocated by an earlier call to a
101
+ (possibly replaced) `operator new(std::size_t)` or
102
+ `operator new(std::size_t, std::align_val_t)` which has not been
103
+ invalidated by an intervening call to `operator delete`.
104
 
105
  *Requires:* If an implementation has strict pointer
106
  safety ([[basic.stc.dynamic.safety]]) then `ptr` shall be a
107
  safely-derived pointer.
108
 
109
+ *Requires:* If the `alignment` parameter is not present, `ptr` shall
110
+ have been returned by an allocation function without an `alignment`
111
+ parameter. If present, the `alignment` argument shall equal the
112
+ `alignment` argument passed to the allocation function that returned
113
+ `ptr`. If present, the `size` argument shall equal the `size` argument
114
+ passed to the allocation function that returned `ptr`.
115
 
116
+ *Required behavior:* A call to an `operator delete` with a `size`
117
+ parameter may be changed to a call to the corresponding
118
+ `operator delete` without a `size` parameter, without affecting memory
119
+ allocation.
120
+
121
+ [*Note 2*: A conforming implementation is for
122
  `operator delete(void* ptr, std::size_t size)` to simply call
123
+ `operator delete(ptr)`. — *end note*]
124
 
125
+ *Default behavior:* The functions that have a `size` parameter forward
126
+ their other parameters to the corresponding function without a `size`
127
+ parameter.
128
+
129
+ [*Note 3*: See the note in the above *Replaceable:*
130
+ paragraph. — *end note*]
131
 
132
  *Default behavior:* If `ptr` is null, does nothing. Otherwise, reclaims
133
  the storage allocated by the earlier call to `operator new`.
134
 
135
  *Remarks:* It is unspecified under what conditions part or all of such
136
  reclaimed storage will be allocated by subsequent calls to
137
+ `operator new` or any of `aligned_alloc`, `calloc`, `malloc`, or
138
+ `realloc`, declared in `<cstdlib>`.
139
 
140
  ``` cpp
141
  void operator delete(void* ptr, const std::nothrow_t&) noexcept;
142
+ void operator delete(void* ptr, std::align_val_t alignment, const std::nothrow_t&) noexcept;
143
  ```
144
 
145
+ *Effects:* The deallocation
146
+ functions ([[basic.stc.dynamic.deallocation]]) called by the
147
  implementation to render the value of `ptr` invalid when the constructor
148
  invoked from a nothrow placement version of the *new-expression* throws
149
  an exception.
150
 
151
+ *Replaceable:* A C++program may define functions with either of these
152
+ function signatures, and thereby displace the default versions defined
153
+ by the C++standard library.
154
+
155
+ *Requires:* `ptr` shall be a null pointer or its value shall represent
156
+ the address of a block of memory allocated by an earlier call to a
157
+ (possibly replaced) `operator new(std::size_t)` or
158
+ `operator new(std::size_t, std::align_val_t)` which has not been
159
+ invalidated by an intervening call to `operator delete`.
 
160
 
161
  *Requires:* If an implementation has strict pointer
162
  safety ([[basic.stc.dynamic.safety]]) then `ptr` shall be a
163
  safely-derived pointer.
164
 
165
+ *Requires:* If the `alignment` parameter is not present, `ptr` shall
166
+ have been returned by an allocation function without an `alignment`
167
+ parameter. If present, the `alignment` argument shall equal the
168
+ `alignment` argument passed to the allocation function that returned
169
+ `ptr`.
170
 
171
+ *Default behavior:* Calls `operator delete(ptr)`, or
172
+ `operator delete(ptr, alignment)`, respectively.
 
 
 
 
 
 
 
 
 
 
 
173