com::cosylab::acs::maci::manager::HandleDataStore Class Reference

Inheritance diagram for com::cosylab::acs::maci::manager::HandleDataStore:

Collaboration diagram for com::cosylab::acs::maci::manager::HandleDataStore:

Classes
class	Element
Public Member Functions
	HandleDataStore ()
	HandleDataStore (int initialCapacity)
	HandleDataStore (int initialCapacity, int maxCapacity)
int	size ()
int	capacity ()
boolean	isEmpty ()
Object	get (int handle)
void	set (int handle, Object data)
void	setCapacity (int newCapacity)
int	first ()
int	last ()
int	next (int handle)
int	previous (int handle)
boolean	isAllocated (int handle)
int	allocate ()
int	allocate (int handle)
int	preallocate ()
int	allocate (int handle, boolean preallocate)
void	ackAllocation (int handle)
void	deallocate (int handle)
void	deallocate (int handle, boolean depreallocate)
String	toString ()
Static Public Attributes
static final int	DEFAULT_MAX_CAPACITY = Integer.MAX_VALUE
Private Attributes
int	capacity
int	maxCapacity = DEFAULT_MAX_CAPACITY
int	size
Element[]	elements
int	first
int	last
Static Private Attributes
static final long	serialVersionUID = -6137572272422678754L

Detailed Description

Data structure for maintaining a collection of elements that can be referred to using handles.

Stores data elements in an array-like structure. Individual elements are addressed using handles, which can be though of as indices in the array. It fulfills these requirements:

allocation - a new element can be added and is assigned a unique handle. Allocation is an O(1) operation.
deallocation - an element can be removed from the registrar. The handle is freed, and can be assigned to another element during allocation at a later time. Deallocation is an O(1) operation.
retrieval - a reference to the element can be retrieved for reading and writing. Retrieval is an O(1) operation.
enumeration - elements stored can be traversed from first to last. Costs of acquiring first, last, next and previous element of the array are O(1).

This ADT is suitable for enumerating resources that are frequently allocated, retrieved and deallocated without losing large amounts of memory and/or time.

This is essentially a doubly-linked list of elements, which are placed in an array. Each element has assigned a handle (the index in the array), and handles of the elements that come previous and next to it. There are actually two chains of elements: the free element chain, which contains all elements that have not yet been allocated, and the allocated element chain. Free element chain is cyclic (passing the end resumes at the beginning), and contains the element with the handle 0. The allocated element chain is not cyclic: it starts with the element that was first allocated, and ends with the one that was last allocated.

Author:: Matej Sekoranja (matej.sekoranja@cosylab.com); Klemen Zagar (klemen.zagar@cosylab.com)

Version:: @VERSION@

Constructor & Destructor Documentation

com::cosylab::acs::maci::manager::HandleDataStore::HandleDataStore ( ) [inline]

Amount by which to offset all handles. Constructs a HandleDataStore with zero offset and initial capacity of ten.

References DEFAULT_MAX_CAPACITY.

com::cosylab::acs::maci::manager::HandleDataStore::HandleDataStore ( int initialCapacity ) [inline]

Constructs a HandleDataStore with zero offset.

Parameters:

initialCapacity

the initial capacity of the list.

Exceptions:

IllegalArgumentException

if the specified initial capacity is negative

References DEFAULT_MAX_CAPACITY.

com::cosylab::acs::maci::manager::HandleDataStore::HandleDataStore	(	int	initialCapacity,
		int	maxCapacity
	)			`[inline]`

Constructs a HandleDataStore.

Creates a HandleDataStore and allocates enough space to hold initialCapacity elements.

Parameters:

initialCapacity

the initial capacity of the list.

Exceptions:

IllegalArgumentException

if the specified initial capacity is negative

References setCapacity().

Member Function Documentation

void com::cosylab::acs::maci::manager::HandleDataStore::ackAllocation ( int handle ) [inline]

Completes allocation of handle, to be used to completely allocate handle after preallocation.

Parameters:

handle

handle to be completely allocated

References elements, first(), last(), com::cosylab::acs::maci::manager::HandleDataStore::Element::next, and com::cosylab::acs::maci::manager::HandleDataStore::Element::previous.

Referenced by allocate().

int com::cosylab::acs::maci::manager::HandleDataStore::allocate	(	int	handle,
		boolean	preallocate
	)			`[inline]`

Allocate an element with given handle in this HandleDataStore.

Assures that this ADT is capable of holding yet another element and returns a handle to it.

