20 General utilities library [utilities]

20.11 Smart pointers [smartptr]

20.11.4 Smart pointer adaptors [smartptr.adapt]

20.11.4.1 Class template out_­ptr_­t [out.ptr.t]

1
#
out_­ptr_­t is a class template used to adapt types such as smart pointers ([smartptr]) for functions that use output pointer parameters.
2
#
[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 }; }
3
#
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]
4
#
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.
5
#
Evaluations of the conversion functions on the same object may conflict ([intro.races]).
🔗
explicit out_ptr_t(Smart& smart, Args... args);
6
#
Effects: Initializes s with smart, a with std​::​forward<Args>(args)..., and value-initializes p.
7
#
[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();
8
#
Let SP be POINTER_­OF_­OR(Smart, Pointer) ([memory.general]).
9
#
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;
10
#
Preconditions: operator void**() has not been called on *this.
11
#
Returns: addressof(const_­cast<Pointer&>(p)).
🔗
operator void**() const noexcept;
12
#
Constraints: is_­same_­v<Pointer, void*> is false.
13
#
Mandates: is_­pointer_­v<Pointer> is true.
14
#
Preconditions: operator Pointer*() has not been called on *this.
15
#
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.
16
#
Remarks: Accessing *v outside the lifetime of *this has undefined behavior.
17
#
[Note 3:
reinterpret_­cast<void**>(static_­cast<Pointer*>(*this)) can be a viable implementation strategy for some implementations.
— end note]

20.11.4.2 Function template out_­ptr [out.ptr]

🔗
template<class Pointer = void, class Smart, class... Args> auto out_ptr(Smart& s, Args&&... args);
1
#
Let P be Pointer if is_­void_­v<Pointer> is false, otherwise POINTER_­OF(Smart).
2
#
Returns: out_­ptr_­t<Smart, P, Args&&...>(s, std​::​forward<Args>(args)...)

20.11.4.3 Class template inout_­ptr_­t [inout.ptr.t]

1
#
inout_­ptr_­t is a class template used to adapt types such as smart pointers ([smartptr]) for functions that use output pointer parameters whose dereferenced values may first be deleted before being set to another allocated value.
2
#
[Example 1: #include <memory> struct star_fish* star_fish_alloc(); int star_fish_populate(struct star_fish** ps, const char* description); struct star_fish_deleter { void operator() (struct star_fish* c) const noexcept; }; using star_fish_ptr = std::unique_ptr<star_fish, star_fish_deleter>; int main(int, char*[]) { star_fish_ptr peach(star_fish_alloc()); // ... // used, need to re-make int err = star_fish_populate(std::inout_ptr(peach), "caring clown-fish liker"); return err; }
A unique_­ptr can be used with inout_­ptr to be passed into an output pointer-style function.
The original value will be properly deleted according to the function it is used with and a new value reset in its place.
— end example]
🔗
namespace std { template<class Smart, class Pointer, class... Args> class inout_ptr_t { public: explicit inout_ptr_t(Smart&, Args...); inout_ptr_t(const inout_ptr_t&) = delete; ~inout_ptr_t(); operator Pointer*() const noexcept; operator void**() const noexcept; private: Smart& s; // exposition only tuple<Args...> a; // exposition only Pointer p; // exposition only }; }
3
#
Pointer shall meet the Cpp17NullablePointer requirements.
If Smart is a specialization of shared_­ptr, the program is ill-formed.
[Note 1:
It is impossible to properly acquire unique ownership of the managed resource from a shared_­ptr given its shared ownership model.
— end note]
4
#
Program-defined specializations of inout_­ptr_­t that depend on at least one program-defined type need not meet the requirements for the primary template.
5
#
Evaluations of the conversion functions on the same object may conflict ([intro.races]).
🔗
explicit inout_ptr_t(Smart& smart, Args... args);
6
#
Effects: Initializes s with smart, a with std​::​forward<Args>(args)..., and p to either
  • (6.1)
    smart if is_­pointer_­v<Smart> is true,
  • (6.2)
    otherwise, smart.get().
7
#
Remarks: An implementation can call s.release().
8
#
[Note 2:
The constructor is not noexcept to allow for a variety of non-terminating and safe implementation strategies.
For example, an intrusive pointer implementation with a control block can allocate in the constructor and safely fail with an exception.
— end note]
🔗
~inout_ptr_t();
9
#
Let SP be POINTER_­OF_­OR(Smart, Pointer) ([memory.general]).
10
#
Let release-statement be s.release(); if an implementation does not call s.release() in the constructor.
Otherwise, it is empty.
11
#
Effects: Equivalent to:
  • (11.1)
    -- if (p) { apply([&](auto&&... args) { s = Smart( static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a)); } if is_­pointer_­v<Smart> is true;
  • (11.2)
    otherwise, if (p) { apply([&](auto&&... args) { release-statement; 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;
  • (11.3)
    otherwise, if (p) { apply([&](auto&&... args) { release-statement; s = Smart(static_cast<SP>(p), std::forward<Args>(args)...); }, std::move(a)); } if is_­constructible_­v<Smart, SP, Args...> is true;
  • (11.4)
    otherwise, the program is ill-formed.
🔗
operator Pointer*() const noexcept;
12
#
Preconditions: operator void**() has not been called on *this.
13
#
Returns: addressof(const_­cast<Pointer&>(p)).
🔗
operator void**() const noexcept;
14
#
Constraints: is_­same_­v<Pointer, void*> is false.
15
#
Mandates: is_­pointer_­v<Pointer> is true.
16
#
Preconditions: operator Pointer*() has not been called on *this.
17
#
Returns: A pointer value v such that:
  • (17.1)
    the initial value *v is equivalent to static_­cast<void*>(p) and
  • (17.2)
    any modification of *v that is not followed by subsequent modification of *this affects the value of p during the destruction of *this, such that static_­cast<void*>(p) == *v.
18
#
Remarks: Accessing *v outside the lifetime of *this has undefined behavior.
19
#
[Note 3:
reinterpret_­cast<void**>(static_­cast<Pointer*>(*this)) can be a viable implementation strategy for some implementations.
— end note]

20.11.4.4 Function template inout_­ptr [inout.ptr]

🔗
template<class Pointer = void, class Smart, class... Args> auto inout_ptr(Smart& s, Args&&... args);
1
#
Let P be Pointer if is_­void_­v<Pointer> is false, otherwise POINTER_­OF(Smart).
2
#
Returns: inout_­ptr_­t<Smart, P, Args&&...>(s, std​::​forward<Args>(args)...).