Information

Documentation

Get OpenRDK at SourceForge.net. Fast, secure and Free Open Source software downloads

edit SideBar

Events

In your init() function, you can listen to multiple events. This means that, in your exec() function, you do not know which event woke up you. If you need to know what kind of event woke you up from your session->wait(), you can use one of the following methods.

Register event handlers

The easiest method is to declare some event handlers (functions in your module) that will be called if some kind of event occurs. First of all, suppose that we have the following properties in the repository:

  property1
  property2
  property3
  bigProperty4

and that your init() function is something like this:

bool MyModule::init()
{
   // ...
   session->listen("property1");
   session->listen("property2");
   session->listen("bigProperty4");
   session->listenToTimer(/* some amount here */);
   // ...
}

First of all, notice that the property3 is not listened: this means that its updates will not wake up the module. Now, if you are in your exec() function, how can you know if you have been awaken by a timer event or a property update event (and which property caused the event)?

In order to declare event handlers, you have to declare them in the header file of your module:

// ...
#define EVENT_HANDLER_CLASS MyModule

class MyModule : public Module {
// ...
private:
   bool timerEvent(const Event* e);
   bool propertyEventA(const Event* e);
   bool propertyEventB(const Event* e);

   DECLARE_EVENT_HANDLER(timerEvent);
   DECLARE_EVENT_HANDLER(propertyEventA);
   DECLARE_EVENT_HANDLER(propertyEventB);
};

Check if your template contains the EVENT_HANDLER_CLASS declaration. Notice the macros used to declare the handlers. Now we will make the session aware of the event handlers:

bool MyModule::init()
{
   // ...
   session->listen("property1");
   session->listen("property2");
   session->listen("bigProperty4");
   session->listenToTimer(/* some amount here */);
   session->registerTimerEventHandler(SESSION_EVENT(timerEvent));
   session->registerPropertyUpdateEventHandler(SESSION_EVENT(propertyEventA));
   session->registerPropertyUpdateEventHandler(SESSION_EVENT(propertyEventB), "property");
   // ...
}

So far, you can register event handlers for timer events (registerTimerEventHandler), for property updates (registerPropertyUpdateEventHandler) and for updates on the property tree (registerPropertyTreeEventHandler). The property update event handler registration has a second parameter, to optionally provide a prefix of the properties you are interested to: in this example, the property2EventHandler event handler will be called for (listened) properties that begin with "property" (this means property1 and property2, but not bigProperty4).

The handlers appears like this:

bool MyModule::timerEvent(const Event* e)
{
   // ... some code here ...
}

Finally, you have to process the events, using these handlers, in the exec() function:

void exec()
{
   // ...
   while (session->wait(), !exiting) {
      session->processEvents();
      // .. some optional code here, not related to events
   }
}

If you start an agent with this module, you will see that:

  • the timerEvent() is called for timer events;
  • the propertyEventA() is called for updates on property1, property2 and bigProperty4;
  • the propertyEventB() is called for updates on property1 and property2.

The updates on property3 will not cause any wake up from the session->wait(), because this property is not listen()ed.

You can look at another example of the use of event handlers in ${OpenRDK}/src/apps/ragent2/modules/examples/eventhandlerexamplemodule; you can run this example module using the configuration file at ${OpenRDK}/data/config/examples/rq-eventhandlerexample.config.

© 2004-2009 RoCoCo Laboratory Powered by PmWiki
Edit - History - Printable View - Recent Changes - Search
Page last modified on May 27, 2009, at 12:08 PM