Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

MutexLock< num_doors > Class Template Reference

#include <MutexLock.h>

Inheritance diagram for MutexLock< num_doors >:

List of all members.


Detailed Description

template<unsigned int num_doors>
class MutexLock< num_doors >

Implements a mutual exclusion lock using semaphores (SYSV style through SemaphoreManager).

Use this to prevent more than one process from accessing a data structure at the same time (which often leads to unpredictable and unexpected results)

The template parameter specifies the maximum number of different processes which need to be protected. This needs to be allocated ahead of time, as there doesn't seem to be a way to dynamically scale as needed without risking possible errors if two processes are both trying to set up at the same time. Also, by using a template parameter, all data structures are contained within the class's memory allocation, so no pointers are involved.

Locks in this class can be recursive or non-recursive, depending whether you call releaseAll() or unlock(). If you lock 5 times, then you need to call unlock() 5 times as well before it will be unlocked. However, if you lock 5 times, just one call to releaseAll() will undo all 5 levels of locking.

Just remember, unlock() releases one level. But releaseAll() completely unlocks.

Note that there is no check that the process doing the unlocking is the one that actually has the lock. Be careful about this.

Warning:
Doing mutual exclusion in software is tricky business, be careful about any modifications you make!

Definition at line 214 of file MutexLock.h.


Public Member Functions

 MutexLock ()
 constructor, gets a new semaphore from the semaphore manager
 MutexLock (SemaphoreManager::semid_t semid)
 constructor, use this if you already have a semaphore id you want to use from semaphore manager
 ~MutexLock ()
 destructor, releases semaphore back to semaphore manager
void lock (int id)
 blocks until lock is achieved. This is done efficiently using a SysV style semaphore
bool try_lock (int id)
 attempts to get a lock, returns true if it succeeds
void unlock ()
 releases one recursive lock-level from whoever has the current lock
void releaseAll ()
 completely unlocks, regardless of how many times a recursive lock has been obtained
unsigned int get_lock_level () const
 returns the lockcount
int owner () const
 returns the current owner's id

Protected Member Functions

bool isOwnerThread ()
 returns true if the current thread is the one which owns the lock
virtual void useResource (Resource::Data &)
 marks the resource as in use
virtual void releaseResource (Resource::Data &)
 releases the resource

Protected Attributes

SemaphoreManager::semid_t sem
 the SysV semaphore number
unsigned int owner_index
 holds the tekkotsu process id of the current lock owner
pthread_t owner_thread
 holds a thread id for the owner thread

Private Member Functions

 MutexLock (const MutexLock &ml)
 copy constructor, do not call
MutexLockoperator= (const MutexLock &ml)
 assignment, do not call

Friends

class MarkScope

Constructor & Destructor Documentation

template<unsigned int num_doors>
MutexLock< num_doors >::MutexLock (  )  [inline]

constructor, gets a new semaphore from the semaphore manager

Definition at line 217 of file MutexLock.h.

template<unsigned int num_doors>
MutexLock< num_doors >::MutexLock ( SemaphoreManager::semid_t  semid  )  [inline]

constructor, use this if you already have a semaphore id you want to use from semaphore manager

Definition at line 226 of file MutexLock.h.

template<unsigned int num_doors>
MutexLock< num_doors >::~MutexLock (  )  [inline]

destructor, releases semaphore back to semaphore manager

Definition at line 235 of file MutexLock.h.

template<unsigned int num_doors>
MutexLock< num_doors >::MutexLock ( const MutexLock< num_doors > &  ml  )  [private]

copy constructor, do not call


Member Function Documentation

template<unsigned int num_doors>
void MutexLock< num_doors >::lock ( int  id  )  [inline]

blocks until lock is achieved. This is done efficiently using a SysV style semaphore

You should pass some process-specific ID number as the input - just make sure no other process will be using the same value.

Definition at line 246 of file MutexLock.h.

Referenced by MotionManager::func_begin(), WorldStatePool::getCurrentWriteState(), MotionManager::InitAccess(), MotionManager::lock(), MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage(), and MutexLock< MAX_ACCESS >::useResource().

template<unsigned int num_doors>
bool MutexLock< num_doors >::try_lock ( int  id  )  [inline]

attempts to get a lock, returns true if it succeeds

You should pass some process-specific ID number as the input - just make sure no other process will be using the same value.

Definition at line 267 of file MutexLock.h.

Referenced by MotionManager::trylock().

template<unsigned int num_doors>
void MutexLock< num_doors >::unlock (  )  [inline]

releases one recursive lock-level from whoever has the current lock

Definition at line 289 of file MutexLock.h.

Referenced by WorldStatePool::doneWritingState(), MotionManager::func_end(), MotionManager::InitAccess(), MutexLock< MAX_ACCESS >::releaseResource(), and MotionManager::unlock().

template<unsigned int num_doors>
void MutexLock< num_doors >::releaseAll (  )  [inline]

completely unlocks, regardless of how many times a recursive lock has been obtained

Definition at line 307 of file MutexLock.h.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage().

template<unsigned int num_doors>
unsigned int MutexLock< num_doors >::get_lock_level (  )  const [inline]

returns the lockcount

Definition at line 317 of file MutexLock.h.

Referenced by MessageQueue< MAX_UNREAD, MAX_RECEIVERS, MAX_SENDERS >::sendMessage().

template<unsigned int num_doors>
int MutexLock< num_doors >::owner (  )  const [inline]

returns the current owner's id

Definition at line 325 of file MutexLock.h.

Referenced by MutexLock< MAX_ACCESS >::try_lock().

template<unsigned int num_doors>
bool MutexLock< num_doors >::isOwnerThread (  )  [inline, protected]

returns true if the current thread is the one which owns the lock

Definition at line 329 of file MutexLock.h.

Referenced by MutexLock< MAX_ACCESS >::lock(), and MutexLock< MAX_ACCESS >::try_lock().

template<unsigned int num_doors>
virtual void MutexLock< num_doors >::useResource ( Resource::Data d  )  [inline, protected, virtual]

marks the resource as in use

Implements Resource.

Definition at line 334 of file MutexLock.h.

template<unsigned int num_doors>
virtual void MutexLock< num_doors >::releaseResource ( Resource::Data d  )  [inline, protected, virtual]

releases the resource

Implements Resource.

Definition at line 337 of file MutexLock.h.

template<unsigned int num_doors>
MutexLock& MutexLock< num_doors >::operator= ( const MutexLock< num_doors > &  ml  )  [private]

assignment, do not call


Friends And Related Function Documentation

template<unsigned int num_doors>
friend class MarkScope [friend]

Definition at line 333 of file MutexLock.h.


Member Data Documentation

template<unsigned int num_doors>
unsigned int MutexLock< num_doors >::owner_index [protected]

template<unsigned int num_doors>
pthread_t MutexLock< num_doors >::owner_thread [protected]

holds a thread id for the owner thread

Definition at line 343 of file MutexLock.h.

Referenced by MutexLock< MAX_ACCESS >::isOwnerThread(), MutexLock< MAX_ACCESS >::lock(), and MutexLock< MAX_ACCESS >::try_lock().


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

Tekkotsu v4.0
Generated Thu Nov 22 00:58:33 2007 by Doxygen 1.5.4