kanzi::OptionalHandle< T, sentinel, deleter, typename > Class Template Reference

Represents a handle that was created by an external source. More...

#include <kanzi/core/util/handle.hpp>

Inheritance diagram for kanzi::OptionalHandle< T, sentinel, deleter, typename >:

Public Types
using	HandleType
	Alias for this handle type.
using	NativeHandleType
	Alias for the underlying native handle type.

Public Member Functions
KZ_NO_DISCARD optional< T >	createOptional () const noexcept
	Creates a kanzi::optional copy of the native handle.
KZ_NO_DISCARD const T	get () const noexcept
	Provides access to stored handle.
KZ_NO_DISCARD T	get () noexcept
	Provides access to stored handle.
KZ_NO_DISCARD const T	getNativeHandle () const noexcept
	Provides access to stored handle.
KZ_NO_DISCARD T	getNativeHandle () noexcept
	Provides access to stored handle.
KZ_NO_DISCARD bool	hasValue () const noexcept
	Checks if a handle is stored.
KZ_NO_DISCARD	operator bool () const noexcept
	Conversion operator to bool.
KZ_NO_DISCARD T &&	operator* () &&noexcept
	Provides access to stored handle via rvalue reference.
KZ_NO_DISCARD T &	operator* () &noexcept
	Provides access to stored handle via reference.
KZ_NO_DISCARD const T &&	operator* () const &&noexcept
	Provides access to stored handle via const rvalue reference.
KZ_NO_DISCARD const T &	operator* () const &noexcept
	Provides access to stored handle via const reference.
OptionalHandle &	operator= (const OptionalHandle &other)=delete
	Copy assignment operator.
OptionalHandle &	operator= (const T &value)
	Copy assignment operator.
OptionalHandle &	operator= (OptionalHandle &&other) noexcept
	Move assignment operator.
OptionalHandle &	operator= (T &&value) noexcept
	Move assignment operator.
	OptionalHandle () noexcept
	Constructor.
	OptionalHandle (const OptionalHandle &other)=delete
	Copy constructor.
	OptionalHandle (const T &nativeHandle) noexcept
	Constructor.
	OptionalHandle (OptionalHandle &&other) noexcept
	Move constructor.
T	release () noexcept
	Releases ownership of a native handle without destroying the resource.
void	reset () noexcept
	Replaces stored handle with sentinel value.
template<typename U , typename = enable_if_t<is_same_v<T, decay_t<U>>>>
void	reset (U &&newHandle) noexcept
	Stores a new handle inside.
void	swap (OptionalHandle &other)
	Swap function.
KZ_NO_DISCARD optional< T >	toOptional () &&noexcept
	Converts OptionalHandle to kanzi::optional.
	~OptionalHandle ()
	Destructor.

Static Public Member Functions
static constexpr auto	getDeleter () noexcept
	Gets deleter function.
static constexpr T	getSentinel () noexcept
	Gets sentinel value that can be used to represent invalid handle.

Protected Attributes
FlatOptional< T, sentinel >	m_handle
	Native handle that is managed by this class.

Detailed Description

template<typename T, T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>
class kanzi::OptionalHandle< T, sentinel, deleter, typename >

Represents a handle that was created by an external source.

Can hold an invalid handle represented by sentinel value.

The purpose of this class is to hold the external handle and free the associated resources after this class has been destroyed.

For handles that cannot have a sentinel value (every value of T is a valid handle), use Handle instead.

Derive from this class using protected inheritance and use OptionalHandleWrapper to create a wrapper around it.

See also

OptionalHandleWrapper

Example code

class QnxContextMethods : protected OptionalHandle<screen_context_t,
                                                   nullptr,
                                                   screen_destroy_context>
{
public:
    // Domain-specific function.
    KZ_NO_DISCARD optional<size_t> getDisplayCount() const noexcept;
 
protected:
    // Default constructor. Creates invalid handle.
    // Marked as protected to force using it through OptionalHandleWrapper.
    explicit QnxContextMethods() noexcept = default;
 
    // Conctructor from native handle.
    // Marked as protected to force using it through OptionalHandleWrapper.
    explicit QnxContextMethods(const NativeHandleType& handle) noexcept
        : OptionalHandle{ handle }
    {
    }
 
    // "create" is a special factory method that constructs a handle.
    // QnxContext::create() will call QnxContextMethods::create() under the hood.
    // Providing "create" method is not mandatory.
    // Marked as protected to force using it through OptionalHandleWrapper.
    KZ_NO_DISCARD static QnxContextMethods create(int contextFlags) noexcept
    {
        // Return QnxContextMethods object created from native handle.
        return QnxContextMethods{ createScreenContext(contextFlags) };
    }
}
 
