Base class for wrapping any handle. More...

Inheritance diagram for dqcsim::wrap::Handle:

Public Member Functions
	Handle () noexcept
	Constructs an empty wrapper. More...

	Handle (HandleIndex handle) noexcept
	Wraps the given raw handle. More...

virtual	~Handle () noexcept
	Delete the handle and its wrapper.

void	free ()
	Explicitly delete the handle, allowing errors to be caught. More...

bool	is_valid () const noexcept
	Returns whether this wrapper (still) contains a valid handle. More...

HandleIndex	get_handle () const noexcept
	Returns the raw handle without relinquishing ownership. More...

HandleIndex	take_handle () noexcept
	Returns the raw handle and relinquishes ownership. More...

	Handle (const Handle &)=delete

void	operator= (const Handle &)=delete

	Handle (Handle &&src)
	Move constructor; simply moves ownership of the handle from the source object to the constructed object. More...

Handle &	operator= (Handle &&src)
	Move constructor; simply moves ownership of the handle from the source object to the assignment target. More...

std::string	dump () const
	Returns a string containing a debug dump of the handle. More...

HandleType	type () const
	Returns the type of this handle. More...

Protected Attributes
HandleIndex	handle
	The wrapped handle.

Friends
std::ostream &	operator<< (std::ostream &out, const Handle &handle)
	Write the debug dump string of the handle to the given output stream. More...

Detailed Description

Base class for wrapping any handle.

This class ensures that the wrapped handle is freed when it is destroyed, preventing memory leaks. You can also free the handle before destruction, which allows any errors reported by DQCsim to be caught. You can take back ownership of the handle using take_handle, preventing it from being freed at destruction.

Only one Handle should wrap a single handle at a time. Since handles cannot typically be cloned, this class is not copy constructible or assignable. If you need it to be, consider wrapping the Handle in a std::shared_ptr.

Warning: Handle objects can not and should never be passed between threads. The wrapped C API handles are thread local can cannot be moved between threads, therefore this wrapper can't either. Trying to do so anyway is undefined behavior and will absolutely not work! If you need to move data between threads, copy the data represented by the handle into C++ variables, pass those over, and reconstruct the handle from them in the destination thread.

Definition at line 1618 of file dqcsim.

Constructor & Destructor Documentation

◆ Handle() [1/3]

dqcsim::wrap::Handle::Handle ( )

inlinenoexcept

Constructs an empty wrapper.

Note: The only way to use a wrapper constructed this way is to move a handle into it using the move assignment operator.

Definition at line 1634 of file dqcsim.

◆ Handle() [2/3]

dqcsim::wrap::Handle::Handle ( HandleIndex handle )

inlinenoexcept

Wraps the given raw handle.

Note: This class will take ownership of the handle, i.e. it is in charge of freeing it.

Parameters

handle The raw handle to wrap.

Definition at line 1645 of file dqcsim.

◆ Handle() [3/3]

dqcsim::wrap::Handle::Handle ( Handle && src )

inline

Move constructor; simply moves ownership of the handle from the source object to the constructed object.

Note: The source wrapper no longer owns a handle after this call. That means that its is_valid will return false and all other methods will likely fail. Note that using an object after moving it is explicitly undefined behavior in the C++ specification, so you shouldn't be using it anymore anyway.

Parameters

src	The handle wrapper to move from.

Definition at line 1726 of file dqcsim.

Member Function Documentation

◆ free()

void dqcsim::wrap::Handle::free ( )

inline

Explicitly delete the handle, allowing errors to be caught.

Note: The wrapper no longer owns a handle after this call. That means is_valid will return false and all other methods will likely fail.

Exceptions

std::runtime_error When deletion of the handle fails for some reason.

Definition at line 1668 of file dqcsim.

◆ is_valid()

bool dqcsim::wrap::Handle::is_valid ( ) const

inlinenoexcept

Returns whether this wrapper (still) contains a valid handle.

Returns: Whether this wrapper (still) contains a valid handle.

Definition at line 1678 of file dqcsim.

◆ get_handle()

HandleIndex dqcsim::wrap::Handle::get_handle ( ) const

inlinenoexcept

Returns the raw handle without relinquishing ownership.

Returns: The wrapped raw handle, or 0 if no handle was attached.

Definition at line 1691 of file dqcsim.

◆ take_handle()

HandleIndex dqcsim::wrap::Handle::take_handle ( )

inlinenoexcept

Returns the raw handle and relinquishes ownership.

Note: The wrapper no longer owns a handle after this call. That means is_valid will return false and all other methods will likely fail.

Returns: The wrapped raw handle, or 0 if no handle was attached.

Definition at line 1703 of file dqcsim.

◆ operator=()

Handle& dqcsim::wrap::Handle::operator= ( Handle && src )

inline

Move constructor; simply moves ownership of the handle from the source object to the assignment target.

Note: If the assignment target wrapper already contained a handle, it is implicitly freed.; The source wrapper no longer owns a handle after this call. That means that its is_valid will return false and all other methods will likely fail. Note that using an object after moving it is explicitly undefined behavior in the C++ specification, so you shouldn't be using it anymore anyway.

Parameters

src	The handle wrapper to move from.

Returns: A reference to the destination handle.

Exceptions

std::runtime_error When the destination already wrapped a handle, and freeing that handle failed.

Definition at line 1748 of file dqcsim.

◆ dump()

std::string dqcsim::wrap::Handle::dump ( ) const

inline

Returns a string containing a debug dump of the handle.

The string uses newlines and indentation to improve readability. It does not end in a newline.

Warning: Debug dumps are not guaranteed to be the same from DQCsim version to version. They should only be used for debugging.

Returns: A debug dump of the current handle.

Exceptions

std::runtime_error When the currently wrapped handle is invalid.

Definition at line 1770 of file dqcsim.

◆ type()

HandleType dqcsim::wrap::Handle::type ( ) const

inline

Returns the type of this handle.

Returns: The handle type for the currently wrapped handle.

Exceptions

std::runtime_error When the current handle is invalid.

Definition at line 1799 of file dqcsim.

Friends And Related Function Documentation

◆ operator<<

std::ostream& operator<<	(	std::ostream &	out,
		const Handle &	handle
	)

friend

Write the debug dump string of the handle to the given output stream.

Newlines and indentation are used to improve readability. However, there is implicit trailing std::endl.

Parameters

out	The output stream to write to.
handle	The handle to dump.

Returns: The output stream object.

Exceptions

std::runtime_error When the given handle is invalid.

Definition at line 1788 of file dqcsim.

The documentation for this class was generated from the following file:

dqcsim

Public Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Handle() [1/3]

◆ Handle() [2/3]

◆ Handle() [3/3]

Member Function Documentation

◆ free()

◆ is_valid()

◆ get_handle()

◆ take_handle()

◆ operator=()

◆ dump()

◆ type()

Friends And Related Function Documentation

◆ operator<<