molib documentation

Languages Available: français español

CLASS

moEvent

NAME

Constructors - initialize an moEvent object
GetClassName - return the name of this event class
Assignment operator - copy an event in another
Duplicate - create a duplicate of an event

VERSION

Version: 1.2.0

SYNOPSIS

moEvent(const moName& name, int order = 0);
moEvent(const moEvent& event);
virtual const char *GetClassName(void) const;
moEvent& operator = (const moEvent& event);
moEventSPtr Duplicate(void) const;

PARAMETERS

name - the name of the new event
order - used to sort events in an event pipe
event - event to copy

DESCRIPTION

The moEvent object will in general be derived to create an event object to be posted in an moEventPipe.

There are two constructors, one of which is a copy constructor. All events must have a name and they can also be given an order. The order is used to sort the events in the moEventPipe in which they are to be posted. Also, events can be given a time (see the SetTime() function). Events are actually sorted by time first, then by order for those events which have the same time.

The assignment operator copies one event in another. The name order and time are copied. An event which has been posted will have been duplicated in the moEventPipe. Thus you are free to modify your event as much as you want.

The Duplicate() function creates an exact duplicate of the event. This is used in the moEventPipe in order to make that the events in pipes are safe (i.e. you won't be able to modify them since you don't have their pointers) until retrieved by the pipe owner.

RETURN VALUE

The GetClassName() function returns a pointer to a constant
static string with the name of the class (molib::moEvent).

The assignment operator returns a reference to this.

The Duplicate() function returns a smart pointer to an event
object.

SEE ALSO

moEvent class

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEvent

NAME

GetName - get the name of the event
SetOrder - change the numeric order
GetOrder - get the current numeric order
Compare - compare two events using their order

VERSION

Version: 1.2.0

SYNOPSIS

mo_name_t GetName(void) const;
void SetOrder(int order);
int GetOrder(void) const;
void SetTime(time_t time);
int GetTime(void) const;
virtual compare_t Compare(const moBase& object) const;

PARAMETERS

order - the numeric order
object - another moEvent object

DESCRIPTION

Each moEvent object can be assigned a name. Usually, the thread which will retrieve the moEvent via an moEventPipe will first check the name of the event to know how to handle it. The name will tell the user what event it is. For instance, when a thread dies, the moThread object sends a DEATH event. This is the name of the event. Once you know the name, you can cast the moEvent to the proper type to access the extraneous data available in the derived event. For instance, if you determine that the event is a DEATH event, you can cast it to moThread::moEventDeath as follow:

moThread::moEventDeath *death;

death = dynamic_cast<moThead::moEventDeath *>(event);

Whenever you post an event, it is added in a list of events defined in an moEventPipe. In that list, the event pipe object sorts the objects using their order. This enables you to have out of bounds events, or very low priority events. For instance, to take a UI like example, you may want to first operate on mouse and keyboard events, then all the other events except events in link with drawing the screen which you want last. In this case, you have three levels:

Mouse, Keyboard order is 1 All other events 0 Except Paint events which are -1

Events can also be given a time. This means events for the future can be posted now and older events can be discarded. The time is specified with the SetTime() function call before the event is posted. Then, the different dispatch functions can take the time in account to know whether the event should be discarded (the event time is more than 1 second old), processed (the event time is between +/-1 second) or held in the queue (the event time is in the future). Since the time needs to be tested first, events are sorted by time before there are sorted by order. By default, events get a time of zero meaning that they are not affected by time. Only events which are posted in the future or those which can be discarded (i.e. these events you do not have to receive) should be given a time. It is very important to understand that a timed event may never arrive and thus you cannot count on it to be dispatched at some point.

The Compare() function is automatically used by the moSortedList of the moEventPipe to order the events using their order number.

NOTES

Timed events may be changed later to allow posts of future events which are ensured to be received even if late when checked out.

RETURN VALUE

The GetName() function returns a name as moNamePool generates

The GetOrder() function returns the order of this event

SEE ALSO

moEventPipe class

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEvent

NAME

SetDispatcher - object to be called when this event is dispatched
Dispatch - dispatch the event

VERSION

Version: 1.2.0

SYNOPSIS

void SetDispatcher(const moEventDispatcher *dispatcher);
void Dispatch(void);

PARAMETERS

dispatcher - an object derived from the moEventDispatcher class

DESCRIPTION

If you want to beneficiate of the automatic dispatching system then you will need to add a dispatcher on every single event you create.

To do so, use the SetDispatcher() function on the event when the dispatcher pointer to call at the time the event is being retrieved from the pipe.

