20 Memory management library [mem]

20.3 Smart pointers [smartptr]

20.3.4 Smart pointer adaptors [smartptr.adapt]

20.3.4.1 Class template out_ptr_t [out.ptr.t]

out_ptr_t is a class template used to adapt types such as smart pointers ([smartptr]) for functions that use output pointer parameters.

[Example 1:

#include <memory> #include <cstdio> int fopen_s(std::FILE** f, const char* name, const char* mode); struct fclose_deleter { void operator()(std::FILE* f) const noexcept { std::fclose(f); } }; int main(int, char*[]) { constexpr const char* file_name = "ow.o"; std::unique_ptr<std::FILE, fclose_deleter> file_ptr; int err = fopen_s(std::out_ptr<std::FILE*>(file_ptr), file_name, "r+b"); if (err != 0) return 1; // *file_ptr is valid return 0; } unique_ptr can be used with out_ptr to be passed into an output pointer-style function, without needing to hold onto an intermediate pointer value and manually delete it on error or failure.

— end example]

🔗

namespace std { template<class Smart, class Pointer, class... Args> class out_ptr_t { public: explicit out_ptr_t(Smart&, Args...); out_ptr_t(const out_ptr_t&) = delete; ~out_ptr_t(); operator Pointer*() const noexcept; operator void**() const noexcept; private: Smart& s; // exposition only tuple<Args...> a; // exposition only Pointer p; // exposition only }; }

Pointer shall meet the Cpp17NullablePointer requirements.

If Smart is a specialization of shared_ptr and sizeof...(Args) == 0, the program is ill-formed.

[Note 1:

It is typically a user error to reset a shared_ptr without specifying a deleter, as shared_ptr will replace a custom deleter upon usage of reset, as specified in [util.smartptr.shared.mod].

— end note]

Program-defined specializations of out_ptr_t that depend on at least one program-defined type need not meet the requirements for the primary template.

Evaluations of the conversion functions on the same object may conflict ([intro.races]).

🔗

explicit out_ptr_t(Smart& smart, Args... args);

Effects: Initializes s with smart, a with std::forward<Args>(args)..., and value-initializes p.

Then, equivalent to:

(6.1)
s.reset(); if the expression s.reset() is well-formed;
(6.2)
otherwise, s = Smart(); if is_constructible_v<Smart> is true;
(6.3)
otherwise, the program is ill-formed.

[Note 2:

The constructor is not noexcept to allow for a variety of non-terminating and safe implementation strategies.

For example, an implementation can allocate a shared_ptr's internal node in the constructor and let implementation-defined exceptions escape safely.

The destructor can then move the allocated control block in directly and avoid any other exceptions.

— end note]

🔗

~out_ptr_t();

Let SP be POINTER_OF_OR(Smart, Pointer) ([memory.general]).

Effects: Equivalent to:

(9.1)
if (p) { apply([&](auto&&... args) { s.reset(static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a)); } if the expression s.reset(static_cast<SP>(p), std::forward<Args>(args)...) is well-formed;
(9.2)
otherwise, if (p) { apply([&](auto&&... args) { s = Smart(static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a)); } if is_constructible_v<Smart, SP, Args...> is true;
(9.3)
otherwise, the program is ill-formed.

🔗

operator Pointer*() const noexcept;

Preconditions: operator void**() has not been called on *this.

Returns: addressof(const_cast<Pointer&>(p)).

🔗

operator void**() const noexcept;

Constraints: is_same_v<Pointer, void*> is false.

Mandates: is_pointer_v<Pointer> is true.

Preconditions: operator Pointer*() has not been called on *this.

Returns: A pointer value v such that:

(15.1)
the initial value *v is equivalent to static_cast<void*>(p) and
(15.2)
any modification of *v that is not followed by a subsequent modification of *this affects the value of p during the destruction of *this, such that static_cast<void*>(p) == *v.

Remarks: Accessing *v outside the lifetime of *this has undefined behavior.

[Note 3:

reinterpret_cast<void**>(static_cast<Pointer*>(*this)) can be a viable implementation strategy for some implementations.

— end note]