#include <GoalKeeper.h>

Public Types
typedef GoalKeeper *	GoalKeeperPtr

Public Member Functions
bool	Blocked ()
	Will return true if any thread lock on this instance of "GoalKeeper". More...

bool	BlockedByAnotherThread ()
	Returns true if a different thread has this instance of "GoalKeeper" locked. More...

kkint32	BlockerThreadId ()
	ThreadId of thread that currently holds the Block -1 indicates no Block. More...

void	EndBlock ()
	Ends the block and allows other threads to pass through StatBlock. More...

kkint32	MemoryConsumedEstimated () const

const KKStr &	Name () const

kkint32	NumBlockedThreads ()
	Returns the number of threads that are waiting to establish a lock on this instance. More...

void	StartBlock ()
	Initiates a Block as long as another thread has not already locked this object. More...

Static Public Member Functions
static void	Create (const KKStr &_name, volatile GoalKeeperPtr &_newGoalKeeper)
	Create a GoalKeeper object and avoid a race condition doing it. More...

static void	CreateAndStartBlock (const KKStr &_name, volatile GoalKeeperPtr &_newGoalKeeper, bool &_didNotExistYet)
	Create a GoalKeeper object and avoid a race condition doing it. More...

static void	Destroy (volatile GoalKeeperPtr &_goalKeeperInstance)
	Destroys an existing instance of GoalKeeper. More...

static void	FinalCleanUp ()
	Will be registered with 'atexit' so that it will be called when program is unloaded from memory. More...

Friends
class	KKQueue< GoalKeeper >

Detailed Description

Definition at line 38 of file GoalKeeper.h.

Member Typedef Documentation

typedef GoalKeeper* KKB::GoalKeeper::GoalKeeperPtr

Definition at line 41 of file GoalKeeper.h.

Member Function Documentation

bool GoalKeeper::Blocked ( )

Will return true if any thread lock on this instance of "GoalKeeper".

Definition at line 173 of file GoalKeeper.cpp.

 {
   return  blocked;
 }  /* Blocked */

bool GoalKeeper::BlockedByAnotherThread ( )

Returns true if a different thread has this instance of "GoalKeeper" locked.

GoalKeeper keeps track of which thread has a lock on this instance of 'GoalKeeper'. This way we know if the calling thread is not the one to have a lock on the thread.

Definition at line 180 of file GoalKeeper.cpp.

References KKB::osGetThreadId().

 {
   if  (!blocked)
     return false;
 
   kkint32  curThreadId = KKB::osGetThreadId ();
   return  (blocked  &&  (curThreadId != blockerThreadId));
 }

kkint32 GoalKeeper::BlockerThreadId ( )

ThreadId of thread that currently holds the Block -1 indicates no Block.

Definition at line 588 of file GoalKeeper.cpp.

 {
   kkint32  x = 0;
   x =  blockerThreadId;
   return  x;
 }

void GoalKeeper::Create	(	const KKStr &	_name,
		volatile GoalKeeperPtr &	_newGoalKeeper
	)

static

Create a GoalKeeper object and avoid a race condition doing it.

In case two different threads try to create the same GoalKeeper at the same time you only want one of them to succeed and the other to use same GaolKeeper object.

Parameters

[in]	_name	Name of Goal Keeper object that you want to create.
[in,out]	_newGoalKeeper	You pass this in. Create will block out the critical region that creates the GoalKeeper object. If it was already created, that is != NULL will just return not changing its value. If it is still NULL in the critical section it will create a new instance and set this parameter to its address.

< default security attributes

< initially not owned

Definition at line 346 of file GoalKeeper.cpp.

References KKB::GoalKeeperList::GoalKeeperList().

