Defines a lock for easy critical section control. Provides timed lock, which tries to lock an internal mutex before a given timeout has elapsed. More...

#include <gcg.h>

Inheritance diagram for gcgLOCK:

Public Member Functions
	gcgLOCK ()
	Constructs a valid and unlocked object. More...

virtual	~gcgLOCK ()
	Destroys the object. Be sure that the object is unlocked before destruction. Trying to destroy a locked object will result in an undefined behavior, as defined by pthread library. More...

bool	lock (long timeoutUsec=-1)

bool	unlock ()

bool	wait (long timeoutUsec=-1)
	Blocks the calling thread, waiting to be woken up. It must be called after having the control by calling gcgLOCK::lock(). If another thread calls wakeUp() for a sufficient number of threads, this method returns true eventually. If timeoutUsec (positive) has elapsed after the blocking, wait() returns false and a warning with GCG_TIMEOUT is issued. If during this time wakeUp() is called for a sufficient number of threads, wait() eventually returns true. If timeoutUsec is negative, the method blocks until wakeUp() is called or an error occurs. For each call to wait() there MUST be a subsequent call to unlock(), even if it returns false. More...

bool	wakeUp (int numberOfThreads=-1)
	Wakes up at least one blocked thread. The number of threads to be woken up is application dependent. If n objects were produced, for example, at least numberOfThreads = n should be woken up to consume them without wasting system resources. If numberOfThreads is negative, all waiting threads are woken up. More...

Public Member Functions inherited from gcgCLASS
void *	operator new (size_t size)
	Defines a new operator to be used by instatiations of GCGlib classes instead the global one. More...

