Burger::RunQueue Class Reference

Simple manager of a list of function pointers. More...

Collaboration diagram for Burger::RunQueue:

Classes
class	RunQueueEntry
	Function pointer entry. More...

Public Types
enum	eReturnCode { OKAY , ABORT , DISPOSE }
enum	{   PRIORITY_FIRST = 0x7FFFFFF , PRIORITY_JOYPAD = 0x7000040 , PRIORITY_MOUSE = 0x70000030 , PRIORITY_KEYBOARD = 0x70000010 ,   PRIORITY_INPUTPROCESSING = 0x7000000 , PRIORITY_SEQUENCING = 0x68001000 , PRIORITY_SOUNDPROCESSING = 0x6800000 , PRIORITY_FILEPROCESSING = 0x6400000 ,   PRIORITY_HIGH = 0x6000000 , PRIORITY_MEDIUM = 0x4000000 , PRIORITY_LOW = 0x2000000 , PRIORITY_LAST = 0 }
typedef eReturnCode(*)	CallbackProc(void *pContext)
	Function pointer type for callbacks.

Public Member Functions
	RunQueue () noexcept
	RunQueue constructor.
	~RunQueue ()
	RunQueue destructor.
void	Call (void) noexcept
	Invoke every function stored within the list.
RunQueueEntry *	Add (CallbackProc pProc, CallbackProc pShutdown=nullptr, void *pData=nullptr, uint_t uPriority=PRIORITY_MEDIUM) noexcept
	Add a function to the list.
RunQueueEntry *	Find (CallbackProc pProc) const noexcept
	Return TRUE if a function is in the list.
RunQueueEntry *	Find (CallbackProc pProc, void *pData) const noexcept
	Return TRUE if a function is in the list.
uint_t	RemoveAll (CallbackProc pProc) noexcept
	Remove all entries to a function from the list.
uint_t	Remove (CallbackProc pProc, void *pData=nullptr) noexcept
	Remove a function from the list.
void	Clear (void) noexcept
	Release all function entries.

Protected Attributes
DoubleLinkedList	m_Entries
	Head entry of the linked list.
uint_t	m_bRecurse
	TRUE if this class is the process of executing.

Private Member Functions
	RunQueue (const RunQueue &)=delete
RunQueue &	operator= (const RunQueue &)=delete
	RunQueue (RunQueue &&)=delete
RunQueue &	operator= (RunQueue &&)=delete

Detailed Description

Simple manager of a list of function pointers.

---

RunQueue will hold a list of simple function pointers and call them when the Call() member is invoked. It's useful for creating a list of functions to be called in the background on a demand basis, such as polling tasks and game logic objects.

Each function is of a type of RunQueue::CallbackProc

Note

Due to the nature of memory use, the copying of this class is forbidden.

See also

RunQueueEntry

Member Typedef Documentation

CallbackProc

eReturnCode( *) Burger::RunQueue::CallbackProc(void *pContext)

Function pointer type for callbacks.

---

When the Call() function is invoked, all functions will be called using the type of RunQueue::eReturnCode (BURGER_API *)(void *) with a single parameter that will have either a user supplied void * or a nullptr if none was supplied.

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
PRIORITY_FIRST	Highest priority for RunQueue tasks, executed first (Reserved for Burgerlib, do not use or exceed this value)
PRIORITY_JOYPAD	Priority for reading joypad (Can generate keystrokes and mouse events)
PRIORITY_MOUSE	Priority for reading mouse (Can generate keystrokes)
PRIORITY_KEYBOARD	Priority for reading keyboard.
PRIORITY_INPUTPROCESSING	Priority for processing game input.
PRIORITY_SEQUENCING	Priority for music processing.
PRIORITY_SOUNDPROCESSING	Priority for handling sound effects.
PRIORITY_FILEPROCESSING	Priority for asynchronous file I/O processing.
PRIORITY_HIGH	High priority for RunQueue tasks.
PRIORITY_MEDIUM	Average priority for RunQueue tasks.
PRIORITY_LOW	Low priority for RunQueue tasks.
PRIORITY_LAST	Lowest priority for RunQueue tasks, executed last, do not go lower than this value.

eReturnCode

enum Burger::RunQueue::eReturnCode

Enumerator
OKAY	Executed normally.
ABORT	Error occurred that requires an immediate abort.
DISPOSE	Dispose of this callback.

Constructor & Destructor Documentation

RunQueue() [1/3]

Burger::RunQueue::RunQueue ( const RunQueue & )

privatedelete

RunQueue() [2/3]

Burger::RunQueue::RunQueue ( RunQueue && )

privatedelete

RunQueue() [3/3]

Burger::RunQueue::RunQueue ( )

inlinenoexcept

RunQueue constructor.

---

Initialize the class to contain no list. This is inline due to its only zeroing out members.

~RunQueue()

Burger::RunQueue::~RunQueue

(

)

RunQueue destructor.

---

This will call Clear() and dispose of all the memory allocated. No other functions will be called.

See also

Clear().

Member Function Documentation

Add()

Burger::RunQueue::RunQueueEntry *BURGER_API Burger::RunQueue::Add ( CallbackProc pProc, CallbackProc pShutdown = nullptr, void * pData = nullptr, uint_t uPriority = PRIORITY_MEDIUM )

noexcept

Add a function to the list.

---

Given a function pointer and a pointer to data to pass to the function pointer, add this entry to the list of functions that are to be called with each call to Call(). The pointer pData is not used by this class and it's solely used as a parameter when the function pointer is called. Priority values are used to sort the function pointers to call them in a desired order. The default is RunQueue::MEDIUMPRIORITY. There is no sorting with like numbered priorities.

Parameters

pProc	Pointer to a function of type RunQueue::CallbackProc.
pShutdown	Pointer to a function of type RunQueue::CallbackProc that is called when this entry is disposed of
pData	Pointer to be passed to the function when called.
uPriority	Priority value to determine order of calling. Higher values get called first.

Returns

Returns a pointer to the created RunQueueEntry if successful, nullptr if out of memory or if the function pointer was nullptr.

See also

Remove(CallbackProc,void*).

Call()

void BURGER_API Burger::RunQueue::Call ( void )

noexcept

Invoke every function stored within the list.

---

Traverse the array of functions to call and invoke each and every one of them. The functions may add new entries to the list or remove themselves if they need to. If Add() is called, execution of the new entry will be deferred until the next time Call() is invoked.

The function called is of type RunQueue::CallbackProc.

Note

This function can take a significant amount of CPU time if the functions invoked are very slow. This function runs with minimal overhead.

There is a recursion checker, this function will do nothing if it is called by a RunQueue::CallbackProc proc.

See also

Add(CallbackProc,CallbackProc,void*,uint_t), Remove(CallbackProc,void*) or RemoveAll(CallbackProc);

Clear()

void BURGER_API Burger::RunQueue::Clear ( void )

noexcept

Release all function entries.

---

Release all of the allocated memory and discard all function and data pointers.

Note

No functions will be called. Only the list will be destroyed.

See also

Add(CallbackProc,CallbackProc,void*,uint_t) or Remove(CallbackProc,void*).

Find() [1/2]

Burger::RunQueue::RunQueueEntry *BURGER_API Burger::RunQueue::Find ( CallbackProc pProc ) const

noexcept

Return TRUE if a function is in the list.

---

Given a function pointer, search the list to see if there is a match. If a match is found, return TRUE.

Parameters

pProc

Pointer to the function.

Returns

RunQueueEntry pointer if the function pointer was found, nullptr if not.

See also

Add(CallbackProc,CallbackProc,void*,uint_t), Clear() or Call().

Find() [2/2]

Burger::RunQueue::RunQueueEntry *BURGER_API Burger::RunQueue::Find ( CallbackProc pProc, void * pData ) const

noexcept

Return TRUE if a function is in the list.

---

Given a function pointer and a pointer to data to pass to the function pointer, search the list to see if there is a match. If a match is found, return TRUE.

Parameters

pProc	Pointer to the function.
pData	Void pointer to pass to the function if called.

Returns

RunQueueEntry pointer if the Function/Data pair was found, nullptr if not.

See also

Add(CallbackProc,CallbackProc,void*,uint_t), Find(CallbackProc) const or Call().

operator=() [1/2]

RunQueue & Burger::RunQueue::operator= ( const RunQueue & )

privatedelete

operator=() [2/2]

RunQueue & Burger::RunQueue::operator= ( RunQueue && )

privatedelete

Remove()

uint_t BURGER_API Burger::RunQueue::Remove ( CallbackProc pProc, void * pData = nullptr )

noexcept

Remove a function from the list.

---

Given a function pointer and a pointer to data to pass to the function pointer, search the list to see if there is a match. If a match is found, remove the entry and return TRUE, saying it's been found.

Note

Functions can remove themselves from the list at execution time, but you cannot remove a different function during your time quantum since it might break the linked list traversal. If you wish to remove other entries, you must defer this action.

Parameters

pProc	Pointer to the function.
pData	Void pointer to pass to the function if called.

Returns

TRUE if the Function/Data pair was found, FALSE if not.

See also

Add(CallbackProc,CallbackProc,void*,uint_t), Clear() or Call().

RemoveAll()

uint_t BURGER_API Burger::RunQueue::RemoveAll ( CallbackProc pProc )

noexcept

Remove all entries to a function from the list.

---

Given a function pointer and a pointer to data to pass to the function pointer, search the list to see if there is a match. If a match is found, remove the entry and return TRUE, saying I found it.

Note

This function should not be invoked while Call() is executing. It may cause a list traversal error.

Parameters

pProc

Pointer to the function.

Returns

TRUE if the Function/Data pair was found, FALSE if not.

See also

Add(CallbackProc,CallbackProc,void*,uint_t), Clear() or Call().

Member Data Documentation

m_bRecurse

uint_t Burger::RunQueue::m_bRecurse

protected

TRUE if this class is the process of executing.

m_Entries

DoubleLinkedList Burger::RunQueue::m_Entries

protected

Head entry of the linked list.