Defines a queue with synchronized access. This is a standard data structure that may be used with First-In-First-Out or Last-In-First-Out policies. This is intended for multi-task applications. Use gcgLINKEDLIST if you do not need exclusive accesses in enqueue and dequeue operations. More...

#include <gcg.h>

Inheritance diagram for gcgQUEUE:

Public Member Functions
	gcgQUEUE ()
	Constructs a valid and empty queue. More...

virtual	~gcgQUEUE ()
	Destroys the queue, releasing the linked list of nodes. After that, it wakes up all threads blocked in waitDequeue(). All entries are deleted. More...

bool	enqueueTail (gcgLINK *node)
	Inserts a new entry node at the TAIL of the queue. This entry will be the last to be dequeued. More...

bool	enqueueHead (gcgLINK *node)
	Inserts a new entry node at the HEAD of the queue. This entry will be the first to be dequeued. More...

gcgLINK *	dequeue ()
	Returns the next entry stored in the HEAD of the queue. The entry is removed from the top of the queue. More...

gcgLINK *	waitDequeue (long timeoutUsec=-1)
	Returns the HEAD entry of the queue. It is removed from the top of the queue. If the queue is empty, waits for timeoutUsec microseconds. If an entry becomes available during this time, it is returned immediately. If time is out, returns NULL with a GCG_TIMEOUT warning (check GCG_REPORT_MESSAGE(gcgGetReport())). If timeoutUsec is negative, the calling thread is blocked and only returns when an entry is available or an error occurs. More...

bool	isEmpty ()
	Checks if the queue is empty. More...

uintptr_t	getCounter ()
	Gets the current number of elements stored in the queue. More...

bool	deleteAll ()
	Removes all entries from the queue. All objects are deleted. If notification is enabled, calls gcgLOCK::wakeUp(-1) to wake all waiting threads once and after all entries were removed. More...

gcgLOCK *	wakeUpWhenEnqueued (gcgLOCK *notifyme, int wakeupNumThreads)
	Sets the gcgLOCK to be used to wake up threads waiting for insertions on this queue. When a entry is added to the queue, gcgQUEUE executes the gcgLOCK::wakeUp() of notifyme, passing wakeupNumThreads as the number of threads to be awaken. This allows asynchronous accesses to the queue. This notification is made by enqueueTail() and enqueueHead(). Only one gcgLOCK instance for enqueuing events is allowed by gcgQUEUE, but the same gcgLOCK instance can be used by several notifying objects. More...

gcgLOCK *	wakeUpWhenDequeued (gcgLOCK *notifyme, int wakeupNumThreads)
	Sets the gcgLOCK to be used to wake up threads waiting for removals on this queue. When a entry is removed from the queue, gcgQUEUE executes the gcgLOCK::wakeUp() of notifyme, passing wakeupNumThreads as the number of threads to be awaken. This allows asynchronous accesses to the queue. This notification is made by dequeue(), waitDequeue(), deleteAll() and upon object destruction. The destructor and deleteAll() call notifyme's gcgLOCK::wakeUp(-1) (wakes up all waiting threads) once and after all entries are deleted. Only one dequeuing gcgLOCK instance is allowed by gcgQUEUE, but the same gcgLOCK instance can be used by several notifying objects. 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...

Private Attributes
void *	handle
	Internal handle of this object.

Detailed Description

Defines a queue with synchronized access. This is a standard data structure that may be used with First-In-First-Out or Last-In-First-Out policies. This is intended for multi-task applications. Use gcgLINKEDLIST if you do not need exclusive accesses in enqueue and dequeue operations.

Since: 0.02.0

Constructor & Destructor Documentation

◆ gcgQUEUE()

gcgQUEUE::gcgQUEUE ( )

Constructs a valid and empty queue.

See also: enqueueHead(); enqueueTail(); dequeue(); waitDequeue(); gcgLINK

◆ ~gcgQUEUE()

virtual gcgQUEUE::~gcgQUEUE ( )

virtual

Destroys the queue, releasing the linked list of nodes. After that, it wakes up all threads blocked in waitDequeue(). All entries are deleted.

See also: enqueueHead(); enqueueTail(); dequeue(); waitDequeue(); isEmpty(); gcgLINK

Member Function Documentation

◆ deleteAll()

bool gcgQUEUE::deleteAll ( )

Removes all entries from the queue. All objects are deleted. If notification is enabled, calls gcgLOCK::wakeUp(-1) to wake all waiting threads once and after all entries were removed.

Returns: Returns true if all entries were removed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: enqueueHead(); enqueueTail(); dequeue(); waitDequeue(); wakeUpWhenChanged()

◆ dequeue()

gcgLINK* gcgQUEUE::dequeue ( )

Returns the next entry stored in the HEAD of the queue. The entry is removed from the top of the queue.

Returns: returns the pointer of the head entry. If it returns NULL, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: enqueueHead(); enqueueTail(); waitDequeue(); isEmpty(); wakeUpWhenChanged(); gcgLINK

◆ enqueueHead()

bool gcgQUEUE::enqueueHead ( gcgLINK * node )

Inserts a new entry node at the HEAD of the queue. This entry will be the first to be dequeued.

Parameters

[in] node a pointer to a linkable instance (gcgLINK) to be inserted at the queue's head. This pointer is deleted by the destructor or a deleteAll() call if not dequeued. A NULL value generates an error.

Returns: returns true if the data is successfully inserted at the top of the queue. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: enqueueTail(); dequeue(); deleteAll(); waitDequeue(); isEmpty(); wakeUpWhenChanged(); gcgLINK

