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

FreeBSD Manual Pages

  
 
  

home | help 
std::out_ptr_t(3)	      C++ Standard Libary	     std::out_ptr_t(3)

NAME
       std::out_ptr_t -	std::out_ptr_t

Synopsis
	  Defined in header <memory>
	  template< class Smart, class Pointer,	class... Args >	 (since	C++23)
	  class	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**
	  parameter.

	  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 object with the result and	the captured arguments
       when it is
	  destroyed.

	  out_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 ex-
       posed to	a
	      foreign function for re-initialization.

	  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
		    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  specializa-
       tion 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
	  constructor	    constructs an out_ptr_t
	  (C++23)	    (public member function)
	  operator=	    out_ptr_t is not assignable
	  [deleted](C++23)  (public member function)
	  destructor	    resets the adapted smart pointer
	  (C++23)	    (public member function)
	  operator Pointer* converts the out_ptr_t to the address of the stor-
       age for output
	  operator void**   (public member function)
	  (C++23)

Non-member functions
	  out_ptr  creates  an	out_ptr_t with an associated smart pointer and
       resetting
	  (C++23) 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_set-
       ter(T**); and
	  std::unique_ptr<T, D>	up; respectively,

	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 du-
       ration other than
	  automatic  storage  duration,	because	such code is likely to produce
       dangling
	  references and result	in undefined behavior on destruction.

	  out_ptr_t forbids the	usage that would reset a std::shared_ptr with-
       out specifying a
	  deleter, because it would call std::shared_ptr::reset	and replace  a
       custom deleter
	  later.

	  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
	  inout_ptr_t interoperates with foreign pointer setters, obtains  the
       initial pointer
	  (C++23)     value from a smart pointer, and resets it	on 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::out_ptr_t(3)

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

home | help