[util.dynamic.safety] (original) (raw)

20 General utilities library [utilities]

20.10 Memory [memory]

20.10.5 Pointer safety [util.dynamic.safety]

A complete object is declared reachable while the number of calls todeclare_­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);

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);

Preconditions:If p is not null, the complete object referenced by phas been previously declared reachable, and is live ([basic.life]) from the time of the call until the lastundeclare_­reachable(p) call on the object.

Returns:A safely derived copy of p which compares equal to p.

[ 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);

Preconditions:No bytes in the specified range are currently registered withdeclare_­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

:

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

]

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

]

[ 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);

Preconditions:The same range has previously been passed to declare_­no_­pointers().

Effects:Unregisters a range registered with declare_­no_­pointers() for destruction.

It shall be called before the lifetime of the object ends.

pointer_safety get_pointer_safety() noexcept;

It isimplementation-defined whetherget_­pointer_­safety returns pointer_­safety​::​relaxed orpointer_­safety​::​preferred if the implementation has relaxed pointer safety.219