One can call the Dispatch() function to execute the EventDispatch() of the moDispatcher class which is currently attached to this event.

SEE ALSO

moEventPipe class

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEventPipe

NAME

GetClassName - get the name of this class

VERSION

Version: 1.2.0

SYNOPSIS

virtual const char *GetClassName(void) const;

DESCRIPTION

Please, see moBase::GetClassName() for more information.

RETURN VALUE

The pointer to the name of this class in a static string.

SEE ALSO

moBase::GetClassName() function

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEventPipe

NAME

Post - post an event in this event pipe
Next - wait until an event is available and return it
Peek - get the next event if any, or return false
Wait - wait until an event is available

VERSION

Version: 1.2.0

SYNOPSIS

void Post(moEvent& event);
void Flush(void);
bool Next(moEventSPtr& event_ptr);
bool Peek(moEventSPtr& event_ptr, bool remove = false);
void Wait(void) const;

PARAMETERS

event - the event to post
event_ptr - a pointer where the event being read is returned
remove - whether to remove the event from the pipe

DESCRIPTION

The moEventPipe object will be used by one thread to receive events from other threads. Any thread, including the owner of the event pipe can send an event in the pipe using the Post() function.

Note that timed events which have a date in the past can be posted. However, nothing will be put in the pipe in this case since the event will already be considered too old. This means you should date your event right before to post it rather than when you create the event (it depends how long it takes your code to create the event, that is).

The owner of the pipe (and none other in most cases) can either use the Next() or the Peek() functions to retrieve the next event. The Next() will block until an event is posted in the moEventPipe. The Peek() won't block if there isn't any message and also it will leave the message in the pipe unless the remove flag is set to true (note that the default is false).

The Next() and Peek() with the remove flag set to true will dispatch the event if the SetAutoDispatch() function was called with true as a parameter. The two functions still return the event which could have been modified by the dispatch function. See also the moEvent::SetDispatcher() function for more information.

If your thread wants to wait until an event is available, then use the Wait() function. That function will block until there is at least one event in the event pipe. This is the sole purpose of that function. It can be useful in case you don't need to know what the event is until later in your function.

In all cases, the functions will check timed events as expected. This means events of the past are automatically discarded and events for the future are ignored. In other words, the Peek() function will return no event if the pipe isn't empty but only includes events which are to be dispatched in the future.

The Next() and Wait() functions are optimized to wait until the date of the next event in the future is reached or a new message arrives.

The Flush() can be used to empty the pipe entirely. Be careful as some events may need to be received otherwise the behavior of your software may be compromised.

NOTES

It is unlikely useful, but an moEventPipe can also be owned by multiple threads. If these are worker threads, then an event can be sent to any one of them for execution of some task. The main problem here is that you can't be sure which thread will receive which event.

The multi-threading synchronization are archived using the moMutex object.

RETURN VALUE

The Peek() function returns true if an event was available

SEE ALSO

moEvent class

BUGS

The Peek() function will also return false if it can't get a lock to look at the pipe data. Yet, the pipe may not be empty.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEventPipe

NAME

GetAutoDispatch - check the current auto-dispatch flag setup
SetAutoDispatch - set the auto-dispatch flag as required

VERSION

Version: 1.2.0

SYNOPSIS

bool GetAutoDispatch(void) const;
void SetAutoDispatch(bool auto_dispatch = true);

PARAMETERS

auto_dispatch - whether to auto-dispatch or not

DESCRIPTION

Whenever a message is taken out of an moEventPipe, you can request that pipe to automatically call the dispatch function defined on the moEvent.

The Next() function will always call the dispatch function.

The Peek() function calls the dispatch function only if the remove flag is set to true.

By default, the events are not automatically dispatched.

RETURN VALUE

The GetAutoDispatch() function returns true if events are
to be dispatched

SEE ALSO

moEvent class

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEventPipeBroadcast

NAME

Next - wait and get the next event out of the pipe
Peek - get an next event out of the pipe

VERSION

Version: 1.2.0

SYNOPSIS

virtual void Next(moEventSPtr& event);
virtual bool Peek(moEventSPtr& event, bool remove = false);

PARAMETERS

event - a copy of the event will be returned to you here
remove - whether the event is removed from the pipe

DESCRIPTION

These functions are similar to the functions of the same name of the moEventPipe class.

In addition, each time an event is removed from the pipe, it is executed. This means all the receivers registered with your instance of moEventPipeBroadcast will have their function(s) called.

