Kicking it Olde Sküül! Burgerlib on Github Follow Olde Sküül on Twitter Burgerbecky on LinkedIn Burgerbecky on LinkedIn
Loading...
Searching...
No Matches
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.
 
RunQueueEntryAdd (CallbackProc pProc, CallbackProc pShutdown=nullptr, void *pData=nullptr, uint_t uPriority=PRIORITY_MEDIUM) noexcept
 Add a function to the list.
 
RunQueueEntryFind (CallbackProc pProc) const noexcept
 Return TRUE if a function is in the list.
 
RunQueueEntryFind (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
 
RunQueueoperator= (const RunQueue &)=delete
 
 RunQueue (RunQueue &&)=delete
 
RunQueueoperator= (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

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
pProcPointer to a function of type RunQueue::CallbackProc.
pShutdownPointer to a function of type RunQueue::CallbackProc that is called when this entry is disposed of
pDataPointer to be passed to the function when called.
uPriorityPriority 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
pProcPointer 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
pProcPointer to the function.
pDataVoid 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
pProcPointer to the function.
pDataVoid 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
pProcPointer 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.