23 General utilities library [utilities]

23.10 Memory [memory]

23.10.4 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
#
Requires: p shall be 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
#
Requires: If p is not null, the complete object referenced by p shall have been previously declared reachable, and shall be 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 shall compare equal to p.
7
#
Throws: Nothing.
8
#
[ Note
:
It is expected that calls to declare_­reachable(p) will 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.
Long running programs should arrange that calls are matched.
— end note
 ]
void declare_no_pointers(char* p, size_t n);
9
#
Requires: No bytes in the specified range are currently registered with declare_­no_­pointers().
If the specified range is in an allocated object, then it must be entirely within a single allocated object.
The object must be live until the corresponding undeclare_­no_­pointers() call.
[ Note
:
In a garbage-collecting implementation, the fact that a region in an object is registered with declare_­no_­pointers() should 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
:
This may 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
:
Under some conditions implementations may need to allocate memory.
However, the request can be ignored if memory allocation fails.
— end note
 ]
void undeclare_no_pointers(char* p, size_t n);
13
#
Requires: The same range must previously have been passed to declare_­no_­pointers().
14
#
Effects: Unregisters a range registered with declare_­no_­pointers() for destruction.
It must 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 ([basic.stc.dynamic.safety]).
It is implementation-defined whether get_­pointer_­safety returns pointer_­safety​::​relaxed or pointer_­safety​::​preferred if the implementation has relaxed pointer safety.221
221)
pointer_­safety​::​preferred might be returned to indicate that a leak detector is running so that the program can avoid spurious leak reports.