20 General utilities library [utilities]

20.10 Memory [memory]

20.10.5 Pointer safety [util.dynamic.safety]

1
#
A complete object is declared reachable while the number of calls to declare_­reachable with an argument referencing the object exceeds the number of calls to undeclare_­reachable with an argument referencing the object.
🔗
void declare_reachable(void* p);
2
#
Preconditions: p is a safely-derived pointer ([basic.stc.dynamic.safety]) or a null pointer value.
3
#
Effects: If p is not null, the complete object referenced by p is subsequently declared reachable ([basic.stc.dynamic.safety]).
4
#
Throws: May throw bad_­alloc if the system cannot allocate additional memory that may be required to track objects declared reachable.
🔗
template<class T> T* undeclare_reachable(T* p);
5
#
Preconditions: If p is not null, the complete object referenced by p has been previously declared reachable, and is live ([basic.life]) from the time of the call until the last undeclare_­reachable(p) call on the object.
6
#
Returns: A safely derived copy of p which compares equal to p.
7
#
Throws: Nothing.
8
#
[Note 1:
It is expected that calls to declare_­reachable(p) consume a small amount of memory in addition to that occupied by the referenced object until the matching call to undeclare_­reachable(p) is encountered.
Thus, long-running programs where calls are not matched can exhibit a memory leak.
— end note]
🔗
void declare_no_pointers(char* p, size_t n);
9
#
Preconditions: No bytes in the specified range are currently registered with declare_­no_­pointers().
If the specified range is in an allocated object, then it is entirely within a single allocated object.
The object is live until the corresponding undeclare_­no_­pointers() call.
[Note 2:
In a garbage-collecting implementation, the fact that a region in an object is registered with declare_­no_­pointers() does not prevent the object from being collected.
— end note]
10
#
Effects: The n bytes starting at p no longer contain traceable pointer locations, independent of their type.
Hence indirection through a pointer located there is undefined if the object it points to was created by global operator new and not previously declared reachable.
[Note 3:
This can be used to inform a garbage collector or leak detector that this region of memory need not be traced.
— end note]
11
#
Throws: Nothing.
12
#
[Note 4:
The request can be ignored if a memory allocation needed by the implementation fails.
— end note]
🔗
void undeclare_no_pointers(char* p, size_t n);
13
#
Preconditions: The same range has previously been passed to declare_­no_­pointers().
14
#
Effects: Unregisters a range registered with declare_­no_­pointers() for destruction.
It shall be called before the lifetime of the object ends.
15
#
Throws: Nothing.
🔗
pointer_safety get_pointer_safety() noexcept;
16
#
Returns: pointer_­safety​::​strict if the implementation has strict pointer safety.
It is implementation-defined whether get_­pointer_­safety returns pointer_­safety​::​relaxed or pointer_­safety​::​preferred if the implementation has relaxed pointer safety.214
214)214)
pointer_­safety​::​preferred can be returned to indicate that a leak detector is running so that the program can avoid spurious leak reports.