void *	operator new (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by instantiations of GCGlib classes instead the global one. Returns a NULL pointer instead of throwing an exception if an error occurs. More...

void *	operator new[] (size_t size)
	Defines a new operator to be used by GCGlib array allocations instead the global one. More...

void *	operator new[] (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by vector allocations instead the global one. More...

void	operator delete (void *p)
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...

void	operator delete (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...

void	operator delete[] (void *p)
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...

void	operator delete[] (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...

Public Attributes
void *	handle
	Internal handle of this object.

Detailed Description

Defines a lock for easy critical section control. Provides timed lock, which tries to lock an internal mutex before a given timeout has elapsed.

Threads sometimes need to access a data resource or event. Firstly, the thread enters a critical section into which it can have exclusive access to the data. After checking the data for resource or event, the thread can pick the information it needs and then unlock the access. Using gcgLOCK class, these operations are respectively gcgLOCK::lock() and gcgLOCK::unlock().

Generic methods to make threads to wait for some notification: gcgLOCK::wait() and gcgLOCK::wakeUp()

If the thread sees that the data is not ready or available, or an expected event did not occur, it can go to sleep waiting for them. Method gcgLOCK::wait() has this function and must be called after gcgLOCK::lock() has gained control of the critical section. A waiting thread does not hog the processor. When the resource becomes available or an event occurs, the other thread responsible for them notifies it waking up one or more threads that are in wait state. The other thread calls gcgLOCK::wakeUp() for this, telling how many threads should be woken up (or all). If multiple threads are blocked each one by a gcgLOCK::wait() call, the system scheduler will choose which of them will wake up. The awaken threads has to get the lock again in order to continue execution (keeping exclusive control of the resources or data). At that point, exclusively one thread is allowed to run. This is desired because the resource or event is accessible only by one thread at a time. The thread can operate on the resource or event and, when finished, release the control to allow another thread to exclusively access the resource/event. The current thread does this is by normally calling gcgLOCK::unlock(). Then, another awaken thread get the lock and the exclusive access to the resource, works on it, and, on its turn, release it for another thread. In this process, the awaken (notified) threads by gcgLOCK::wakeUp() return from gcgLOCK::wait() sequentially, and synchronously have access to the resource or event. Along the lock() - unlock() code block, the thread can check anytime if the resource/event is available and call gcgLOCK::wait() as long as needed, while data is not available or event signaled.

Since: 0.01.6

Constructor & Destructor Documentation

◆ gcgLOCK()

gcgLOCK::gcgLOCK ( )

Constructs a valid and unlocked object.

See also: lock(); unlock()

◆ ~gcgLOCK()

virtual gcgLOCK::~gcgLOCK ( )

virtual

Destroys the object. Be sure that the object is unlocked before destruction. Trying to destroy a locked object will result in an undefined behavior, as defined by pthread library.

See also: lock(); unlock()

Member Function Documentation

◆ lock()

bool gcgLOCK::lock ( long timeoutUsec = -1 )

Locks the object. If it is unavalaible, waits the lock for timeoutUsec microseconds. If the locked is obtained during this time, the function returns immediately. If time is out, returns false with a GCG_TIMEOUT warning (check GCG_REPORT_MESSAGE(gcgGetReport())). If timeoutUsec is negative, the calling thread will be blocked until it acquire the lock or un error occurs. If the lock is seized, returns true.

Parameters

[in] timeoutUsec the time in microseconds that the function must wait to get the lock. The function returns immediately after the lock is seized. If negative, the function blocks the calling thread until the lock is obtained or an error occurs.

Returns: true if the object was locked. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem. If timeoutUsec is elapsed without successful locking, the warning GCG_TIMEOUT is triggered.

See also: unlock(); wait(); wakeUp()

◆ unlock()

bool gcgLOCK::unlock ( )

Unlocks the object. The calling thread must own the object otherwise an error is generated.

Returns: true if the object was unlocked. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: lock(); wait(); wakeUp()

◆ wait()

bool gcgLOCK::wait ( long timeoutUsec = -1 )

Blocks the calling thread, waiting to be woken up. It must be called after having the control by calling gcgLOCK::lock(). If another thread calls wakeUp() for a sufficient number of threads, this method returns true eventually. If timeoutUsec (positive) has elapsed after the blocking, wait() returns false and a warning with GCG_TIMEOUT is issued. If during this time wakeUp() is called for a sufficient number of threads, wait() eventually returns true. If timeoutUsec is negative, the method blocks until wakeUp() is called or an error occurs. For each call to wait() there MUST be a subsequent call to unlock(), even if it returns false.

Parameters

[in] timeoutUsec the time in microseconds that the function must wait. If during this time wakeUp() is invoked for a sufficient number of threads, the method returns true. If negative, the function blocks the calling thread until a wakeUp() method is invoked or an error occurs. If timeoutUsec (positive) has elapsed after the blocking, wait() returns false and a warning with GCG_TIMEOUT is issued.

Returns: true if the thread was woken up, regained the lock, and has exclusive access to the critical section. gcgWAIT:unlock() MUST be called eventually after a call to gcgWAIT:wait(). Otherwise, all other threads get stucked in a deadlock. If it returns false, the thread can access the objects of the associated critical section, but the event or resource might be unavailable. Check always the conditions before using resources. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: lock(); unlock(); wakeUp()

◆ wakeUp()

bool gcgLOCK::wakeUp ( int numberOfThreads = -1 )

Wakes up at least one blocked thread. The number of threads to be woken up is application dependent. If n objects were produced, for example, at least numberOfThreads = n should be woken up to consume them without wasting system resources. If numberOfThreads is negative, all waiting threads are woken up.

Parameters

[in] numberOfThreads number of threads to be woken up. If zero, nothing occurs. If negative, all threads are awaken.

Returns: true if the broadcast signal to wake threads were sent. If returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: lock(); unlock(); wait()

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

M:/Documentos/Projetos/Projetos/GCGlib/src/gcg.h

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ gcgLOCK()

◆ ~gcgLOCK()

Member Function Documentation

◆ lock()

◆ unlock()

◆ wait()

◆ wakeUp()