Referenced by KKLSC::ScannerFile::CreateGoalie(), KKB::Raster::Initialize(), KKB::RasterBuffer::RasterBuffer(), and KKLSC::ScannerHeaderFields::ScannerHeaderFields().

 {
 #if  defined(WIN32)
   HANDLE  mutexCreateHandle = CreateMutex (NULL,                 /**< default security attributes */
                                            false,                /**< initially not owned */
                                            "GoalKeeperClass"
                                           );
   if  (mutexCreateHandle == NULL)
     throw KKException ("GoalKeeper::Create  failed to get handle to Mutex Object 'GoalKeeperClass'.");
 
   WaitForSingleObject (mutexCreateHandle, INFINITE);
 
   if  (_newGoalKeeper == NULL)
   {
     _newGoalKeeper = new GoalKeeper (_name);
     if  (existingGoalKeepers == NULL)
     {
       existingGoalKeepers = new GoalKeeperList (true);
       atexit (GoalKeeper::FinalCleanUp);
     }
     existingGoalKeepers->PushOnBack (_newGoalKeeper);
   }
 
   ReleaseMutex (mutexCreateHandle);
   CloseHandle(mutexCreateHandle);
 #else
   sem_t*  semHandle = sem_open ("GoalKeeperClass", O_CREAT, 0644, 1);
   if  (semHandle == SEM_FAILED)
   {
     cout << std::endl
          << "GoalKeeper::Create  Error[" << errno << "] opening '/GoalKeeper' Semaphore." << std::endl
          << std::endl;
 
     perror("GoalKeeper::Create   Error Opening Semaphore  'GoalKeeper'");
 
     throw "GoalKeeper::Create    Error opening 'GoalKeeper'.";
   }
 
   sem_wait (semHandle);
 
   if  (_newGoalKeeper == NULL)
   {
     _newGoalKeeper = new GoalKeeper (_name);
     if  (existingGoalKeepers == NULL)
     {
       existingGoalKeepers = new GoalKeeperList (true);
       atexit (GoalKeeper::FinalCleanUp);
     }
     existingGoalKeepers->PushOnBack (_newGoalKeeper);
   }
 
   sem_post (semHandle);
   sem_close (semHandle);
 #endif
 }  /* Create */

void GoalKeeper::CreateAndStartBlock	(	const KKStr &	_name,
		volatile GoalKeeperPtr &	_newGoalKeeper,
		bool &	_didNotExistYet
	)

static

Create a GoalKeeper object and avoid a race condition doing it.

Create a new instance of a GoalKeeper object if it has not already been done and locks it if we create it.

Similar to 'Create' except it will also call the StartBlock method. There is also an additional parameter that will let you know if your call was responsible for creating it.

In case two different threads try to create the same GoalKeeper at the same time you only want one of them to succeed and the other to use same GaolKeeper object.

Parameters

[in]	_name	Name of Goal Keeper object that you want to create.
[in,out]	_newGoalKeeper	You pass this in. Create will block out the critical region that creates the GoalKeeper object. If it was already created, that is != NULL will just return not changing its value. If it is still NULL in the critical section it will create a new instance and set this parameter to its address.
[out]	_didNotExistYet	Indicates if this call had to create the GoalKeeper instance; if it already existed will return as false.
[in]	_name	Name to be assigned to GoalKeeper object.
[in,out]	_newGoalKeeper	A pointer to the GoalKeeper that already exists or to new one that got created.
[out]	_didNotExistYet	Indicates if the call to 'CreateAndStartBlock' had to create a new instance.

< default security attributes.

< initially not owned.

Definition at line 413 of file GoalKeeper.cpp.

References KKB::GoalKeeperList::GoalKeeperList(), and StartBlock().

 {
 #if  defined(WIN32)
   HANDLE  mutexCreateHandle = CreateMutex (NULL,                 /**< default security attributes. */
                                            false,                /**< initially not owned.         */
                                            "GoalKeeperClass"
                                           );
   if (mutexCreateHandle == NULL)
     throw KKException("GoalKeeper::CreateAndStartBlock  failed to get handle to Mutex Object 'GoalKeeperClass'.");
 
   WaitForSingleObject (mutexCreateHandle, INFINITE);
 
   if  (_newGoalKeeper == NULL)
   {
     _didNotExistYet = true;
     _newGoalKeeper = new GoalKeeper (_name);
 
     if  (existingGoalKeepers == NULL)
     {
       existingGoalKeepers = new GoalKeeperList (true);
       atexit (GoalKeeper::FinalCleanUp);
     }
     existingGoalKeepers->PushOnBack (_newGoalKeeper);
   }
   else
   {
     _didNotExistYet = false;
   }
 
   _newGoalKeeper->StartBlock ();
 
   ReleaseMutex (mutexCreateHandle);
   CloseHandle(mutexCreateHandle);
 #else
   sem_t*  semHandle = sem_open ("GoalKeeperClass", O_CREAT, 0644, 1);
   if  (semHandle == SEM_FAILED)
   {
     cout << std::endl
          << "GoalKeeper::Create  Error[" << errno << "] opening '/GoalKeeper' Semaphore." << std::endl
          << std::endl;
 
     perror("GoalKeeper::Create   Error Opening Semaphore  'GoalKeeper'");
 
     throw "GoalKeeper::Create    Error opening 'GoalKeeper'.";
   }
 
   sem_wait (semHandle);
 
   if  (_newGoalKeeper == NULL)
   {
     _didNotExistYet = true;
     _newGoalKeeper = new GoalKeeper (_name);
     if  (existingGoalKeepers == NULL)
     {
       existingGoalKeepers = new GoalKeeperList (true);
       atexit (GoalKeeper::FinalCleanUp);
     }
     existingGoalKeepers->PushOnBack (_newGoalKeeper);
   }
   else
   {
     _didNotExistYet = false;
   }
 
   _newGoalKeeper->StartBlock ();
 
   sem_post (semHandle);
   sem_close (semHandle);
 #endif
 }  /* CreateAndStartBlock */

void GoalKeeper::Destroy ( volatile GoalKeeperPtr & _goalKeeperInstance )

static

Destroys an existing instance of GoalKeeper.

Use this method rather than calling the destructor directly. This way the 'existingGoalKeepers' data member can be kept up to date. If for some reason two different threads managed to call this method for the same GoalKeeper instance only one of them will actually destroy the instance.

Parameters

[in,out] _goalKeeperInstance Instance of GoalKeeper that is to be destroyed. Upon return it will be set to NULL.

< default security attributes

< initially not owned

Definition at line 491 of file GoalKeeper.cpp.

Referenced by KKMLL::FileDesc::FinalCleanUp(), KKMLL::MLClass::FinalCleanUp(), KKB::Raster::FinalCleanUp(), KKB::RasterBuffer::~RasterBuffer(), KKLSC::ScannerFile::~ScannerFile(), and KKLSC::ScannerHeaderFields::~ScannerHeaderFields().

 {
 #if  defined(WIN32)
   HANDLE  mutexCreateHandle = CreateMutex (NULL,                 /**< default security attributes */
                                            false,                /**< initially not owned */
                                            "GoalKeeperClass"
                                           ); 
   if (mutexCreateHandle == NULL)
     throw KKException("GoalKeeper::Destroy  failed to get handle to Mutex Object 'GoalKeeperClass'.");
 
   WaitForSingleObject (mutexCreateHandle, INFINITE);
 
   if  (_goalKeeperInstance == NULL)
   {
     // Some other thread managed to destroy this instance.
   }
   else
   {
     kkint32  existingInstanceIdx =  existingGoalKeepers->PtrToIdx (_goalKeeperInstance);
     if  (existingInstanceIdx < 0)
     {
       // If not in list then a  different thread beat us to destroying this instance or it was never created to start with.
     }
     else
     {
       existingGoalKeepers->DeleteEntry (_goalKeeperInstance);
       delete  _goalKeeperInstance;
       _goalKeeperInstance = NULL;
     }
   }
 
   ReleaseMutex (mutexCreateHandle);
   CloseHandle(mutexCreateHandle);
 #else
   sem_t*  semHandle = sem_open ("GoalKeeperClass", O_CREAT, 0644, 1);
   if  (semHandle == SEM_FAILED)
   {
     cout << std::endl
          << "GoalKeeper::Create  Error[" << errno << "] opening '/GoalKeeper' Semaphore." << std::endl
          << std::endl;
 
     perror("GoalKeeper::Create   Error Opening Semaphore  'GoalKeeper'");
 
     throw "GoalKeeper::Create    Error opening 'GoalKeeper'.";
   }
 
   sem_wait (semHandle);
 
   if  (_goalKeeperInstance == NULL)
   {
     // Some other thread managed to destroy this instance.
   }
   else
   {
     kkint32  existingInstanceIdx =  existingGoalKeepers->PtrToIdx (_goalKeeperInstance);
     if  (existingInstanceIdx >= 0)
     {
       // If not in list then a  different thread beat us to destroying this instance or it was never created to start with.
     }
     else
     {
       existingGoalKeepers->DeleteEntry (_goalKeeperInstance);
       delete  _goalKeeperInstance;
       _goalKeeperInstance = NULL;
     }
   }
 
   sem_post (semHandle);
   sem_close (semHandle);
 #endif
 
 }  /* Destroy */

