Difference between revisions of "cpp/memory/out ptr t"
(+ capture by copy/reference) |
m |
||
| Line 8: | Line 8: | ||
{{tt|out_ptr_t}} is used to adapt types such as smart pointers for foreign functions that output their results via a {{c|Pointer*}} (usually {{c|T**}} for some object type {{tt|T}}) or {{c|void**}} parameter. | {{tt|out_ptr_t}} is used to adapt types such as smart pointers for foreign functions that output their results via a {{c|Pointer*}} (usually {{c|T**}} for some object type {{tt|T}}) or {{c|void**}} parameter. | ||
| − | {{tt|out_ptr_t}} captures additional arguments on construction, provides a storage for the result to which such an aforementioned foreign function writes, and finally resets the adapted {{tt|Smart}} object with the result and the captured arguments when it is destroyed. | + | {{tt|out_ptr_t}} captures additional arguments on construction, provides a storage for the result to which such an aforementioned foreign function writes, and finally resets the adapted {{tt|Smart}} object with the result and the captured arguments when it is destroyed. |
The arguments for resetting are equivalently stored into a {{c|std::tuple<Args...>}} member subobject, i.e. an argument is captured by copy if the corresponding type in {{tt|Args...}} is an object type, or captured by reference if the type is a reference type. | The arguments for resetting are equivalently stored into a {{c|std::tuple<Args...>}} member subobject, i.e. an argument is captured by copy if the corresponding type in {{tt|Args...}} is an object type, or captured by reference if the type is a reference type. | ||
Revision as of 23:30, 15 June 2021
| Defined in header <memory>
|
||
| template< class Smart, class Pointer, class... Args > class out_ptr_t; |
(since C++23) | |
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** parameter.
out_ptr_t captures additional arguments on construction, provides a storage for the result to which such an aforementioned foreign function writes, and finally resets the adapted Smart object with the result and the captured arguments when it is destroyed.
The arguments for resetting are equivalently stored into a std::tuple<Args...> member subobject, i.e. an argument is captured by copy if the corresponding type in Args... is an object type, or captured by reference if the type is a reference type.
Contents |
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 writes its result |
| 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 and sizeof...(Args) == 0.
| ||
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 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
| (C++23) |
constructs an out_ptr_t (public member function) |
| operator= [deleted](C++23) |
out_ptr_t is not assignable (public member function) |
| (C++23) |
resets the adapted smart pointer (public member function) |
converts the out_ptr_t to the address of the storage for output (public member function) |
Non-member functions
| (C++23) |
creates an out_ptr_t with an associated smart pointer and resetting arguments (function template) |
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; respectively,
if (int ec = foreign_setter(std::out_ptr(up)) { return ec; }
is roughly equivalent to
T *raw_p{}; int ec = foreign_setter(&raw_p); up.reset(raw_p); if (ec != 0) { return ec; }
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 and replace a custom deleter later.
Example
| This section is incomplete Reason: no example |
See also
| (C++23) |
interoperates with foreign pointer setters, obtains the initial pointer value from a smart pointer, and resets it on destruction (class template) |
| (C++11) |
smart pointer with unique object ownership semantics (class template) |
| (C++11) |
smart pointer with shared object ownership semantics (class template) |