class QnxContext : public OptionalHandleWrapper<QnxContext, QnxContextMethods>
{
    using OptionalHandleWrapper::OptionalHandleWrapper;
};
 
// Create QNX context using "create" factory method.
auto qnxContext = QnxContext::create(1);
 
// You can also use constructors defined in QnxContextMethods.
auto qnxContext2 = QnxContext{};
auto qnxContext3 = QnxContext{ reinterpret_cast<QnxContext::NativeHandleType>(1) };
 
// OptionalHandle-related functions can be used safely using operator.().
auto nativeHandle = qnxContext.getNativeHandle();
 
// Domain-specific functions can be used through operator->().
// Always check the value before using such functions.
kzAssert(qnxContext);
auto displayCount = qnxContext->getDisplayCount();

Template Parameters

T	Handle type.
sentinel	Sentinel value that represents invalid handle.
deleter	Deleter function, used for freeing resources that handle represents.

Since

Kanzi 4.0.0

Member Typedef Documentation

NativeHandleType

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

using kanzi::OptionalHandle< T, sentinel, deleter, typename >::NativeHandleType

Alias for the underlying native handle type.

HandleType

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

using kanzi::OptionalHandle< T, sentinel, deleter, typename >::HandleType

Alias for this handle type.

Constructor & Destructor Documentation

