home | help 
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,  re-
     leases 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  con-
     struction,
	  *  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 for-
     eign function
		  accesses for ownership resetting
	Args... - type of captured arguments used for resetting the adapted  ob-
     ject

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 dura-
     tion 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...>. Im-
     plementations
	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

http://cppreference.com 	   2024.06.10		     std::inout_ptr_t(3)
home | help