#include <quniquehandle_p.h>

Inheritance diagram for QUniqueHandle< HandleTraits >:

Collaboration diagram for QUniqueHandle< HandleTraits >:

Public Types
using	Type = typename HandleTraits::Type

Public Member Functions
	QUniqueHandle ()=default

	QUniqueHandle (const Type &handle) noexcept

	QUniqueHandle (QUniqueHandle &&other) noexcept

	~QUniqueHandle () noexcept

void	swap (QUniqueHandle &other) noexcept

	QUniqueHandle (const QUniqueHandle &)=delete

QUniqueHandle &	operator= (const QUniqueHandle &)=delete

bool	isValid () const noexcept

	operator bool () const noexcept

Type	get () const noexcept

void	reset (const Type &handle=HandleTraits::invalidValue()) noexcept

Type	release () noexcept

Type *	operator& () noexcept

void	close () noexcept

Friends
bool	comparesEqual (const QUniqueHandle &lhs, const QUniqueHandle &rhs) noexcept

Qt::strong_ordering	compareThreeWay (const QUniqueHandle &lhs, const QUniqueHandle &rhs) noexcept

Detailed Description

template<typename HandleTraits>
class QUniqueHandle< HandleTraits >

QUniqueHandle is a general purpose RAII wrapper intended for interfacing with resource-allocating C-style APIs, for example operating system APIs, database engine APIs, or any other scenario where resources are allocated and released, and where pointer semantics does not seem a perfect fit.

QUniqueHandle does not support copying, because it is intended to maintain ownership of resources that can not be copied. This makes it safer to use than naked handle types, since ownership is maintained by design.

The underlying handle object is described using a client supplied HandleTraits object that is implemented per resource type. The traits struct must describe two properties of a handle:

1) What value is considered invalid 2) How to close a resource.

Example 1:

struct InvalidHandleTraits {
    using Type = HANDLE;

    static Type invalidValue() {
        return INVALID_HANDLE_VALUE;
    }

    static bool close(Type handle) {
        return CloseHandle(handle) != 0;
    }
}

using FileHandle = QUniqueHandle<InvalidHandleTraits>;

Usage:

Takes ownership of returned handle. FileHandle handle{ CreateFile(...) };

if (!handle.isValid()) { qDebug() << GetLastError() return; }

...

Example 2:

struct SqLiteTraits {
    using Type = sqlite3*;

    static Type invalidValue() {
        return nullptr;
    }

    static bool close(Type handle) {
        sqlite3_close(handle);
        return true;
    }
}

using DbHandle = QUniqueHandle<SqLiteTraits>;

Usage:

DbHandle h;

Take ownership of returned handle. int result = sqlite3_open(":memory:", &h);

...

NOTE: The QUniqueHandle assumes that closing a resource is guaranteed to succeed, and provides no support for handling failure to close a resource. It is therefore only recommended for use cases where failure to close a resource is either not an error, or an unrecoverable error.

Definition at line 112 of file quniquehandle_p.h.