OptionalHandle() [1/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

kanzi::OptionalHandle< T, sentinel, deleter, typename >::OptionalHandle ( )

inlineexplicitnoexcept

Constructor.

OptionalHandle() [2/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

kanzi::OptionalHandle< T, sentinel, deleter, typename >::OptionalHandle ( const T & nativeHandle )

inlineexplicitnoexcept

Constructor.

Parameters

nativeHandle

Native handle to store.

~OptionalHandle()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

kanzi::OptionalHandle< T, sentinel, deleter, typename >::~OptionalHandle ( )

inline

Destructor.

OptionalHandle() [3/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

kanzi::OptionalHandle< T, sentinel, deleter, typename >::OptionalHandle ( const OptionalHandle< T, sentinel, deleter, typename > & other )

delete

Copy constructor.

OptionalHandle() [4/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

kanzi::OptionalHandle< T, sentinel, deleter, typename >::OptionalHandle ( OptionalHandle< T, sentinel, deleter, typename > && other )

inlinenoexcept

Move constructor.

Member Function Documentation

operator=() [1/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

OptionalHandle & kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator= ( const OptionalHandle< T, sentinel, deleter, typename > & other )

delete

Copy assignment operator.

operator=() [2/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

OptionalHandle & kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator= ( OptionalHandle< T, sentinel, deleter, typename > && other )

inlinenoexcept

Move assignment operator.

operator=() [3/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

OptionalHandle & kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator= ( const T & value )

inline

Copy assignment operator.

Takes an ownership of the resource.

Parameters

value

Handle to store.

operator=() [4/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

OptionalHandle & kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator= ( T && value )

inlinenoexcept

Move assignment operator.

Takes an ownership of the resource.

Parameters

value

Handle to store.

swap()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

void kanzi::OptionalHandle< T, sentinel, deleter, typename >::swap ( OptionalHandle< T, sentinel, deleter, typename > & other )

inline

Swap function.

Parameters

other

Second object to swap with.

operator*() [1/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD T & kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator* ( ) &

inlinenoexcept

Provides access to stored handle via reference.

Returns

Reference to stored handle.

operator*() [2/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD const T & kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator* ( ) const &

inlinenoexcept

Provides access to stored handle via const reference.

Returns

Const reference to stored handle.

operator*() [3/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD T && kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator* ( ) &&

inlinenoexcept

Provides access to stored handle via rvalue reference.

Returns

Rvalue reference to stored handle.

operator*() [4/4]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD const T && kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator* ( ) const &&

inlinenoexcept

Provides access to stored handle via const rvalue reference.

Returns

Const rvalue reference to stored handle.

hasValue()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD bool kanzi::OptionalHandle< T, sentinel, deleter, typename >::hasValue ( ) const

inlinenoexcept

Checks if a handle is stored.

Returns

If holds a valid handle, true, otherwise false.

operator bool()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD kanzi::OptionalHandle< T, sentinel, deleter, typename >::operator bool ( ) const

inlineexplicitnoexcept

Conversion operator to bool.

Returns

If holds a valid handle, true, otherwise false.

get() [1/2]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD T kanzi::OptionalHandle< T, sentinel, deleter, typename >::get ( )

inlinenoexcept

Provides access to stored handle.

Returns

Stored handle.

get() [2/2]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD const T kanzi::OptionalHandle< T, sentinel, deleter, typename >::get ( ) const

inlinenoexcept

Provides access to stored handle.

Returns

Const stored handle.

getNativeHandle() [1/2]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD T kanzi::OptionalHandle< T, sentinel, deleter, typename >::getNativeHandle ( )

inlinenoexcept

Provides access to stored handle.

Returns

Stored handle.

getNativeHandle() [2/2]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD const T kanzi::OptionalHandle< T, sentinel, deleter, typename >::getNativeHandle ( ) const

inlinenoexcept

Provides access to stored handle.

Returns

Const stored handle.

reset() [1/2]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

void kanzi::OptionalHandle< T, sentinel, deleter, typename >::reset ( )

inlinenoexcept

Replaces stored handle with sentinel value.

Note

Resources associated with old handle are properly destroyed.

reset() [2/2]

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

template<typename U , typename = enable_if_t<is_same_v<T, decay_t<U>>>>

void kanzi::OptionalHandle< T, sentinel, deleter, typename >::reset ( U && newHandle )

inlinenoexcept

Stores a new handle inside.

Takes an ownership of the resource.

Note

Resources associated with old handle are properly destroyed.

Template Parameters

U	Deduced type for universal reference.

Parameters

newHandle

New handle to store.

release()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

T kanzi::OptionalHandle< T, sentinel, deleter, typename >::release ( )

inlinenoexcept

Releases ownership of a native handle without destroying the resource.

Returns

Stored handle.

getSentinel()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

static constexpr T kanzi::OptionalHandle< T, sentinel, deleter, typename >::getSentinel ( )

inlinestaticconstexprnoexcept

Gets sentinel value that can be used to represent invalid handle.

Returns

Sentinel value.

getDeleter()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

static constexpr auto kanzi::OptionalHandle< T, sentinel, deleter, typename >::getDeleter ( )

inlinestaticconstexprnoexcept

Gets deleter function.

Returns

Deleter function.

toOptional()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD optional< T > kanzi::OptionalHandle< T, sentinel, deleter, typename >::toOptional ( ) &&

inlinenoexcept

Converts OptionalHandle to kanzi::optional.

Use by moving the value first:

auto optHandle = OptionalHandle<int, 0, trivialDeleteFunc>{ 2 };
kanzi::optional<int> kzOpt = kanzi::move(optHandle).toOptional();

As the value is being moved, the responsibilities of deleting the handle are now upon the caller.

See also

FlatOptional::toOptional()

Return values

nullopt

OptionalHandle represented an empty value.

Returns

kanzi::optional equivalent.

createOptional()

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

KZ_NO_DISCARD optional< T > kanzi::OptionalHandle< T, sentinel, deleter, typename >::createOptional ( ) const

inlinenoexcept

Creates a kanzi::optional copy of the native handle.

Return values

nullopt

OptionalHandle represented an empty value.

Returns

kanzi::optional equivalent.

Member Data Documentation

m_handle

template<typename T , T sentinel, auto deleter, typename = enable_if_t<satisfiesOptionalHandle<T>>>

FlatOptional<T, sentinel> kanzi::OptionalHandle< T, sentinel, deleter, typename >::m_handle

protected

Native handle that is managed by this class.

---

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

• kanzi/core/util/handle.hpp