IMPORTANT: if the remove flag is set to false (the default) in the Peek() function, then the event isn't removed from the pipe and thus none of the receivers' functions will be called.

RETURN VALUE

The Peek() function returns true whenever an event was
available, false otherwise.

SEE ALSO

moEvent::Next, moEvent::Peek

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEventPipeBroadcast

NAME

AddReceiver - add a receiver for any event posted on this pipe
RemoveReceiver - remove a receiver previously added to this pipe
Execute - process the event with the different receivers

VERSION

Version: 1.2.0

SYNOPSIS

void AddReceiver(const moEventReceiver *receiver);
void RemoveReceiver(const moEventReceiver *receiver);
void Dispatch(moEvent *event);

PARAMETERS

receive - a pointer to a valid receiver
event - the event to process using the receivers

DESCRIPTION

The AddReceiver() function will add the given receiver pointer to the list of objects to receive events. Note that a receiver will receive all the events, though most will usually be ignored. You can insert the same receiver multiple times, but watch out, if you do so, your functions will be executed multiple times too.

The RemoveReceiver() function searches for a previously added receiver and remove the first instance it finds. If the same receiver had been added multiple times, then it has to be removed multiple times to be removed completely.

The Dispatch() function takes an event as a parameter and sends that event to each of the receivers currently attached to the moEventPipeBroadcast object. This is usually called internally by the Next() and Peek() functions whenever they retrieve an event, but one may want to trigger an event right away. (warning: this takes precedence over all the events currently in the pipe and it is not validated in any strong way like the other events).

RETURN VALUE

The Peek() function returns true whenever an event was
available, false otherwise.

SEE ALSO

moEvent::Next, moEvent::Peek

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEventReceiver

NAME

GetPriority - returns the current priority of a receiver
SetPriority - sets the priority of a receiver

VERSION

Version: 1.2.0

SYNOPSIS

void SetPriority(int priority);
int GetPriority(void) const;

PARAMETERS

priority - the new priority for a receiver

DESCRIPTION

The receivers will be sorted using their priority. In most cases, receivers will not change their priority and they will be executed in an unspecified order.

The receiver with the largest priority will always be called first. Receivers with equal priority are called in any order.

RETURN VALUE

The GetPriority() function returns the current priority of
a receiver.

SEE ALSO

moEventPipeBroadcast class

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moEventReceiver

NAME

Compare - compares the priority of two receivers

VERSION

Version: 1.2.0

SYNOPSIS

compare_t Compare(const moBase& object) const;

PARAMETERS

object - the other receiver to compare priority with

DESCRIPTION

When receivers are ready to have some of their functions called, they are copied in a sorted list. This list is sorted according to their current priority.

RETURN VALUE

One of the MO_BASE_COMPARE_... values

SEE ALSO

SetPriority(), GetPriority()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moReceiversEvent

NAME

Constructors - to initialize a receivers event

VERSION

Version: 1.2.0

SYNOPSIS

moReceiversEvent(const moName& name, int order = 0);
moReceiversEvent(const moEvent& event);

PARAMETERS

name - the name of the event
order - the order to sort events among each others
event - an event to copy

DESCRIPTION

The receivers events are special events which can be used with the moEventPipeBroadcast object.

Whenever such an event is used with such a pipe, its SendToReceivers() function is automatically called whenever an event is retrieved from the pipe (see the Next and Peek functions of the moEventPipeBroadcast).

SEE ALSO

moEventPipeBoardcast::Next moEventPipeBoardcast::Peek

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moReceiversEvent

NAME

Duplicate - allocate a copy of this event

VERSION

Version: 1.2.0

SYNOPSIS

virtual moEventSPtr Duplicate(void) const = 0;

DESCRIPTION

You need to have your own Duplicate() function because you need to have your SendToReceivers() function called whenever an event is received.

Whenever an event is being posted, it needs to be duplicated. This function is called automatically by the moEventPipe whenever Post() is called. This is important because several threads are using the different objects and often the user will create his events on the stack and that event needs to still be present in the pipe whenever the other thread receives it.

SEE ALSO

SendToReceivers

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moReceiversEvent

NAME

SendToReceivers - to send an event whenever the pipe gets one

VERSION

Version: 1.2.0

SYNOPSIS

virutal void SendToReceivers(const moSortedList& receivers) = 0;

DESCRIPTION

This function will send the event to all the receivers mentioned in the list of receivers. It is a pure virtual here since we can't know of the functions to be called in the lower level implementation (these are not declared here yet!).

SEE ALSO

Duplicate, moEventPipeBroadcast::Dispatch

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox