OSB_LIB::ResourceList< R > Class Template Reference

Collaboration diagram for OSB_LIB::ResourceList< R >:

Detailed Description

template<typename R>
class OSB_LIB::ResourceList< R >

List of resources of a concrete type.

This utility template class allows clients to store objects of a concrete class derived from Resource in memory. Within resources_ a given resource object id may exist only once.
The class also provides functionality to read/write lock individual objects or the whole list of resources.

Attention:: Currently the whole list is always locked, even if a client requests a lock for an individual object. This means that while multiple read locks are possible, trying to acquire more than one write lock results in a dead-lock.

Definition at line 78 of file resourcelists.h.

Public Types

typedef std::list< R > List
Type of STL container used to store the resources.
typedef ReadGuard< R * > Rg
Read guard for one resource object.
typedef WriteGuard< R * > Wg
Write guard for one resource object.
typedef RwGuard ListRg
Read guard for the whole list of resources.
typedef RwGuard ListWg
Write guard for the whole list of resources.
success = 0
Success, none of the other values.
lockFailed = 1
Locking failed.
objectNotFound = 2
Object not found.
enum GuardStatus { success = 0, lockFailed = 1, objectNotFound = 2 }
Status of issued guards. More...

Public Member Functions

ResourceList (bool useLocks)
Constructor with locking flag.
bool useLocks () const
Locks applicable?
R * find (const Id< Resource > &id, bool doThrow)
Find a resource object by it's id.
const R * find (const Id< Resource > &id, bool doThrow) const
Find a resource object by it's id.
bool insert (const R &r)
Insert a resource to the list.
bool replace (const R &r)
Replace a resource in the list.
bool replace (const ResourceList< R > &src)
Replace resources in the list.
bool erase (const Id< Resource > &id)
Delete a resource from the list.
bool clear ()
Delete all resources from the list.
void sortByResNum (bool desc=false)
Sort resource lists by name.

Locking functions:

Rg readLock (const Id< Resource > &id, bool doThrow) const
Read-lock a resource object.
Wg writeLock (const Id< Resource > &id, bool doThrow)
Write-lock a resource object.
ListRg readLock () const
Read-lock the whole list of resources.
ListWg writeLock ()
Write-lock the whole list of resources.

Public Attributes

List resources_
List with the resource objects.

Private Member Functions

List::iterator findIter (const Id< Resource > &id)
Get an iterator to a resource object.
void eraseUnlocked (const Id< Resource > &id)
Delete a resource from the list without locking.
void replaceUnlocked (const R &r)
Replace a resource in the list without locking.

Static Private Member Functions

static bool lessResNum (const R &lhs, const R &rhs)
Compare two resources by their resource number.
static bool greaterResNum (const R &lhs, const R &rhs)
Compare two resources by their resource number.

Private Attributes

bool useLocks_
Flag if locking should be applied.
RwMutex mutex_
Mutex to lock the whole list.

Member Typedef Documentation

template<typename R>

typedef std::list<R> OSB_LIB::ResourceList< R >::List

Type of STL container used to store the resources.

Definition at line 81 of file resourcelists.h.

template<typename R>

typedef RwGuard OSB_LIB::ResourceList< R >::ListRg

Read guard for the whole list of resources.

Definition at line 87 of file resourcelists.h.

template<typename R>

typedef RwGuard OSB_LIB::ResourceList< R >::ListWg

Write guard for the whole list of resources.

Definition at line 89 of file resourcelists.h.

template<typename R>

typedef ReadGuard<R*> OSB_LIB::ResourceList< R >::Rg

Read guard for one resource object.

Definition at line 83 of file resourcelists.h.

template<typename R>

typedef WriteGuard<R*> OSB_LIB::ResourceList< R >::Wg

Write guard for one resource object.

Definition at line 85 of file resourcelists.h.

Member Enumeration Documentation

template<typename R>

enum OSB_LIB::ResourceList::GuardStatus

Status of issued guards.

Enumerator:

success	Success, none of the other values.
lockFailed	Locking failed.
objectNotFound	Object not found.

Definition at line 91 of file resourcelists.h.

Constructor & Destructor Documentation

template<typename R>

OSB_LIB::ResourceList< R >::ResourceList ( bool useLocks ) [explicit]

Constructor with locking flag.

Parameters:

useLocks

Flag if locking should be applied or not.

Definition at line 607 of file resourcelists.h.

Member Function Documentation

template<typename R>

bool OSB_LIB::ResourceList< R >::clear ( )

Delete all resources from the list.

Returns:: true in case of success, false if locking fails.

Definition at line 816 of file resourcelists.h.

References OSB_LIB::RwGuard::locked(), OSB_LIB::ResourceList< R >::resources_, and OSB_LIB::ResourceList< R >::writeLock().

template<typename R>

bool OSB_LIB::ResourceList< R >::erase ( const Id< Resource > & id )

Delete a resource from the list.

Parameters:

Id of the resource to delete.

Returns:: true if the resource is no more in the list after the function returns, false if locking fails.

The function write-locks the resource list

Definition at line 800 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::eraseUnlocked(), OSB_LIB::RwGuard::locked(), and OSB_LIB::ResourceList< R >::writeLock().

template<typename R>

void OSB_LIB::ResourceList< R >::eraseUnlocked ( const Id< Resource > & id ) [private]

Delete a resource from the list without locking.

Parameters:

Id of the resource to delete.

If findIter() finds a the resource in the list, the function erases it.

Definition at line 809 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::findIter(), and OSB_LIB::ResourceList< R >::resources_.

Referenced by OSB_LIB::ResourceList< R >::erase(), and OSB_LIB::ResourceList< R >::replaceUnlocked().

template<typename R>

const R * OSB_LIB::ResourceList< R >::find	(	const Id< Resource > &	id,
		bool	doThrow
	)			const

Find a resource object by it's id.

Parameters:

	id	Id of the resource to search.
	doThrow	Flag to throw if the resource is not found.

Returns:: Pointer to the resource, 0 if not found.

Exceptions:

OsbException

if doThrow is true and the resource is not found.

Remarks:: Because the pointer must be valid after the function returns, the caller of the functions is responsible to aquire (and release) an appropriate lock.

Definition at line 652 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::find().

template<typename R>

R * OSB_LIB::ResourceList< R >::find	(	const Id< Resource > &	id,
		bool	doThrow
	)

Find a resource object by it's id.

Parameters:

	id	Id of the resource to search.
	doThrow	Flag to throw if the resource is not found.

Returns:: Pointer to the resource, 0 if not found.

Exceptions:

OsbException

if doThrow is true and the resource is not found.

Remarks:: Because the pointer must be valid after the function returns, the caller of the functions is responsible to aquire (and release) an appropriate lock.

Definition at line 635 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::findIter(), and OSB_LIB::ResourceList< R >::resources_.

Referenced by OSB_LIB::ResourceList< R >::find(), OSB_LIB::ResourceList< R >::insert(), OSB_LIB::ResourceList< R >::readLock(), OSB_LIB::ResourceList< R >::replaceUnlocked(), and OSB_LIB::ResourceList< R >::writeLock().

template<typename R>

ResourceList< R >::List::iterator OSB_LIB::ResourceList< R >::findIter ( const Id< Resource > & id ) [private]

Get an iterator to a resource object.

Parameters:

Id of the resource to find.

Returns:: An iterator that points to the found resource, it is List::end() if not found.

Because an iterator to resources_ is returned, the caller of the function is responsible to lock and unlock the list.

Definition at line 621 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::resources_.

Referenced by OSB_LIB::ResourceList< R >::eraseUnlocked(), and OSB_LIB::ResourceList< R >::find().

template<typename R>

bool OSB_LIB::ResourceList< R >::greaterResNum	(	const R &	lhs,
		const R &	rhs
	)			`[static, private]`

Compare two resources by their resource number.

Parameters:

	lhs	One resource.
	rhs	The other resource.

Returns:: true if `lhs' is considered greater then `rhs'.

Definition at line 833 of file resourcelists.h.

Referenced by OSB_LIB::ResourceList< R >::sortByResNum().

template<typename R>

bool OSB_LIB::ResourceList< R >::insert ( const R & r )

Insert a resource to the list.

Parameters:

Resource to insert.

Returns:: true in case of success, false if the resource already exists in the list or if locking fails.

The function write-locks the resource list, verifies that the resource id does not exist in resources_ and then copies tr to it.

Definition at line 755 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::find(), OSB_LIB::RwGuard::locked(), OSB_LIB::ResourceList< R >::resources_, and OSB_LIB::ResourceList< R >::writeLock().

template<typename R>

bool OSB_LIB::ResourceList< R >::lessResNum	(	const R &	lhs,
		const R &	rhs
	)			`[static, private]`

Compare two resources by their resource number.

Parameters:

	lhs	One resource.
	rhs	The other resource.

Returns:: true if `lhs' is considered less then `rhs'.

Definition at line 825 of file resourcelists.h.

Referenced by OSB_LIB::ResourceList< R >::sortByResNum().

template<typename R>

ResourceList< R >::ListRg OSB_LIB::ResourceList< R >::readLock ( ) const

Read-lock the whole list of resources.

