Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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 for-
       eign 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  de-
       stroyed.

	  inout_ptr_t  behaves	as  if it holds	following non-static data mem-
       bers:

	    * 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 ex-
       posed 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  specializa-
       tion.

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 forbid-
       den.

	  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 pro-
       duce 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   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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::inout_ptr_t&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help