Parameters:

	handle	handle to be allocated
	preallocate	if `true` element is not really allocated (only reserved, listing through the ADT will skip preallocated elements), to completely allocate preallocated elements use `ackAllocation(handle)` or canceled by `deallocate(handle, true)` method.

Returns:: newly allocated handle if allocation was successfull, otherwise 0

See also:: deallocate

References ackAllocation(), capacity(), elements, com::cosylab::acs::maci::manager::HandleDataStore::Element::free, maxCapacity, com::cosylab::acs::maci::manager::HandleDataStore::Element::next, com::cosylab::acs::maci::manager::HandleDataStore::Element::previous, setCapacity(), and size().

int com::cosylab::acs::maci::manager::HandleDataStore::allocate ( int handle ) [inline]

Allocate an element in this HandleDataStore.

Parameters:

handle

hanlde be allocated

Returns:: newly allocated handle if allocation was successfull, otherwise 0

See also:: deallocate

References allocate().

int com::cosylab::acs::maci::manager::HandleDataStore::allocate ( ) [inline]

Allocate an element in this HandleDataStore.

Returns:: newly allocated handle if allocation was successfull, otherwise 0

See also:: deallocate

References elements, and next().

Referenced by com::cosylab::acs::maci::test::HandleDataStoreTest::allocate(), allocate(), preallocate(), com::cosylab::acs::maci::test::HandleDataStoreTest::testDefaultAllocation(), and com::cosylab::acs::maci::test::HandleDataStoreTest::testFreeAllocation().

int com::cosylab::acs::maci::manager::HandleDataStore::capacity ( ) [inline]

Returns the capacity of this ADT.

Capacity is the maximum number of elements that this ADT can hold before resizing itself.

Returns:: the capacity of this ADT.

Referenced by allocate(), isAllocated(), setCapacity(), and toString().

void com::cosylab::acs::maci::manager::HandleDataStore::deallocate	(	int	handle,
		boolean	depreallocate
	)			`[inline]`

Deallocate an element with the given handle.

The element and its corresponding handle can be reused at a later call to allocate.

Parameters:

	handle	the handle of the element to deallocate.
	depreallocate	has to be `true`, if handle was only preallocated

See also:: allocate

References com::cosylab::acs::maci::manager::HandleDataStore::Element::data, elements, first(), com::cosylab::acs::maci::manager::HandleDataStore::Element::free, last(), next(), com::cosylab::acs::maci::manager::HandleDataStore::Element::next, com::cosylab::acs::maci::manager::HandleDataStore::Element::previous, previous(), and size().

void com::cosylab::acs::maci::manager::HandleDataStore::deallocate ( int handle ) [inline]

Deallocate an element with the given handle.

The element and its corresponding handle can be reused at a later call to allocate.

Parameters:

handle

the handle of the element to deallocate.

See also:: allocate

Referenced by com::cosylab::acs::maci::test::HandleDataStoreTest::deallocate(), and com::cosylab::acs::maci::test::HandleDataStoreTest::testFreeAllocation().

int com::cosylab::acs::maci::manager::HandleDataStore::first ( ) [inline]

Return the handle of the first element in this ADT.

Returns:: the handle of the element that was the first one to get allocated and has not yet been deallocated. Useful for determining the starting point when enumerating the entire ADT.

See also:: next; previous; last

Referenced by ackAllocation(), deallocate(), and toString().

Object com::cosylab::acs::maci::manager::HandleDataStore::get ( int handle ) [inline]

Returns the element with the specified handle.

NOTE: handle is not checked, if it is valid.

Parameters:

handle

handle of the element

Exceptions:

IndexOutOfBoundsException

if handle is out of bounds.

References com::cosylab::acs::maci::manager::HandleDataStore::Element::data, and elements.

boolean com::cosylab::acs::maci::manager::HandleDataStore::isAllocated ( int handle ) [inline]

Determines whether a given handle is allocated.

Parameters:

handle

the handle in question.

Returns:: true if an element with handle handle already exists in this ADT, false otherwise.

References capacity(), elements, and com::cosylab::acs::maci::manager::HandleDataStore::Element::free.

boolean com::cosylab::acs::maci::manager::HandleDataStore::isEmpty ( ) [inline]

Tests if this list has no elements.

Returns:: true if this list has no elements, false otherwise.

References size().

int com::cosylab::acs::maci::manager::HandleDataStore::last ( ) [inline]

Return the handle of the last element in this ADT.

Returns:: the handle of the element that was the last one to get allocated and has not yet been deallocated. Useful for determining the starting point when enumerating the entire ADT.