MutexLock< num_doors > Class Template Reference
#include <MutexLock.h>
Inheritance diagram for MutexLock< num_doors >:
Detailed Description
template<unsigned int num_doors>
class MutexLock< num_doors >
A software only mutual exclusion lock. (does not depend on processor or OS support).
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!
"A First Come First Served Mutal Exclusion Algorithm with Small Communication Variables"
Edward A. Lycklama, Vassos Hadzilacos - Aug. 1991
Definition at line 302 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 | 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 | |
| void | forget (int id) |
| allows you to reset one of the possible owners, so another process can take its place. This is not tested | |
Protected Member Functions | |
| virtual void | useResource (Resource::Data &) |
| marks the resource as in use | |
| virtual void | releaseResource (Resource::Data &) |
| releases the resource | |
| 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 | |
Friends | |
| class | MarkScope |
Classes | |
| struct | door_t |
| Holds per process shared info, one of these per process. More... | |
Constructor & Destructor Documentation
Member Function Documentation
| 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 486 of file MutexLock.h.
Referenced by MutexLock< num_doors >::forget(), MutexLock< num_doors >::lock(), and MutexLock< num_doors >::try_lock().
| 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 572 of file MutexLock.h.
| unsigned int MutexLock< num_doors >::get_lock_level | ( | ) | const [inline] |
| 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 375 of file MutexLock.h.
Referenced by MutexLock< MAX_ACCESS >::MutexLock().
| 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.
- Todo:
- I'd like to not use a loop here
Definition at line 405 of file MutexLock.h.
Referenced by MotionManager::func_begin(), WorldStatePool::getCurrentWriteState(), MotionManager::InitAccess(), MotionManager::lock(), and WorldStatePool::WorldStatePool().
| 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 553 of file MutexLock.h.
Referenced by MutexLock< num_doors >::forget(), MutexLock< num_doors >::lock(), and MutexLock< num_doors >::try_lock().
| int MutexLock< num_doors >::owner | ( | ) | const [inline] |
returns the current owner's id
Definition at line 338 of file MutexLock.h.
Referenced by WorldStatePool::isComplete(), MutexLock< num_doors >::lock(), and MutexLock< num_doors >::try_lock().
| void MutexLock< num_doors >::releaseAll | ( | ) | [inline] |
completely unlocks, regardless of how many times a recursive lock has been obtained
Definition at line 332 of file MutexLock.h.
Referenced by MutexLock< num_doors >::forget(), and WorldStatePool::getCurrentWriteState().
| virtual void MutexLock< num_doors >::releaseResource | ( | Resource::Data & | ) | [inline, protected, virtual] |
| 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 377 of file MutexLock.h.
Referenced by MutexLock< num_doors >::do_try_lock().
| 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.
Definition at line 426 of file MutexLock.h.
Referenced by MotionManager::trylock().
| void MutexLock< num_doors >::unlock | ( | ) | [inline] |
releases one recursive lock-level from whoever has the current lock
Definition at line 454 of file MutexLock.h.
Referenced by WorldStatePool::doneWritingState(), MotionManager::func_end(), MotionManager::InitAccess(), and MotionManager::unlock().
| virtual void MutexLock< num_doors >::useResource | ( | Resource::Data & | ) | [inline, protected, virtual] |
Friends And Related Function Documentation
friend class MarkScope [friend] |
Definition at line 349 of file MutexLock.h.
Member Data Documentation
holds all the doors
Definition at line 396 of file MutexLock.h.
Referenced by MutexLock< num_doors >::do_try_lock(), MutexLock< num_doors >::forget(), MutexLock< num_doors >::lookup(), and MutexLock< num_doors >::unlock().
unsigned int MutexLock< num_doors >::doors_used [protected] |
counts the number of doors used
Definition at line 397 of file MutexLock.h.
Referenced by MutexLock< num_doors >::forget(), and MutexLock< num_doors >::lookup().
the depth of the lock, 0 when unlocked
Definition at line 399 of file MutexLock.h.
Referenced by MutexLock< num_doors >::lock(), MutexLock< num_doors >::try_lock(), and MutexLock< num_doors >::unlock().
unsigned int MutexLock< num_doors >::owner_index [protected] |
holds the door index of the current lock owner
Definition at line 398 of file MutexLock.h.
Referenced by MutexLock< num_doors >::do_try_lock(), and MutexLock< num_doors >::unlock().
The documentation for this class was generated from the following file:
