HDF5Handle Class Reference

Wrapper for unique hid_t objects. More...

#include <vigra/hdf5impex.hxx>

Public Member Functions
herr_t	close ()
	Explicitly call the stored destructor (if one has been registered in the constructor) for the contained handle and set the wrapper to NULL. Returns a negative value when the destructor call for the handle fails, and a non-negative value otherwise.
hid_t	get () const
	Get a temporary hid_t object for the contained handle. Do not call a close function on the return value - a crash will be likely otherwise.
	HDF5Handle ()
	Default constructor. Creates a NULL handle.
	HDF5Handle (hid_t h, Destructor destructor, const char *error_message)
	Create a wrapper for a hid_t object. More...
	HDF5Handle (HDF5Handle const &h)
	Copy constructor. More...
	operator hid_t () const
	Convert to a plain hid_t object. More...
bool	operator!= (HDF5Handle const &h) const
	Inequality comparison of the contained handle.
bool	operator!= (hid_t h) const
	Inequality comparison of the contained handle.
HDF5Handle &	operator= (HDF5Handle const &h)
	Assignment. Calls close() for the LHS handle and hands over ownership of the RHS handle (analogous to std::unique_pt).
bool	operator== (HDF5Handle const &h) const
	Equality comparison of the contained handle.
bool	operator== (hid_t h) const
	Equality comparison of the contained handle.
hid_t	release ()
	Return the contained handle and set the wrapper to NULL without calling close().
void	reset (hid_t h, Destructor destructor, const char *error_message)
	Reset the wrapper to a new handle. More...
void	swap (HDF5Handle &h)
	Swap the contents of two handle wrappers. More...
	~HDF5Handle ()
	Destructor. Calls close() for the contained handle.

Detailed Description

Wrapper for unique hid_t objects.

This class offers the functionality of std::unique_ptr for HDF5 handles (type hid_t). Unfortunately, std::unique_ptr cannot be used directly for this purpose because it only works with pointers, whereas hid_t is an integer type.

Newly created or opened HDF5 handles are stored as objects of type hid_t. When the handle is no longer needed, the appropriate close function must be called. However, if a function is aborted by an exception, this is difficult to ensure. Class HDF5Handle is a smart pointer that solves this problem by calling the close function in the destructor (This is analogous to how std::unique_ptr calls 'delete' on the contained pointer). A pointer to the close function must be passed to the constructor, along with an error message that is raised when creation/opening fails.

When a HDF5Handle is created or assigned from another one, ownership passes on to the left-hand-side handle object, and the right-hand-side objects is resest to a NULL handle.

Since HDF5Handle objects are convertible to hid_t, they can be used in the code in place of the latter.

Usage:

HDF5Handle file_id(H5Fopen(filename, H5F_ACC_RDWR, H5P_DEFAULT),
                   &H5Fclose,
                   "Error message when H5Fopen() fails.");

... // use file_id in the same way as a plain hid_t object

// pass ownership to a new handle object
HDF5Handle new_handle(file_id);

assert(file_id.get() == 0);

#include <vigra/hdf5impex.hxx>
Namespace: vigra

Constructor & Destructor Documentation

HDF5Handle	(	hid_t	h,
		Destructor	destructor,
		const char *	error_message
	)

Create a wrapper for a hid_t object.

The hid_t object h is assumed to be the return value of an open or create function. It will be closed with the given close function destructor as soon as this HDF5Handle is destructed, except when destructor is a NULL pointer (in which case nothing happens at destruction time). If h has a value that indicates failed opening or creation (by HDF5 convention, this means that h is negative), an exception is raised by calling vigra_fail(error_message).

Usage:

HDF5Handle file_id(H5Fopen(filename, H5F_ACC_RDWR, H5P_DEFAULT),
                   &H5Fclose,
                   "Error message.");

... // use file_id in the same way

HDF5Handle

(

HDF5Handle const &

h

)

Copy constructor.

Hands over ownership of the RHS handle (analogous to std::unique_pt).

Member Function Documentation

void reset	(	hid_t	h,
		Destructor	destructor,
		const char *	error_message
	)

Reset the wrapper to a new handle.

Equivalent to handle = HDF5Handle(h, destructor, error_message).

void swap

(

HDF5Handle &

h

)

Swap the contents of two handle wrappers.

Also available as std::swap(handle1, handle2).

operator hid_t

(

)

const

Convert to a plain hid_t object.

This function ensures that hid_t objects can be transparently replaced with HDF5Handle objects in user code. Do not call a close function on the return value - a crash will be likely otherwise.

---

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

• vigra/hdf5impex.hxx