Wefts::CriticalSection Class Reference

#include <wefts_critical.h>

Inheritance diagram for Wefts::CriticalSection:

[legend]Collaboration diagram for Wefts::CriticalSection:

[legend]List of all members.

Public Member Functions
	CriticalSection ()
	Initializes the critical section.
bool	enter (bool fence=true, bool timed=false, double time=0)
	Enters the critical section.
bool	enter (double time, bool fence=true)
	Enter a critical section for a maximum of a given amount of seconds.
bool	tryEnter ()
	Try to enter a critical section and returns immediately.
void	leave ()
	Leaves the critical sections, allowing other threads to proceed.
void	signIn ()
	Claims the critical section to be unenterable.
void	signOut ()
	Signals that the curren thread is not interested in the critical section anymore.
void	checkPoint ()
	Allows critical section entering if possible.
virtual void	handleCleanup (int code, void *caller=0)
Private Attributes
int	m_signedIn
	Count of signed in threads.
int	m_signRequests
	Count of threads wishing to sign in.
int	m_enterRequests
	Count of threads wishing enter the critical section.
int	m_fenceCount
	Fence count for enter requests.
bool	m_achieved
	True if currently achieved by a thread.
Mutex	m_mutex
	Mutex to protect internal data.
Condition	m_signinCond
	Condition for threads wishing to sign in.
Condition	m_enterCond
	Condition for threads willing to enter the section.

---

Constructor & Destructor Documentation

Wefts::CriticalSection::CriticalSection (   )

Initializes the critical section. This is not an inlined method.

---

Member Function Documentation

void Wefts::CriticalSection::checkPoint (   )

Allows critical section entering if possible. If the current thread does not wants to sign out, but it is doing some interruptable but long work on the data set guarded by the critical section, it may wish to call this method at some point, or periodically. This method will block and allow the thread(s) that asked for critical section entering to proceed, if they rised a fence or if this is the only currently signed in thread. Note: In this case, this becomes a cancelation point. An eventual cancelation during a check point wait will automatically signout this thread form the section, but the thread will have to do it's own cleanup with Thread::pushCleanup() method, or to prevent cancelation with Thread::setCancel().

bool Wefts::CriticalSection::enter (  double  time, bool  fence = true )  [inline]

Enter a critical section for a maximum of a given amount of seconds. Works as enter( bool ), except for the fact that it returns false if the thread is not able to enter the critical section in the given time, or true if the section is achieved. Note: This method is a cancelation point. Be sure to clean the thread or to push a cleanup routine (or to disable cancelation) before calling it. Parameters: time  seconds to wait for the critical section to be enterable. fence  true to rise the sign in fence. Returns: true if the thread entered the section, false otherwise.

bool Wefts::CriticalSection::enter (  bool  fence = true, bool  timed = false, double  time = 0 )

Enters the critical section. The calling thread will be suspended until the count of signed in threads will reach 0, and the critical section is not achieved by other threads. If the fence parameter is ture, a fence is risen; this fence blocks other threads willing to sign in, and blocks also threads entering check points. Anyhow, it won't prevent other threads from entering the critical section. In example, if two threads try to enter a critical section, and one of them rises the fence, the other threads willing to sign in or entering a checkpoint will be stopped, but there is no guarantee that the fencing thread will enter the section before the other. Anyhow, it's guaranteed that the fencing thread will be eventually called before that a new thread has the chance to sucessfully sign in or exit a checkpoint. If the fence parameter is false, then this thread will have to wait for all the threads to be signed out, or to engage at the same time a checkpoint before to proceed. This may happend randomly, or it may happen consistently if the program is designed to have many waits inside the singed in threads. Be the fence parameter true or false, once that the thread has entered the critical section, no thread is allowed to go past a checkpoint or to sign in, up to when the owning thread calls the leave method. If the thread calling this method is also signed in, it MUST sign out before to call enter, or it will hang forever. The timed parameter serves to know if the time parameter must be considered. If timed is true, the function will return true if the function is able to enter the section in the given time interval, or false if it fails. Tipically, you'll want to use candy grammar version enter( double, bool ). Note: This method is a cancelation point. Be sure to clean the thread or to push a cleanup routine (or to disable cancelation) before calling it. See also: leave() Parameters: fence  true to rise a fence and prevents other threads to sign in. False to wait for all the thread to be really signed out. timed  set true if you want to provide a timeout. time  if timed is true, wait for time seconds or abort function Returns: false if timeout was given and it expired without the function being able to enter the section; true otheriwse.

void Wefts::CriticalSection::handleCleanup (  int  code, void *  caller = 0 )  [virtual]

Implements Wefts::CleanupHandler.

void Wefts::CriticalSection::leave (   )

Leaves the critical sections, allowing other threads to proceed. If there are other threads waiting for the critical section to become enterable, and fence is risen they are awaken. Else, threads waiting to sign in are awaken.

void Wefts::CriticalSection::signIn (   )

Claims the critical section to be unenterable. Calling this thread states that it must work on the application data so that the critical section may not be entered safely. Notice that if the data set guarded this way was simple and consistent, a mutex or a read write mutex would be fare enough to handle this situation. But when the data set becomes very complex, or it's not even defined because it may vary from time to time, usage of a critical section semantics becomes important. Any number of threads may sign in for a critical section, but only one is allowed to enter it; and it can enter it only if no other thread has signed in. Also, by entering a critical section, sign in is temporarily forbidden. Timed sign in and sign in tries semantics are not provided because critical section holding is meant to be sporadic and temporary; it has no sense to ask if the current thread may or may not be blocked as a sign in request, because the sign in request significance is exactly to block the thread if the critical section is currently entered. Note: This method is a cancelation point. Be sure to clean the thread or to push a cleanup routine (or to disable cancelation) before calling it.

void Wefts::CriticalSection::signOut (   )

Signals that the curren thread is not interested in the critical section anymore. With this call, the current thread tells eventual other threads wishing to enter the section that they may do it now, as even if the thread continues to work, it will not harm or use the critical section guarded data.

bool Wefts::CriticalSection::tryEnter (   )

Try to enter a critical section and returns immediately. If the critical section is immediately available, the thread enters it and the function returns true; else, it returns false. Its a candy grammar for enter( fence, true, time ); Note: This is not a cancelation point, and can be called also if the thread is in an unclean status. See also: enter(bool) Returns: true if the thread entered the section, false otherwise

---

Member Data Documentation

bool Wefts::CriticalSection::m_achieved [private]

True if currently achieved by a thread. This prevents multiple threas to achieve the section when the signed in count reaches zero.

Condition Wefts::CriticalSection::m_enterCond [private]

Condition for threads willing to enter the section. This condition serves for the predicate ( !m_achieved && m_signedIn == 0 ). Will be signaled only if m_enterRequests != 0.

int Wefts::CriticalSection::m_enterRequests [private]

Count of threads wishing enter the critical section.

int Wefts::CriticalSection::m_fenceCount [private]

Fence count for enter requests.

Mutex Wefts::CriticalSection::m_mutex [private]

Mutex to protect internal data.

int Wefts::CriticalSection::m_signedIn [private]

Count of signed in threads. When it's 0, the critical section may be entered.

Condition Wefts::CriticalSection::m_signinCond [private]

Condition for threads wishing to sign in. This condition serves for the predicate ( !m_achieved && m_fenceCount == 0 ). Will be signaled only if m_signRequests != 0.

int Wefts::CriticalSection::m_signRequests [private]

Count of threads wishing to sign in.

---

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

• wefts_critical.h
• wefts_critical.cpp

---