void GoalKeeper::EndBlock ( )

Ends the block and allows other threads to pass through StatBlock.

Decrements the variable 'blockerDepth' by one. Once 'blockerDepth' is equal zero the Block on this instance is removed. The idea is that for each time in a row a Thread calls StartBlock it has to call EndBlock the same number of times.

Definition at line 295 of file GoalKeeper.cpp.

References KKB::KKStr::Concat(), KKB::KKStr::operator+(), KKB::operator+(), and KKB::osGetThreadId().

Referenced by KKLSC::ScannerHeaderFields::Add(), KKB::RasterBuffer::AddRaster(), KKLSC::ScannerFile::AddStartStopEntryToIndexFile(), KKLSC::ScannerFile::BuildFrameOffsets(), KKMLL::MLClass::ChangeNameOfClass(), KKLSC::ScannerHeaderFields::Clear(), KKMLL::MLClass::CreateNewMLClass(), KKLSC::ScannerFile::DetermineFrameOffsetForFrame(), KKB::GlobalGoalKeeper::EndBlock(), KKLSC::ScannerHeaderFields::EndBlock(), KKLSC::ScannerHeaderFields::FieldExists(), KKMLL::FileDesc::FinalCleanUp(), KKMLL::MLClass::FinalCleanUp(), KKLSC::ScannerFile::FrameRead(), KKB::RasterBuffer::GetCopyOfLastImage(), KKMLL::FileDesc::GetExistingFileDesc(), KKLSC::ScannerFile::GetFrameOffset(), KKLSC::ScannerFile::GetNextLine(), KKB::RasterBuffer::GetNextRaster(), KKLSC::ScannerHeaderFields::GetValue(), KKMLL::MLClass::GlobalClassList(), KKB::Raster::Initialize(), KKLSC::ScannerHeaderFields::MemoryConsumedEstimated(), KKB::RasterBuffer::MemoryConsumedEstimated(), KKMLL::MLClass::ResetAllParentsToAllClasses(), KKLSC::ScannerFile::SkipNextLine(), and KKLSC::ScannerFile::UpdateFrameOffset().

 {
   kkint32  curProcessorId = KKB::osGetThreadId ();
 
   kkint32 errorCode = 0;   // 0=No Error;  
                          // 1=There is no Block
                          // 2=Different thread holds the block
                          // 3=Failure to get a lock
 
   {
     CriticalSectionStart ();
   
     if  (!blocked)
     {
       errorCode = 1;
     }
     
     else if  (curProcessorId != blockerThreadId)
     {
       errorCode = 2;
     }
 
     else
     {
       blockerDepth--;
       if  (blockerDepth < 1)
       {
         blocked = false;
         blockerThreadId = -1;
         blockerDepth = 0;
       }
     }
 
     CriticalSectionEnd ();
   }
 
   if  (errorCode == 0)
     return;
 
   else if  (errorCode == 1)
     throw KKStr ("GoalKeeper::EndBlock    Name[" + name + "]  There was no block established.");
 
   else if  (errorCode == 2)
     throw KKStr ("GoalKeeper::EndBlock    Name[" + name + "]  ThreadId[" + curProcessorId + "] Currently holds Block;  our ThreadId[" + curProcessorId + "]");
 
   return;
 }  /* EndBlock */

