Homepage Demos Overview Downloads Tutorials Reference
Credits

MutexLock< num_doors > Class Template Reference

#include <MutexLock.h>

Inheritance diagram for MutexLock< num_doors >:

Inheritance graph
[legend]
List of all members.

Detailed Description

template<unsigned int num_doors>
class MutexLock< num_doors >

A software only mutual exclusion lock.

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 release() or unlock(). If you lock 5 times, then you should call release() 5 times as well before it will be unlocked. However, if you lock 5 times, just one call to unlock() will undo all 5 levels of locking.

Just remember, release() releases one level. But unlock() 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!
Implements a first-come-first-served Mutex as laid out on page 11 of:
"A First Come First Served Mutal Exclusion Algorithm with Small Communication Variables"
Edward A. Lycklama, Vassos Hadzilacos - Aug. 1991

Definition at line 40 of file MutexLock.h.

Public Member Functions

 MutexLock ()
 constructor, just calls the init() function.
void lock (int id)
 blocks (by busy looping on do_try_lock()) until a lock is achieved
bool try_lock (int id)
 attempts to get a lock, returns true if it succeeds
void release ()
 releases one recursive lock-level from whoever has the current lock
void unlock ()
 completely unlocks, regardless of how many times a recursive lock has been obtained
unsigned int get_lock_level () const
 returns the lockcount
int owner ()
 returns the current owner's id
void forget (int id)
 allows you to reset one of the possible owners, so another process can take its place. This is not tested

Static Public Attributes

static const unsigned int NO_OWNER = -1U
 marks as unlocked

Protected Member Functions

bool do_try_lock (unsigned int index, bool block)
 Does the work of trying to get a lock.
unsigned int lookup (int id)
 returns the internal index mapping to the id number supplied by the process
void init ()
 Doesn't do anything if you have the MUTEX_LOCK_ET_USE_SPINCOUNT undef'ed. Used to do a memset, but that was causing problems....
void spin ()
 If you find a way to sleep for a few microseconds instead of busy waiting, put it here.

Protected Attributes

door_t doors [num_doors]
 holds all the doors
unsigned int doors_used
 counts the number of doors used
unsigned int owner_index
 holds the door index of the current lock owner
unsigned int lockcount
 the depth of the lock, 0 when unlocked

Classes

struct  door_t
 Holds per process shared info, one of these per process. More...


Constructor & Destructor Documentation

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

constructor, just calls the init() function.

Definition at line 45 of file MutexLock.h.


Member Function Documentation

template<unsigned int num_doors>
bool MutexLock< num_doors >::do_try_lock unsigned int  index,
bool  block
[protected]
 

Does the work of trying to get a lock.

Pass true for block if you want it to use FCFS blocking instead of just returning right away if another process has the lock

Definition at line 170 of file MutexLock.h.

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

template<unsigned int num_doors>
void MutexLock< num_doors >::forget int  id  ) 
 

allows you to reset one of the possible owners, so another process can take its place. This is not tested

Definition at line 249 of file MutexLock.h.

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

returns the lockcount

Definition at line 71 of file MutexLock.h.

template<unsigned int num_doors>
void MutexLock< num_doors >::init  )  [inline, protected]
 

Doesn't do anything if you have the MUTEX_LOCK_ET_USE_SPINCOUNT undef'ed. Used to do a memset, but that was causing problems....

Definition at line 98 of file MutexLock.h.

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

template<unsigned int num_doors>
void MutexLock< num_doors >::lock int  id  ) 
 

blocks (by busy looping on do_try_lock()) until a lock is achieved

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

This is not a recursive lock - repeated locks still only require one release to undo them.

Todo:
  • I'd like to not use a loop here

Definition at line 124 of file MutexLock.h.

Referenced by MotionManager::func_begin(), MotionManager::InitAccess(), and MotionManager::lock().

template<unsigned int num_doors>
unsigned int MutexLock< num_doors >::lookup int  id  )  [protected]
 

returns the internal index mapping to the id number supplied by the process

Definition at line 230 of file MutexLock.h.

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

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

returns the current owner's id

Definition at line 74 of file MutexLock.h.

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

template<unsigned int num_doors>
void MutexLock< num_doors >::release  ) 
 

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

Definition at line 150 of file MutexLock.h.

Referenced by SharedQueue< 3 *1024, 100 >::done(), MutexLock< num_doors >::forget(), MotionManager::func_end(), MotionManager::InitAccess(), MotionManager::release(), and MutexLock< MAX_ACCESS >::unlock().

template<unsigned int num_doors>
void MutexLock< num_doors >::spin  )  [inline, protected]
 

If you find a way to sleep for a few microseconds instead of busy waiting, put it here.

Definition at line 100 of file MutexLock.h.

Referenced by MutexLock< num_doors >::do_try_lock(), and MutexLock< num_doors >::lock().

template<unsigned int num_doors>
bool MutexLock< num_doors >::try_lock int  id  ) 
 

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.

This is not a recursive lock - repeated locks still only require one release to undo them.

Definition at line 134 of file MutexLock.h.

Referenced by MotionManager::trylock().

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

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

Definition at line 68 of file MutexLock.h.


Member Data Documentation

template<unsigned int num_doors>
door_t MutexLock< num_doors >::doors[num_doors] [protected]
 

holds all the doors

Definition at line 115 of file MutexLock.h.

Referenced by MutexLock< num_doors >::do_try_lock(), MutexLock< num_doors >::forget(), MutexLock< num_doors >::lookup(), and MutexLock< num_doors >::release().

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

counts the number of doors used

Definition at line 116 of file MutexLock.h.

Referenced by MutexLock< num_doors >::forget(), and MutexLock< num_doors >::lookup().

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

the depth of the lock, 0 when unlocked

Definition at line 118 of file MutexLock.h.

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

template<unsigned int num_doors>
const unsigned int MutexLock< num_doors >::NO_OWNER = -1U [static]
 

marks as unlocked

Definition at line 42 of file MutexLock.h.

Referenced by MutexLock< num_doors >::do_try_lock(), MutexLock< num_doors >::forget(), MutexLock< num_doors >::lookup(), and MutexLock< num_doors >::release().

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

holds the door index of the current lock owner

Definition at line 117 of file MutexLock.h.

Referenced by MutexLock< num_doors >::do_try_lock(), and MutexLock< num_doors >::release().


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

Tekkotsu v2.2.2
Generated Tue Jan 4 15:45:29 2005 by Doxygen 1.4.0