CRcEventProcessor Class Reference

Description

Event processor.

This class allows to queue and process events in three different ways:

1. Synchronously by calling PollEvent() or WaitEvent().
2. Asynchronously by overloading the OnEvent() method.
3. Asynchronously by providing a callback function.

Definition at line 1659 of file resources.H.

#include "resources.H"

Inheritance diagram for CRcEventProcessor:

Putting events ...
void	PutEvent (CRcEvent *ev)
	Enqueue/process an event; caller remains owner of 'ev'.

Fetching events synchronously...
bool	PollEvent (CRcEvent *ev)
	Check for an event (non-blocking) and return it at '*ev'. More...
bool	WaitEvent (CRcEvent *ev, TTicks *maxTime=NULL)
	Wait for an event and return it at '*ev'. More...
void	Interrupt ()
	Request a running WaitEvent() to stop now.
void	FlushEvents ()
	Remove all presently queued events; also waits until a concurrently running OnEvent() invocation returns.

Event callbacks (asynchronous) ...
Event callbacks are called asynchronously immediately on each invocation 'PutEvent'. Unlike the PollEvent() / WaitEvent() mechanism, the callback may be called from any thread, and the user is responsible for any necessary synchronisation with other threads. If the callback returns 'false', the event will be enqueued for later 'PollEvent'/'WaitEvent' calls. This way, it is possible to do either all or just part of the work in the callback (e.g. wake up the polling thread). The default implementation just returns 'false', so that all events are queued up. It is not allowed to call any CRcEventProcessor() methods from the callback!
virtual bool	OnEvent (CRcEvent *ev)
	Handle an event asynchronously (may have been called from any thread) More...
void	SetCbOnEvent (FRcEventFunc *_cbEvent, void *_cbEventData=NULL)
void	ClearCbOnEvent ()

Support for global event loops ...
void	SetInSelectSet (bool _inSelectSet)
	Set whether or not the event processor is contained in the set of upcoming Select() operations.
bool	InSelectSet ()
virtual const char *	TypeId ()
	(optional) Hint for the main event loop: object type
virtual const char *	InstId ()
	(optional) Hint for the main event loop: object instance
static CRcEventProcessor *	Select (TTicks maxTime=-1)
	Wait until any of the existing 'CRcEventProcessor' objects has an event available. More...

Stringification ...
const char *	ToStr (CString *ret)

Member Function Documentation

PollEvent()

bool CRcEventProcessor::PollEvent

(

CRcEvent *

ev

)

Check for an event (non-blocking) and return it at '*ev'.

A return value of 'true' indicates that an event was waiting and (if 'ev != NULL') is now removed from the internal queue. If 'ev != NULL', this event is returned. Otherwise, the queue is left unchanged.

Can be called from any thread: the user does not need to take synchronisation measures by calling these from his main thread.

WaitEvent()

bool CRcEventProcessor::WaitEvent	(	CRcEvent *	ev,
		TTicks *	maxTime = NULL
	)

Wait for an event and return it at '*ev'.

A return value of 'true' indicates that an event was waiting and (if 'ev != NULL') is now removed from the internal queue. If 'ev != NULL', this event is returned. Otherwise, the queue is left unchanged.

If 'maxTime != NULL', wait for at most '*maxTime' milliseconds and decrement '*maxTime' by the time actually waited. This way, the method can be called multiple times while approximately limiting the total waiting time (Note: The total time can still be longer due to preemption and additional execution times).

Can be called from any thread: the user does not need to take synchronisation measures by calling these from his main thread.

OnEvent()

virtual bool CRcEventProcessor::OnEvent ( CRcEvent *  ev )

virtual

Handle an event asynchronously (may have been called from any thread)

Parameters

ev	is the event

Returns

true if the event has been processed completely.

Select()

static CRcEventProcessor* CRcEventProcessor::Select ( TTicks  maxTime = -1 )

static

Wait until any of the existing 'CRcEventProcessor' objects has an event available.

Parameters

maxTime

is the maximum time to wait. If set <0, the method waits forever. If set to 0, no waiting happens, this can be used for non-blocking polling.

Returns

an event processor with waiting events, or 'NULL' if 'maxTime' was exceeded while waiting.

Note: It is mandatory that at least one event is actually consumed afterwards, which implies that the caller is able to process/delegate events for all of the existing event processors. If no event is consumed, a busy waiting loop can result. Subscribers with disabled event queues are never returned here. In general, any internal event processors (e.g. drivers) should have working callbacks. For the main program it is then safe, but necessary to run "ASSERT (ep->PollEvent (...))" on unknown event owners.

---

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

• resources/resources.H