std::inout_ptr_t

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros (C++20) Dynamic memory management Program utilities Coroutine support (C++20) Variadic functions is_constant_evaluated (C++20) is_within_lifetime (C++26) initializer_list (C++11) source_location (C++20) Three-way comparison three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

General utilities Date and time Function objects Formatting library (C++20)   bitset hash (C++11) Relational operators (deprecated in C++20) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23) Elementary string conversions to_chars (C++17) from_chars (C++17) chars_format (C++17) to_chars_result (C++17) from_chars_result (C++17)

 

Dynamic memory management

Uninitialized memory algorithms uninitialized_copy uninitialized_fill uninitialized_move (C++17) uninitialized_default_construct (C++17) uninitialized_value_construct (C++17) destroy (C++17) destroy_at (C++17) voidify (C++20) uninitialized_copy_n (C++11) uninitialized_fill_n uninitialized_move_n (C++17) uninitialized_default_construct_n (C++17) uninitialized_value_construct_n (C++17) destroy_n (C++17) construct_at (C++20) Constrained uninitialized memory algorithms ranges::uninitialized_copy (C++20) ranges::uninitialized_fill (C++20) ranges::uninitialized_move (C++20) ranges::construct_at (C++20) ranges::destroy (C++20) ranges::destroy_n (C++20) ranges::destroy_at (C++20) ranges::uninitialized_copy_n (C++20) ranges::uninitialized_fill_n (C++20) ranges::uninitialized_move_n (C++20) ranges::uninitialized_default_construct (C++20) ranges::uninitialized_value_construct (C++20) ranges::uninitialized_default_construct_n (C++20)   ranges::uninitialized_value_construct_n (C++20) Allocators allocator allocator_traits (C++11) allocation_result (C++23) allocator_arg (C++11) uses_allocator (C++11) uses_allocator_construction_args (C++20) make_obj_using_allocator (C++20) uninitialized_construct_using_allocator (C++20) scoped_allocator_adaptor (C++11) pmr::polymorphic_allocator (C++17) Memory resources pmr::memory_resource (C++17) pmr::get_default_resource (C++17) pmr::set_default_resource (C++17) pmr::new_delete_resource (C++17) pmr::null_memory_resource (C++17) pmr::synchronized_pool_resource (C++17) pmr::unsynchronized_pool_resource (C++17)   pmr::monotonic_buffer_resource (C++17) pmr::pool_options (C++17) Garbage collection support declare_reachable (C++11)(until C++23) undeclare_reachable (C++11)(until C++23) declare_no_pointers (C++11)(until C++23) undeclare_no_pointers (C++11)(until C++23) pointer_safety (C++11)(until C++23) get_pointer_safety (C++11)(until C++23) Uninitialized storage raw_storage_iterator (until C++20*) get_temporary_buffer (until C++20*) return_temporary_buffer (until C++20*) Explicit lifetime management start_lifetime_asstart_lifetime_as_array (C++23)(C++23)

Smart pointers unique_ptr (C++11) shared_ptr (C++11) weak_ptr (C++11) auto_ptr (until C++17*) owner_less (C++11) owner_less<void> (C++17) owner_hash (C++26) owner_equal (C++26) enable_shared_from_this (C++11) bad_weak_ptr (C++11) default_delete (C++11) out_ptr_t (C++23) inout_ptr_t (C++23) Low level memory management operator new operator new[] operator delete operator delete[] get_new_handler (C++11) set_new_handler launder (C++17) bad_alloc bad_array_new_length (C++11) nothrow_t align_val_t (C++17) destroying_delete_t (C++20) new_handler nothrow Miscellaneous pointer_traits (C++11) to_address (C++20) addressof (C++11) align (C++11) assume_aligned (C++20) C Library malloc calloc realloc    aligned_alloc (C++17) free

 

std::inout_ptr_t

Member functions

inout_ptr_t::inout_ptr_t

inout_ptr_t::~inout_ptr_t

inout_ptr_t::operator Pointer*inout_ptr_t::operator void**

Non-member functions

inout_ptr

 

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

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)