aiscoal: CkptContainer Class Reference

CkptContainer::CkptContainer	(	std::string	containerName,
		unsigned long	maxObjects,
		unsigned long	maxObjectSize,
		CkptRetentionPolicy	rPolicy = `CKPT_RELEASE`
	)

Creates a container with a link to the checkpoint represented by the container name.

Parameters:

	containerName	- The name (a string) of the container
	maxObjects	- the maximum numbers of objects that can be in the container
	maxObjectSize	- the maximum size of an object in the container
	rPolicy	- controls the behavior of the data when all containers have been removed. [Default = CKPT_RELEASE]

Definition at line 3 of file CkptContainer.cc.

References _checkpointHandle, _checkpointName, _containerName, _daoFactory, _maxObjectSize, _serviceHandle, _valid, and CKPT_RETAIN.

CkptContainer::~CkptContainer ( )

Destroy the container, closing the handle to the underlying checkpoint.

If this is the last container associated with this replica on this node, destruction causes the triggering of the retention policy in place.

CKPT_RETAIN - the replica will continue to exist. Re-creation of a container using the same container name will have access to the committed objects. The replica will continue to be updated from commits on other nodes.
CKPT_RELEASE - the replica will be removed. Re-creation of a container with the same name will cause the creation of a checkpoint in the CKPT service. The availability of committed objects will be dependent upon the presence of the replica data in another node in our cluster.

Definition at line 43 of file CkptContainer.cc.

References _checkpointHandle, _daoFactory, _serviceHandle, and _valid.

unsigned long CkptContainer::size ( )

Get the number of objects in the container.

Invokes the CKPT status query to determine the number of sections in the underlying checkpoint.

Returns:: the number of objects in the container

Definition at line 52 of file CkptContainer.cc.

References _checkpointHandle.

CkptObject * CkptContainer::get ( CkptObjectKey * key )

Retrieve a representation of the object identified by a key.

Passing the key as a pointer implies the CkptObject will own the key (i.e. manage its deallocation) The key becomes OWNED by the retrieved CkptObject through a call to CkptObject::setKey() If the key is on a stack, use get(CkptObjectKey&) This means you could call get(new CkptObjectKey("KeyName", deserProc)) and expect the library to deallocate the key for you.

CAUTION: calling this procedure with the pointer to a stack-based key can result in faults (if the retrieved object outlives the stack frame where the key resides)

Parameters:

key

- the key for the object being retrieved

Returns:

a pointer to the CkptObject associated with key.

This object is a snapshot representation of the data in the underlying replica.
Commits to the container by other nodes do not cause automatic update to this object.

See also:: get(CkptObjectKey&)

Reimplemented in CkptSimpleContainer< T >.

Definition at line 62 of file CkptContainer.cc.

References _checkpointHandle, _daoFactory, _maxObjectSize, _valid, and CkptObjectKey::sectionIdValue().

Referenced by CkptSimpleContainer< T >::get().

CkptObject * CkptContainer::get ( CkptObjectKey & key )

Retrieve a representation of the object identified by a key.

Passing the key as a reference implies the CkptObject should make a copy (i.e. the key may live on a stack somewhere)

The key is COPIED, and the copy is owned by the retrieved CkptObject through a call to CkptObject::setKey() To use a non-stack-based key (say, on a heap), and to avoid the copy, use get(CkptObjectKey*)

Parameters:

key

- the key for the object being retrieved

Returns:

a pointer to the CkptObject associated with key.

This object is a snapshot representation of the data in the underlying replica.
Commits to the container by other nodes do not cause automatic updates to this object.

See also:: get(CkptObjectKey*)

Reimplemented in CkptSimpleContainer< T >.

Definition at line 102 of file CkptContainer.cc.

CkptRC CkptContainer::persist	(	CkptObject *	obj,
		bool	overwriteExisting = `true`
	)

Persist the data in the specified object, retrievable by its key.

from all nodes with a reference to this container Commits the data in obj to the underlying storage medium/propigates it to all nodes with references to this container.

Parameters:

	obj	- the object to be persisted in the data medium
	overwriteExisting	- flag indicating if the persist operation should overwrite an existing object with the same key, if it is found.

Returns:: CkptSuccess if the operation succeeds, CkptFailure otherwise.

Definition at line 107 of file CkptContainer.cc.

References _checkpointHandle, _daoFactory, _valid, CkptFailure, CkptSuccess, DAOInterfaceFactory::createOutputDAO(), CkptByteArray::getDataPtr(), CkptByteArray::getDataSize(), CkptObject::getKey(), DAOInterface::getOutputData(), CkptObjectKey::sectionIdValue(), and CkptObject::setContainer().

CkptRC CkptContainer::remove ( CkptObject * obj )

Disassociates a CkptObject from the container and delete the section for it in the underlying checkpoint.

Parameters:

obj

The object to be removed from the container

Returns:: CkptSuccess if the operation succeeds, CkptFailure otherwise.

Definition at line 147 of file CkptContainer.cc.

