Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

phMutex Class Reference
[Threading and SynchronizationThread Safe]

#include <phMutex.h>

Inheritance diagram for phMutex:

phObject phCondition phFilter phLamportSystem phList phListNode phLiveObject phPlayerDevice phSemaphore phSimpleVision phSocket phSystem phTimeList List of all members.

Detailed Description

phMutex provides platform independent locking mechanisms to the Phission code. The phMutex is a recursive implemented mutex. Multiple mutexes can be obtained by a thread by calling the phMutex::lock() method and each successful phMutex::lock() should be matched with a call to the phMutex::unlock() method. If there isn't one phMutex::unlock() call for every phMutex::lock()/phMutextryLock() call that succeeded, deadlock could occur in other threads that are trying to obtain the lock. Recursive mutexes are necessary for a system such as Phission where a call to the current object's method may also call other methods that belong to the same instance of the object. Those other methods could be called on their own as well. Without recursive mutexes, the one scope calling into another scope (scope being separate methods or blocks of code) will deadlock on the second attempt at locking.

This is the main mechanism for providing thread saftey. All thread safe objects are derived from this object at some level whether directly or through a parent class. When mutual exlusion is needed, the Phission classes lock the object to get exlusive access to member variables. In most cases, inheriting from phMutex allows the Phission classes to act as monitors where only one thread at a time is permitted access to the class's private members through a method. The method locks the "this" mutex right before shared data is accessed. The phTHIS*_LOCK macros are used to reduce the visible code required for locking. (see phTHIS_LOCK(l))

However, there are some cases where more parallelism is introduced, such as in phLiveObject::update(). In this method the child/inheriting cass doesn't lock the "this" mutex but rather a separate phMutex variable. This provides two paths of locking, one path that requires accessing the 'this' object lock and the other path requiring that the secondary phMutex variable be acquired. Other operations can still occur on the "this" lock while one thread is blocked on an update semaphore and waiting for the update semaphore to be posted. The update semaphore is managed by the phLiveCookie class.

  int main ( int argc, char *argv[] )
      phMutex mutex;
      int locked = 0;
      // Lock the mutex; This increases the count of locked

      // Pretend we got an error
      goto error;
      // Unlock the mutex; The macro will prevent us from 
      // unlocking more than we've locked 

      return 0;

      return -1;

See also:

Definition at line 282 of file phMutex.h.

Public Member Functions

 phMutex ()
virtual ~phMutex ()
int lock ()
int trylock ()
int unlock ()

Protected Member Functions

int incLockCount ()
int decLockCount ()
uint32_t getLockCount ()

Protected Attributes

void * m_private_mutex

Private Attributes

ph_mutex_info m_mutex_info
uint32_t m_locked_count
uintmax_t m_owner

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

Copyright (C) 2002 - 2007 Philip D.S. Thoren ( )
University Of Massachusetts at Lowell
Robotics Lab Logo

Generated on Sat Jun 16 02:45:00 2007 for phission by  doxygen 1.4.4