void GoalKeeper::FinalCleanUp ( )

static

Will be registered with 'atexit' so that it will be called when program is unloaded from memory.

Definition at line 566 of file GoalKeeper.cpp.

 {
   if  (existingGoalKeepers)
   {
     delete  existingGoalKeepers;
     existingGoalKeepers = NULL;
   }
 }

kkint32 GoalKeeper::MemoryConsumedEstimated ( ) const

Definition at line 166 of file GoalKeeper.cpp.

References KKB::KKStr::MemoryConsumedEstimated().

Referenced by KKLSC::ScannerHeaderFields::MemoryConsumedEstimated(), and KKB::RasterBuffer::RasterBuffer().

 {
   return  (sizeof (GoalKeeper) + name.MemoryConsumedEstimated ());
 }

const KKStr& KKB::GoalKeeper::Name ( ) const

inline

Definition at line 131 of file GoalKeeper.h.

131 {return name;}

kkint32 GoalKeeper::NumBlockedThreads ( )

Returns the number of threads that are waiting to establish a lock on this instance.

Definition at line 579 of file GoalKeeper.cpp.

Referenced by KKLSC::ScannerFile::BuildFrameOffsets().

 {
   kkint32  x = 0;
   x =  numBlockedThreads;
   return  x;
 }

void GoalKeeper::StartBlock ( )

Initiates a Block as long as another thread has not already locked this object.

If it is already blocked processor will sleep and then try again. As long as the variable 'blockerDepth'is greater than zero this instance will be considered blocked. Once a thread has the instance blocked it will increment 'blockerDepth' and return to caller.

Definition at line 214 of file GoalKeeper.cpp.

References KKB::osGetThreadId(), and KKB::osSleepMiliSecs().

 {
   kkint32  curThreadId = KKB::osGetThreadId ();
   
   bool    firstPassThruLoop = true;
   bool    weAreBlocked      = true;
   kkuint32  milliSecsBlocked  = 0;
 
   while  (weAreBlocked)
   {
     CriticalSectionStart ();
 
     if  (firstPassThruLoop)
       numBlockedThreads++;
 
     if  (blocked)
     {
       if  (curThreadId == blockerThreadId)
       {
         // We are the thread that already holds the block;  so okay for us 
         // to process.
         blockerDepth++;
         weAreBlocked = false;
         numBlockedThreads--;
       }
       else
       {
         weAreBlocked = true;
 #if  defined(GOALKEEPER_DEBUG)
         blockedStats->PushOnBack (new BlockedStat (curThreadId, blockerThreadId, milliSecsBlocked, numBlockedThreads));
 #endif
       }
     }
     else
     {
       // No one holds the lock;  so we can take it.
       blocked = true;
       blockerDepth = 1;
       blockerThreadId = curThreadId;
       weAreBlocked = false;
       numBlockedThreads--;
     }
 
     CriticalSectionEnd ();
 
     if  (weAreBlocked)
     {
       if  (milliSecsBlocked < 10)
       {
         osSleepMiliSecs (1);
         milliSecsBlocked++;
       }
 
       else if  (milliSecsBlocked < 200)
       {
         osSleepMiliSecs (10);
         milliSecsBlocked += 10;
       }
 
       else if  (milliSecsBlocked < 10000)
       {
         osSleepMiliSecs (100);
         milliSecsBlocked += 100;
       }
 
       else
       {
         osSleepMiliSecs (400);
         milliSecsBlocked += 400;
       }
     }
 
     firstPassThruLoop = false;
   }
 
   return;
 }   /* StartBlock */

Friends And Related Function Documentation

friend class KKQueue< GoalKeeper >

friend

Definition at line 50 of file GoalKeeper.h.

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

C:/Users/Kurt/GitHub/KSquareLibraries/KKBase/GoalKeeper.h
C:/Users/Kurt/GitHub/KSquareLibraries/KKBase/GoalKeeper.cpp

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

Member Function Documentation

Friends And Related Function Documentation