KKB::GoalKeeperSimple Class Reference

A simple/ light-weight implementation of critical section blocking. More...

#include <GoalKeeperSimple.h>

Public Types
typedef GoalKeeperSimple *	GoalKeeperSimplePtr

Public Member Functions
bool	Blocked ()
	Will return true if any thread lock on this instance of "GoalKeeperSimple". More...
bool	BlockedByAnotherThread ()
	Returns true if a different thread has this instance of "GoalKeeperSimple" 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
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 GoalKeeperSimplePtr &_newGoalKeeper)
	Create a GoalKeeperSimple object and avoid a race condition doing it. More...
static void	CreateAndStartBlock (const KKStr &_name, volatile GoalKeeperSimplePtr &_newGoalKeeper, bool &_didNotExistYet)
	Create a GoalKeeperSimple object and avoid a race condition doing it. More...
static void	Destroy (volatile GoalKeeperSimplePtr &_goalKeeperInstance)
	Destroys an existing instance of GoalKeeperSimple. 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< GoalKeeperSimple >

Detailed Description

A simple/ light-weight implementation of critical section blocking.

Definition at line 29 of file GoalKeeperSimple.h.

Member Typedef Documentation

typedef GoalKeeperSimple* KKB::GoalKeeperSimple::GoalKeeperSimplePtr

Definition at line 32 of file GoalKeeperSimple.h.

Member Function Documentation

bool GoalKeeperSimple::Blocked

(

)

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

Definition at line 76 of file GoalKeeperSimple.cpp.

{
  return  blocked;
}  /* Blocked */

bool GoalKeeperSimple::BlockedByAnotherThread

(

)

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

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

Definition at line 83 of file GoalKeeperSimple.cpp.

References KKB::osGetThreadId().

