std::inout_ptr_t(3) | C++ Standard Libary | std::inout_ptr_t(3) |
NAME¶
std::inout_ptr_t - std::inout_ptr_t
Synopsis¶
Defined in header <memory>
template< class Smart, class Pointer, class... Args > (since C++23)
class inout_ptr_t;
inout_ptr_t is used to adapt types such as smart pointers for foreign
functions that
reset ownership via a Pointer* (usually T** for some object type T) or void**
parameter.
inout_ptr_t captures additional arguments on construction, provides a storage
for
the result which such an aforementioned foreign function accesses, releases
the
ownership held by the adapted Smart object, and finally resets the adapted
Smart
object with the result and the captured arguments when it is destroyed.
inout_ptr_t behaves as if it holds following non-static data members:
* a Smart& reference, which is bound to the adapted object on
construction,
* for every T in Args..., a member of type T, which is an argument captured
on
construction and used for resetting while destruction, and
* a member subobject that suitable for storing a Pointer within it and
providing a
void* object, where the Pointer or void* object is generally exposed to a
foreign function for ownership resetting.
If Smart is not a pointer type, release() is called at most once on the
adapted
object. Implementations may call release() within constructor, or before
resetting
within destructor if the Pointer value is not null.
Users can control whether each argument for resetting is captured by copy or
by
reference, by specifying an object type or a reference type in Args...
respectively.
Template parameters¶
Smart - the type of the object (typically a smart pointer) to
adapt
Pointer - type of the object (typically a raw pointer) to which a foreign
function
accesses for ownership resetting
Args... - type of captured arguments used for resetting the adapted
object
Type requirements¶
-
Pointer must meet the requirements of NullablePointer.
-
The program is ill-formed if Smart is a std::shared_ptr specialization.
Specializations¶
Unlike most class templates in the standard library,
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.
This license allows a program-defined specialization to expose the raw
pointer
stored within a non-standard smart pointer to foreign functions.
Member functions¶
constructor constructs an inout_ptr_t
(C++23) (public member function)
operator= inout_ptr_t is not assignable
[deleted](C++23) (public member function)
destructor resets the adapted smart pointer after releasing its ownership
(C++23) (public member function)
operator Pointer* converts the inout_ptr_t to the address of the storage for
output
operator void** (public member function)
(C++23)
Non-member functions¶
inout_ptr creates an inout_ptr_t with an associated smart pointer
and resetting
(C++23) arguments
(function template)
Notes¶
inout_ptr_t expects that the foreign functions release the
ownership represented by
the value of the pointed-to Pointer, and then re-initialize it. As such
operation
requires unique ownership, the usage with std::shared_ptr is forbidden.
The typical usage of inout_ptr_t is creating its temporary objects by
std::inout_ptr, which resets the adapted smart pointer immediately. E.g.
given a
setter function and a smart pointer of appropriate type declared with int
foreign_resetter(T**); and std::unique_ptr<T, D> up; respectively,
if (int ec = foreign_resetter(std::inout_ptr(up)))
return ec;
is roughly equivalent to
T *raw_p = up.get();
up.release();
int ec = foreign_resetter(&raw_p);
up.reset(raw_p);
if (ec != 0)
return ec;
It is not recommended to create an inout_ptr_t object of a storage duration
other
than automatic storage duration, because such code is likely to produce
dangling
references and result in undefined behavior on destruction.
Captured arguments are typically packed into a std::tuple<Args...>.
Implementations
may use different mechanism to provide the Pointer or void* object they need
hold.
Feature-test macro Value Std Feature
__cpp_lib_out_ptr 202106L (C++23) std::out_ptr, std::inout_ptr
202311L (C++26) freestanding std::out_ptr and std::inout_ptr
Example¶
This section is incomplete
Reason: no example
See also¶
out_ptr_t interoperates with foreign pointer setters and resets a
smart pointer on
(C++23) destruction
(class template)
unique_ptr smart pointer with unique object ownership semantics
(C++11) (class template)
shared_ptr smart pointer with shared object ownership semantics
(C++11) (class template)
Category:¶
* Todo no example
2024.06.10 | http://cppreference.com |