# std::inout_ptr_t

From cppreference.com
< cpp‎ | memory

Defined in header `<memory>` |  |
template< class Smart, class Pointer, class... Args > class inout_ptr_t; |  | (since C++23)

`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) (C++23) | constructs an `inout_ptr_t` (public member function)
operator= [deleted](C++23) | `inout_ptr_t` is not assignable (public member function)
(destructor) (C++23) | resets the adapted smart pointer after releasing its ownership (public member function)
operator Pointer*operator void** (C++23) | converts the `inout_ptr_t` to the address of the storage for output (public member function)

### Non-member functions

inout_ptr (C++23) | creates an `inout_ptr_t` with an associated smart pointer and resetting 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 (C++23) | interoperates with foreign pointer setters and resets a smart pointer on destruction (class template)
unique_ptr (C++11) | smart pointer with unique object ownership semantics (class template)
shared_ptr (C++11) | smart pointer with shared object ownership semantics (class template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/memory/inout_ptr_t&oldid=170143"