Returns:: A guard: if locking was successful or is not applied, it's member locked() will be true.

Definition at line 724 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::mutex_, OSB_LIB::RwMutex::readLock(), OSB_LIB::RwMutex::readUnlock(), and OSB_LIB::ResourceList< R >::useLocks_.

template<typename R>

ResourceList< R >::Rg OSB_LIB::ResourceList< R >::readLock	(	const Id< Resource > &	id,
		bool	doThrow
	)			const

Read-lock a resource object.

Parameters:

	id	Id of the resource to lock.
	doThrow	Flag to throw if the resource is not found.

Exceptions:

OsbException

if doThrow is true and the resource is not found.

Returns:: A read guard that -if succesful- contains a non-zero pointer to the resource. If case of failure the guard is not locked and it's is set to one of the values defined for GuardStatus to indicate the error.

Definition at line 662 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::find(), OSB_LIB::ResourceList< R >::lockFailed, OSB_LIB::ResourceList< R >::mutex_, OSB_LIB::ResourceList< R >::objectNotFound, OSB_LIB::RwMutex::readLock(), and OSB_LIB::ResourceList< R >::useLocks_.

template<typename R>

bool OSB_LIB::ResourceList< R >::replace ( const ResourceList< R > & src )

Replace resources in the list.

Parameters:

src

List of resource to replace.

Returns:: true in case of success, false if locking fails.

Definition at line 768 of file resourcelists.h.

References OSB_LIB::RwGuard::locked(), OSB_LIB::ResourceList< R >::replaceUnlocked(), OSB_LIB::ResourceList< R >::resources_, and OSB_LIB::ResourceList< R >::writeLock().

template<typename R>

bool OSB_LIB::ResourceList< R >::replace ( const R & r )

Replace a resource in the list.

Parameters:

Resource to replace.

Returns:: true in case of success, false if locking fails.
The function also returns true, if the resource did not exist in the list before the function was called.

Definition at line 781 of file resourcelists.h.

References OSB_LIB::RwGuard::locked(), OSB_LIB::ResourceList< R >::replaceUnlocked(), and OSB_LIB::ResourceList< R >::writeLock().

template<typename R>

void OSB_LIB::ResourceList< R >::replaceUnlocked ( const R & r ) [private]

Replace a resource in the list without locking.

Parameters:

Resource to replace.

Definition at line 790 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::eraseUnlocked(), OSB_LIB::ResourceList< R >::find(), and OSB_LIB::ResourceList< R >::resources_.

Referenced by OSB_LIB::ResourceList< R >::replace().

template<typename R>

void OSB_LIB::ResourceList< R >::sortByResNum ( bool desc = false )

Sort resource lists by name.

Parameters:

desc

Flag to sort in descending (true) or ascending (false) order.

Definition at line 841 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::greaterResNum(), OSB_LIB::ResourceList< R >::lessResNum(), and OSB_LIB::ResourceList< R >::resources_.

template<typename R>

bool OSB_LIB::ResourceList< R >::useLocks ( ) const

Locks applicable?

Definition at line 614 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::useLocks_.

template<typename R>

ResourceList< R >::ListWg OSB_LIB::ResourceList< R >::writeLock ( )

Write-lock the whole list of resources.

Returns:: A guard: if locking was successful or is not applied, it's member locked() will be true.

Definition at line 740 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::mutex_, OSB_LIB::ResourceList< R >::useLocks_, OSB_LIB::RwMutex::writeLock(), and OSB_LIB::RwMutex::writeUnlock().

Referenced by OSB_LIB::ResourceList< R >::clear(), OSB_LIB::ResourceList< R >::erase(), OSB_LIB::ResourceList< R >::insert(), and OSB_LIB::ResourceList< R >::replace().

template<typename R>

ResourceList< R >::Wg OSB_LIB::ResourceList< R >::writeLock	(	const Id< Resource > &	id,
		bool	doThrow
	)

Write-lock a resource object.

Parameters:

	id	Id of the resource to lock.
	doThrow	Flag to throw if the resource is not found.

Exceptions:

OsbException

if doThrow is true and the resource is not found.

Returns:: A write guard that -if succesful- contains a non-zero pointer to the resource. If case of failure the guard is not locked and it's is set to one of the values defined for GuardStatus to indicate the error.

Definition at line 693 of file resourcelists.h.

References OSB_LIB::ResourceList< R >::find(), OSB_LIB::ResourceList< R >::lockFailed, OSB_LIB::ResourceList< R >::mutex_, OSB_LIB::ResourceList< R >::objectNotFound, OSB_LIB::ResourceList< R >::useLocks_, and OSB_LIB::RwMutex::writeLock().