vigra - HDF5HandleShared Class Reference

[ VIGRA Homepage | Function Index | Class Index | Namespaces | File List | Main Page ]

| HDF5HandleShared Class Reference Import/Export of Images and Arrays in HDF5 Format |

Wrapper for shared hid_t objects. More...

`#include <vigra/hdf5impex.hxx>`

## Public Member Functions
herr_t | close ()
| Close the handle if this is the unique (i.e. last) owner. More...
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.
| HDF5HandleShared ()
| Default constructor. Creates a NULL handle.
| HDF5HandleShared (hid_t h, Destructor destructor, const char *error_message)
| Create a shared wrapper for a plain hid_t object. More...
| HDF5HandleShared (HDF5HandleShared const &h)
| Copy constructor. Shares ownership with the RHS handle (analogous to `std::shared_ptr`).
| operator hid_t () const
| Convert to a plain hid_t object. More...
bool | operator!= (HDF5HandleShared const &h) const
| Inequality comparison of the contained handle.
bool | operator!= (hid_t h) const
| Inequality comparison of the contained handle.
HDF5HandleShared & | operator= (HDF5HandleShared const &h)
| Assignment. Call close() for the present LHS handle and share ownership with the RHS handle (analogous to `std::shared_ptr`).
bool | operator== (HDF5HandleShared const &h) const
| Equality comparison of the contained handle.
bool | operator== (hid_t h) const
| Equality comparison of the contained handle.
void | reset (hid_t h, Destructor destructor, const char *error_message)
| Reset the handle to a new value. More...
void | swap (HDF5HandleShared &h)
| Swap the contents of two handle wrappers. More...
bool | unique () const
| Check if this is the unique owner of the conatined handle. More...
size_t | use_count () const
| Get the number of owners of the contained handle.
| ~HDF5HandleShared ()
| Destructor (calls close())

## Detailed Description

Wrapper for shared hid_t objects.

This class offers the functionality of `std::shared_ptr` for HDF5 handles (type `hid_t`). Unfortunately, `std::shared_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 HDF5HandleShared is a smart pointer that solves this problem by calling the close function in the destructor of the handle's last owner (This is analogous to how `std::shared_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 `HDF5HandleShared` is created or assigned from another one, ownership is shared between the two handles, and the value returned by `use_count()` increases by one.

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

Usage:

HDF5HandleShared 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
// share ownership between same_id and file_id
HDF5HandleShared same_id(file_id);
assert(same_id.use_count() == 2);
assert(same_id.get() == file_id.get());

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

## Constructor & Destructor Documentation

HDF5HandleShared | ( | hid_t | h,
|  | Destructor | destructor,
|  | const char * | error_message
| ) |  |

Create a shared wrapper for a plain 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 HDF5HandleShared 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:

HDF5HandleShared file_id(H5Fopen(filename, H5F_ACC_RDWR, H5P_DEFAULT),
&H5Fclose,
"Error message.");
... // use file_id in the same way

## Member Function Documentation

herr_t close | ( |  | ) |

Close the handle if this is the unique (i.e. last) owner.

Decrements the reference counter and calls the destructor function of the handle (if one has been registered in the constructor) when the counter reaches zero. Sets this wrapper to NULL in any case. Returns a negative value when the destructor call for the handle fails, and a non-negative value otherwise.

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

Reset the handle to a new value.

Equivalent to `handle = HDF5HandleShared(h, destructor, error_message)`.

bool unique | ( |  | ) | const

Check if this is the unique owner of the conatined handle.

Equivalent to `handle.use_count() == 1`.

void swap | ( | HDF5HandleShared & | 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 HDF5HandleShared 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

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de) Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany | html generated using doxygen and Python vigra 1.11.1 (Fri May 19 2017)