hdf5::ObjectHandle Class Reference

Wrapper for hid_t object identifiers. More...

#include <object_handle.hpp>

Public Types
enum class	Type {   Uninitialized , BadObject , File , Group ,   Datatype , Dataspace , Dataset , Attribute ,   PropertyList , VirtualFileLayer , PropertyListClass , ErrorClass ,   ErrorMessage , ErrorStack }
	type of the object handle More...
enum class	Policy { WithWard = 1 , WithoutWard = 2 }
	type of the ward policy More...

Public Member Functions
	ObjectHandle (hid_t id, Policy policy=Policy::WithWard)
	construct from HDF5 ID More...
	ObjectHandle () noexcept
	default constructor More...
	ObjectHandle (const ObjectHandle &o)
	copy constructor More...
	ObjectHandle (ObjectHandle &&o) noexcept
	move constructor More...
	~ObjectHandle () noexcept
	destructor More...
ObjectHandle &	operator= (const ObjectHandle &o)
	copy assignment operator More...
ObjectHandle &	operator= (ObjectHandle &&o) noexcept
	move assignment operator More...
	operator hid_t () const
	conversion operator More...
void	close ()
	close the object More...
bool	is_valid () const
	check validity More...
ObjectHandle::Type	get_type () const
	get nexus object type More...
int	get_reference_count () const
	return reference counter value More...

Detailed Description

Objects in HDf5 are referenced using an handle of type hid_t. Though the name of the type and the API reference of the HDF5 C-API suggest this value is an ID it should be rather considered a handle which is used to reference a particular object.

The aim of this class is to encapsulate an HDF5 handler and control the reference counting for that handler for copy and move construction and assignment.

• copy construction and assignment increments the reference count of an handler
• move construction and assignment leaves the reference count unchanged
• closing an object decrements the reference count
• in addition, the reference count is decreased if the destructor of an instance of ObjectHandle is called

From that point of view ObjectHandle could also be considered as a guard object for a handle which ensures that an object gets closed once it looses scope.

The class also comprises a set of static member functions which provide operations on the handler.

Member Enumeration Documentation

Policy

enum hdf5::ObjectHandle::Policy

strong

Enumerator
WithWard
WithoutWard

Type

enum hdf5::ObjectHandle::Type

strong

Enumerator
Uninitialized
BadObject
File
Group
Datatype
Dataspace
Dataset
Attribute
PropertyList
VirtualFileLayer
PropertyListClass
ErrorClass
ErrorMessage
ErrorStack

Constructor & Destructor Documentation

ObjectHandle() [1/4]

hdf5::ObjectHandle::ObjectHandle ( hid_t  id, Policy  policy = Policy::WithWard  )

explicit

This constructor can be used to construct an instance of h5object from an HDF5 ID. h5object takes full control over the constructed object. Thus the constructor has move semantics and does not allow to use const & or & to the hid_t argument. A typical usage example would look like this

.....
hdf5::ObjectHandle handle(H5Gopen(fid,"data",hdf5::property::kDefault));
...

An exception is thrown if the ID passed is negative.

Exceptions

std::runtime_error

if the passed id is invalid (<0)

Parameters

id	HDF5 object ID.
policy	with or w/o ward policy.

ObjectHandle() [2/4]

hdf5::ObjectHandle::ObjectHandle ( )

explicitnoexcept

The default constructor does not throw. However, after default construction the object will be in an invalid state.

ObjectHandle() [3/4]

hdf5::ObjectHandle::ObjectHandle

(

const ObjectHandle &

o

)

Copies the ID of the o and increments its reference counter if the object is valid.

Exceptions

std::runtime_error

in case of errors

Parameters

o	object which to cpy

ObjectHandle() [4/4]

hdf5::ObjectHandle::ObjectHandle ( ObjectHandle &&  o )

noexcept

Copies the ID of the original object and sets the ID of the original object to 0. As this is a move process the reference counter of the ID will not be incremented.

Parameters

o	object to move

~ObjectHandle()

hdf5::ObjectHandle::~ObjectHandle ( )

noexcept

Member Function Documentation

close()

void hdf5::ObjectHandle::close

(

)

This will decrement the reference counter of the ID held by this object or close it if the reference counter approaches 0. The close method runs an object introspection by means of the HDF5 library and calls the appropriate close function.

Exceptions

std::runtime_error

if the close operation fails

get_reference_count()

int hdf5::ObjectHandle::get_reference_count

(

)

const

Exceptions

std::runtime_error

if retrieval of the reference count fails

Returns

the actual reference count

get_type()

ObjectHandle::Type hdf5::ObjectHandle::get_type

(

)

const

Exceptions

std::runtime_error

if the type is unknown

Returns

object type

is_valid()

bool hdf5::ObjectHandle::is_valid

(

)

const

This method returns true of the object refers to a valid HDF5 object. In other words this means that the object is valid and available. For a file object this would mean that the file is open.

Exceptions

std::runtime_error

if object status retrieval fails

Returns

true if valid HDF5 object

operator hid_t()

hdf5::ObjectHandle::operator hid_t ( ) const

inlineexplicit

operator=() [1/2]

ObjectHandle& hdf5::ObjectHandle::operator=

(

const ObjectHandle &

o

)

Just like for the copy constructor the reference counter for the original ID is incremented.

Exceptions

std::runtime_error

in case of errors

Parameters

o	object to assign

Returns

refence to object

operator=() [2/2]

ObjectHandle& hdf5::ObjectHandle::operator= ( ObjectHandle &&  o )

noexcept

Like the move constructor this operator has no influence on the value of the IDs reference counter.

Exceptions

std::runtime_error

in case of errors

Parameters

o	object form which to move data

Returns

reference to object

---

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

• /home/jenkins/h5cpp/src/h5cpp/core/object_handle.hpp