References _checkpointHandle, _valid, CkptFailure, CkptSuccess, CkptObject::getKey(), CkptObjectKey::sectionIdValue(), and CkptObject::setContainer().

CkptRC CkptContainer::commit ( CkptObject * obj )

Commits the data in obj to the underlying storage medium.

Returns:: CkptSuccess if the operation succeeds, CkptFailure otherwise.

Definition at line 159 of file CkptContainer.cc.

References _checkpointHandle, _daoFactory, _valid, CKPT_OBJ_MANAGED, CkptFailure, CkptSuccess, DAOInterfaceFactory::createOutputDAO(), CkptByteArray::getDataPtr(), CkptByteArray::getDataSize(), DAOInterface::getOutputData(), and CkptObject::getState().

Referenced by CkptObject::commit().

bool CkptContainer::isValid ( ) [inline]

Returns the state of the Container.

If this returns false, all operations on the container will fail.

Returns:: true if the Container has successfully opened the underlying checkpoint with the CKPT service.
false otherwise.

Definition at line 145 of file CkptContainer.h.

References _valid.

CkptRC CkptContainer::setRetentionPolicy ( CkptRetentionPolicy rPolicy )

Change the retention policy for the replica under this checkpoint.

Parameters:

rPolicy

- the policy used for the data replica If set to CKPT_RELEASE, the replica will be deleted when all containers that reference it are closed. If set to CKPT_RETAIN, the replica will continue to exist even if there are no containers using it. A container can reopen a reference to the replica, provided the same parameters are used for its creation.

Returns:: CkptSuccess if the operation succeeds, CkptFailure otherwise.

Definition at line 180 of file CkptContainer.cc.

References _checkpointHandle, _valid, CKPT_RETAIN, CkptFailure, and CkptSuccess.

std::string CkptContainer::_containerName [private]

the name of the container

Definition at line 162 of file CkptContainer.h.

Referenced by CkptContainer().

SaNameT CkptContainer::_checkpointName [private]

a SaNameT representation of the _containerName

Definition at line 163 of file CkptContainer.h.

Referenced by CkptContainer().

SaCkptHandleT CkptContainer::_serviceHandle [private]

a handle to the CKPT service

Definition at line 164 of file CkptContainer.h.

Referenced by CkptContainer(), and ~CkptContainer().

SaCkptCheckpointHandleT CkptContainer::_checkpointHandle [private]

a handle to the checkpoint represented by _checkpointName

Definition at line 165 of file CkptContainer.h.

Referenced by CkptContainer(), commit(), get(), persist(), remove(), setRetentionPolicy(), size(), and ~CkptContainer().

unsigned long CkptContainer::_maxObjectSize [private]

the maximum size of an object in the container

Definition at line 166 of file CkptContainer.h.

Referenced by CkptContainer(), and get().

bool CkptContainer::_valid [private]

flag indicating the validity of the container-CKPT relationship

Definition at line 167 of file CkptContainer.h.

Referenced by CkptContainer(), commit(), get(), isValid(), persist(), remove(), setRetentionPolicy(), and ~CkptContainer().

DAOInterfaceFactory* CkptContainer::_daoFactory [private]

factory for creating Data Access Objects

Definition at line 168 of file CkptContainer.h.

Referenced by CkptContainer(), commit(), get(), persist(), and ~CkptContainer().

CkptContainer Class Reference

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation


Public Member Functions
	CkptContainer (std::string containerName, unsigned long maxObjects, unsigned long maxObjectSize, CkptRetentionPolicy rPolicy=CKPT_RELEASE)
	Creates a container with a link to the checkpoint represented by the container name.
	~CkptContainer ()
	Destroy the container, closing the handle to the underlying checkpoint.
unsigned long	size ()
	Get the number of objects in the container.
CkptObject *	get (CkptObjectKey *key)
	Retrieve a representation of the object identified by a key.
CkptObject *	get (CkptObjectKey &key)
	Retrieve a representation of the object identified by a key.
CkptRC	persist (CkptObject *obj, bool overwriteExisting=true)
	Persist the data in the specified object, retrievable by its key.
CkptRC	remove (CkptObject *obj)
	Disassociates a CkptObject from the container and delete the section for it in the underlying checkpoint.
CkptRC	commit (CkptObject *obj)
	Commits the data in obj to the underlying storage medium.
bool	isValid ()
	Returns the state of the Container.
CkptRC	setRetentionPolicy (CkptRetentionPolicy rPolicy)
	Change the retention policy for the replica under this checkpoint.
Private Attributes
std::string	_containerName
	the name of the container
SaNameT	_checkpointName
	a SaNameT representation of the _containerName
SaCkptHandleT	_serviceHandle
	a handle to the CKPT service
SaCkptCheckpointHandleT	_checkpointHandle
	a handle to the checkpoint represented by _checkpointName
unsigned long	_maxObjectSize
	the maximum size of an object in the container
bool	_valid
	flag indicating the validity of the container-CKPT relationship
DAOInterfaceFactory *	_daoFactory
	factory for creating Data Access Objects