std::out_ptr_t

out_ptr_t is used to adapt types such as smart pointers for foreign functions that output their results via a Pointer* (usually T** for some object type T) or void**

out_ptr_t captures additional arguments on construction, provides storage for the result to which such an aforementioned foreign function writes, and finally resets the adapted Smart

out_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*

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

Specializations

Unlike most class templates in the standard library, program-defined specializations of out_ptr_t that depend on at least one program-defined type

This license allows a program-defined specialization to expose the raw pointer stored within a non-standard smart pointer to foreign functions.

Member functions

Non-member functions

Notes

out_ptr_t expects that the foreign functions do not used the value of the pointed-to Pointer, and only re-initialize it. The value of the smart pointer before adaption is not used.

The typical usage of out_ptr_t is creating its temporary objects by std::out_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_setter(T**); and std::unique_ptr<T, D> up;

int foreign_setter(T**);
std::unique_ptr<T, D> up;
 
if (int ec = foreign_setter(std::out_ptr(up)))
    return ec;

is roughly equivalent to

int foreign_setter(T**);
std::unique_ptr<T, D> up;
T* raw_p{};
 
int ec = foreign_setter(&raw_p);
up.reset(raw_p);
if (ec != 0)
    return ec;

It is not recommended to create an out_ptr_t object of a storage duration

out_ptr_t forbids the usage that would reset a std::shared_ptr without specifying a deleter, because it would call std::shared_ptr::reset

Captured arguments are typically packed into a std::tuple <Args...> . Implementations may use different mechanism to provide the Pointer or void*

Example

See also