◆ enqueueTail()

bool gcgQUEUE::enqueueTail ( gcgLINK * node )

Inserts a new entry node at the TAIL of the queue. This entry will be the last to be dequeued.

Parameters

[in] node a pointer to a linkable instance (gcgLINK) to be inserted at queue's tail. This pointer is deleted by the destructor or a deleteAll() call if not dequeued. A NULL value generates an error.

Returns: returns true if the data is successfully inserted at the end of the queue. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: enqueueHead(); dequeue(); deleteAll(); waitDequeue(); isEmpty(); wakeUpWhenChanged(); gcgLINK

◆ getCounter()

uintptr_t gcgQUEUE::getCounter ( )

Gets the current number of elements stored in the queue.

Returns: the number of entries stored in the queue.

See also: enqueueHead(); enqueueTail(); dequeue(); waitDequeue(); isEmpty()

◆ isEmpty()

bool gcgQUEUE::isEmpty ( )

Checks if the queue is empty.

Returns: Returns true if the queue has no entries.

See also: enqueueHead(); enqueueTail(); dequeue(); waitDequeue(); getCounter()

◆ waitDequeue()

gcgLINK* gcgQUEUE::waitDequeue ( long timeoutUsec = -1 )

Returns the HEAD entry of the queue. It is removed from the top of the queue. If the queue is empty, waits for timeoutUsec microseconds. If an entry becomes available during this time, it is returned immediately. If time is out, returns NULL with a GCG_TIMEOUT warning (check GCG_REPORT_MESSAGE(gcgGetReport())). If timeoutUsec is negative, the calling thread is blocked and only returns when an entry is available or an error occurs.

Parameters

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

Returns: returns the entry pointer. If it returns NULL, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem. If timeoutUsec is elapsed without successful dequeue, it returns NULL and the warning GCG_TIMEOUT is triggered.

See also: enqueueHead(); enqueueTail(); dequeue(); waitDequeue(); isEmpty(); wakeUpWhenChanged(); gcgLINK

◆ wakeUpWhenDequeued()

gcgLOCK* gcgQUEUE::wakeUpWhenDequeued	(	gcgLOCK *	notifyme,
		int	wakeupNumThreads
	)

Sets the gcgLOCK to be used to wake up threads waiting for removals on this queue. When a entry is removed from the queue, gcgQUEUE executes the gcgLOCK::wakeUp() of notifyme, passing wakeupNumThreads as the number of threads to be awaken. This allows asynchronous accesses to the queue. This notification is made by dequeue(), waitDequeue(), deleteAll() and upon object destruction. The destructor and deleteAll() call notifyme's gcgLOCK::wakeUp(-1) (wakes up all waiting threads) once and after all entries are deleted. Only one dequeuing gcgLOCK instance is allowed by gcgQUEUE, but the same gcgLOCK instance can be used by several notifying objects.

Parameters

[in]	notifyme	pointer to a gcgLOCK used for concurrent access to the queue. A thread that is waiting for an entry removal should call gcgLOCK::wait() to block. When gcgQUEUE calls notifyme->wakeUp(wakeupNumThreads) indicating an removal from the queue, at least wakeupNumThreads are woken up and will have the chance to access the queue. Only one dequeuing notifier is allowed by gcgQUEUE. It may be NULL, disabling change dequeuing notifications (default).
[in]	wakeupNumThreads	number of threads to be awaken when an removal occurs. This is directly passed to notifyme's gcgLOCK::wakeUp() invocation. The destructor wakes up all threads.

Returns: returns the previous gcgLOCK pointer.

See also: dequeue(); waitDequeue(); ~gcgQUEUE(); gcgLOCK; gcgLOCK::wakeUp(); gcgLOCK::wait()

◆ wakeUpWhenEnqueued()

gcgLOCK* gcgQUEUE::wakeUpWhenEnqueued	(	gcgLOCK *	notifyme,
		int	wakeupNumThreads
	)

Sets the gcgLOCK to be used to wake up threads waiting for insertions on this queue. When a entry is added to the queue, gcgQUEUE executes the gcgLOCK::wakeUp() of notifyme, passing wakeupNumThreads as the number of threads to be awaken. This allows asynchronous accesses to the queue. This notification is made by enqueueTail() and enqueueHead(). Only one gcgLOCK instance for enqueuing events is allowed by gcgQUEUE, but the same gcgLOCK instance can be used by several notifying objects.

Parameters

[in]	notifyme	pointer to a gcgLOCK used for concurrent access to the queue. A thread that is waiting for an entry insertion should call gcgLOCK::wait() to block. When gcgQUEUE calls notifyme->wakeUp(wakeupNumThreads) indicating an entry addition, at least wakeupNumThreads are woken up and will have the chance to access the queue. Only one enqueuing notifier is allowed by gcgQUEUE. It may be NULL, disabling change enqueuing notifications (default).
[in]	wakeupNumThreads	number of threads to be awaken when an insertion occurs. This is directly passed to notifyme's gcgLOCK::wakeUp() invocation.

Returns: returns the previous gcgLOCK pointer for enqueuing notifications.

See also: enqueueHead(); enqueueTail(); waitDequeue(); gcgLOCK::wakeUp(); gcgLOCK::wait()

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

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

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ gcgQUEUE()

◆ ~gcgQUEUE()

Member Function Documentation

◆ deleteAll()

◆ dequeue()

◆ enqueueHead()

◆ enqueueTail()

◆ getCounter()

◆ isEmpty()

◆ waitDequeue()

◆ wakeUpWhenDequeued()

◆ wakeUpWhenEnqueued()