{
  if  (!blocked)
    return false;

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

kkint32 GoalKeeperSimple::BlockerThreadId

(

)

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

Definition at line 404 of file GoalKeeperSimple.cpp.

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

void GoalKeeperSimple::Create ( const KKStr &  _name, volatile GoalKeeperSimplePtr &  _newGoalKeeper  )

static

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

In case two different threads try to create the same GoalKeeperSimple 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 GoalKeeperSimple 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 160 of file GoalKeeperSimple.cpp.

References KKB::GoalKeeperSimpleList::GoalKeeperSimpleList().

Referenced by KKB::MsgQueue::MsgQueue().

{
#if  defined(WIN32)
  HANDLE  mutexCreateHandle = CreateMutex (NULL,                 /**< default security attributes */
                                           false,                /**< initially not owned */
                                           "GoalKeeperClass"
                                          );
  if  (!mutexCreateHandle)
  {
    KKStr errMsg = "GoalKeeperSimple::Create   ***ERROR***   CreateMutex failed; returned back NULL;  _name:" + _name;
    cerr << endl << errMsg << endl << endl;
    throw KKException (errMsg);
  }

  WaitForSingleObject (mutexCreateHandle, INFINITE);

  if  (_newGoalKeeper == NULL)
  {
    _newGoalKeeper = new GoalKeeperSimple (_name);
    if  (existingGoalKeepers == NULL)
    {
      existingGoalKeepers = new GoalKeeperSimpleList (true);
      atexit (GoalKeeperSimple::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
         << "GoalKeeperSimple::Create  Error[" << errno << "] opening '/GoalKeeperSimple' Semaphore." << std::endl
         << std::endl;

    perror("GoalKeeperSimple::Create   Error Opening Semaphore  'GoalKeeperSimple'");

    throw "GoalKeeperSimple::Create    Error opening 'GoalKeeperSimple'.";
  }

  sem_wait (semHandle);

  if  (_newGoalKeeper == NULL)
  {
    _newGoalKeeper = new GoalKeeperSimple (_name);
    if  (existingGoalKeepers == NULL)
    {
      existingGoalKeepers = new GoalKeeperSimpleList (true);
      atexit (GoalKeeperSimple::FinalCleanUp);
    }
    existingGoalKeepers->PushOnBack (_newGoalKeeper);
  }

  sem_post (semHandle);
  sem_close (semHandle);
#endif
}  /* Create */

void GoalKeeperSimple::CreateAndStartBlock ( const KKStr &  _name, volatile GoalKeeperSimplePtr &  _newGoalKeeper, bool &  _didNotExistYet  )

static

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

Create a new instance of a GoalKeeperSimple 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 GoalKeeperSimple 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 GoalKeeperSimple 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 GoalKeeperSimple instance; if it already existed will return as false.
[in]	_name	Name to be assigned to GoalKeeperSimple object.
[in,out]	_newGoalKeeper	A pointer to the GoalKeeperSimple 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 231 of file GoalKeeperSimple.cpp.

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

{
#if  defined(WIN32)
  HANDLE  mutexCreateHandle = CreateMutex (NULL,                 /**< default security attributes. */
                                           false,                /**< initially not owned.         */
                                           "GoalKeeperClass"
                                          ); 
  if  (!mutexCreateHandle)
  {
    KKStr errMsg = "GoalKeeperSimple::CreateAndStartBlock   ***ERROR***   CreateMutex failed; returned back NULL;  _name:" + _name;
    cerr << endl << errMsg << endl << endl;
    throw KKException(errMsg);
  }

  WaitForSingleObject (mutexCreateHandle, INFINITE);

  if  (_newGoalKeeper == NULL)
  {
    _didNotExistYet = true;
    _newGoalKeeper = new GoalKeeperSimple (_name);

    if  (existingGoalKeepers == NULL)
    {
      existingGoalKeepers = new GoalKeeperSimpleList (true);
      atexit (GoalKeeperSimple::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
         << "GoalKeeperSimple::Create  Error[" << errno << "] opening '/GoalKeeperSimple' Semaphore." << std::endl
         << std::endl;

    perror("GoalKeeperSimple::Create   Error Opening Semaphore  'GoalKeeperSimple'");

    throw "GoalKeeperSimple::Create    Error opening 'GoalKeeperSimple'.";
  }

  sem_wait (semHandle);

  if  (_newGoalKeeper == NULL)
  {
    _didNotExistYet = true;
    _newGoalKeeper = new GoalKeeperSimple (_name);
    if  (existingGoalKeepers == NULL)
    {
      existingGoalKeepers = new GoalKeeperSimpleList (true);
      atexit (GoalKeeperSimple::FinalCleanUp);
    }
    existingGoalKeepers->PushOnBack (_newGoalKeeper);
  }
  else
  {
    _didNotExistYet = false;
  }

  _newGoalKeeper->StartBlock ();

  sem_post (semHandle);
  sem_close (semHandle);
#endif
}  /* CreateAndStartBlock */

void GoalKeeperSimple::Destroy ( volatile GoalKeeperSimplePtr &  _goalKeeperInstance )

static

Destroys an existing instance of GoalKeeperSimple.

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 GoalKeeperSimple instance only one of them will actually destroy the instance.

Parameters

[in,out]

_goalKeeperInstance

Instance of GoalKeeperSimple that is to be destroyed. Upon return it will be set to NULL.

< default security attributes

< initially not owned

Definition at line 313 of file GoalKeeperSimple.cpp.

Referenced by KKB::MsgQueue::~MsgQueue().

{
#if  defined(WIN32)
  HANDLE  mutexCreateHandle = CreateMutex (NULL,                 /**< default security attributes */
                                           false,                /**< initially not owned */
                                           "GoalKeeperClass"
                                          ); 
  if (!mutexCreateHandle)
  {
    KKStr errMsg = "GoalKeeperSimple::Destroy   ***ERROR***   CreateMutex failed; returned back NULL";
    cerr << endl << errMsg << endl << endl;
    throw KKException(errMsg);
  }

  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
         << "GoalKeeperSimple::Create  Error[" << errno << "] opening '/GoalKeeperSimple' Semaphore." << std::endl
         << std::endl;

    perror("GoalKeeperSimple::Create   Error Opening Semaphore  'GoalKeeperSimple'");

    throw "GoalKeeperSimple::Create    Error opening 'GoalKeeperSimple'.";
  }

  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 GoalKeeperSimple::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 139 of file GoalKeeperSimple.cpp.

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

Referenced by KKB::MsgQueue::AddMsg(), KKB::MsgQueue::AddMsgs(), KKB::MsgQueue::GetAllMsgs(), KKB::MsgQueue::GetCopyOfLastMsg(), KKB::MsgQueue::GetNextMsg(), and KKB::MsgQueue::MemoryConsumedEstimated().

{
  kkint32  curThreadId = KKB::osGetThreadId ();
  if  (!blocked)
    throw KKB::KKException ("GoalKeeperSimple::EndBlock    Name[" + name + "]  Is not currently blocked.");

  if  (curThreadId != blockerThreadId)
    throw KKB::KKException ("GoalKeeperSimple::EndBlock    Name[" + name + "]  ThreadId[" + blockerThreadId + "] Currently holds Block;  our ThreadId[" + curThreadId + "]");

  --levels;
  if  (levels < 1)
  {
    blocked = false;
    blockerThreadId = -1;
    CriticalSectionEnd ();
  }
}  /* EndBlock */

void GoalKeeperSimple::FinalCleanUp ( )

static

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

Definition at line 392 of file GoalKeeperSimple.cpp.

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

kkint32 GoalKeeperSimple::MemoryConsumedEstimated

(

)

const

Definition at line 69 of file GoalKeeperSimple.cpp.

References KKB::KKStr::MemoryConsumedEstimated().

Referenced by KKB::MsgQueue::MsgQueue().

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

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

inline

Definition at line 122 of file GoalKeeperSimple.h.

{return  name;}

void GoalKeeperSimple::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 117 of file GoalKeeperSimple.cpp.

References KKB::osGetThreadId().

Referenced by KKB::MsgQueue::AddMsg(), KKB::MsgQueue::AddMsgs(), CreateAndStartBlock(), KKB::MsgQueue::GetAllMsgs(), KKB::MsgQueue::GetCopyOfLastMsg(), KKB::MsgQueue::GetNextMsg(), and KKB::MsgQueue::MemoryConsumedEstimated().

{
  kkint32  curThreadId = KKB::osGetThreadId ();

  if  (blocked  &&  (curThreadId == blockerThreadId))
  {
    ++levels;
  }
  else
  {
    CriticalSectionStart ();
    levels = 1;
    blockerThreadId = curThreadId;
    blocked = true;
  }

  return;
}   /* StartBlock */

Friends And Related Function Documentation

friend class KKQueue< GoalKeeperSimple >

friend

Definition at line 41 of file GoalKeeperSimple.h.

---

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

• C:/Users/Kurt/GitHub/KSquareLibraries/KKBase/GoalKeeperSimple.h
• C:/Users/Kurt/GitHub/KSquareLibraries/KKBase/GoalKeeperSimple.cpp