OpenSwarm  0.16.1.2
An operating system for miniature robots
Files
Event Management

Events are the main information exchange method in OpenSwarm. Events can be emitted, created, and (un)registered. Functions to handle events can also (un)subscribed to certain events. It can be used to synchronise and communicate with processes, to implement asynchronous programming model, and process incoming data/signals. More...

Files

file  events.c
 defines functions to create, (un)subscribe, (un)register, and delete events and related handler.
 
file  events.h
 declares functions to create, (un)subscribe, (un)register, and delete events and related handler.
 

Detailed Description

Events are the main information exchange method in OpenSwarm. Events can be emitted, created, and (un)registered. Functions to handle events can also (un)subscribed to certain events. It can be used to synchronise and communicate with processes, to implement asynchronous programming model, and process incoming data/signals.

Author
Stefan M. Trenkwalder s.tre.nosp@m.nkwa.nosp@m.lder@.nosp@m.open.nosp@m.swarm.nosp@m..org

In general, events are data structures passed from one process/part of OpenSwarm to another.

For example, an event might be triggered by detecting another robot within range. If a function is subscribed to this event, the robot can react on the detection of another robot.

Events can also carry additional information—such as the distance and angle to the detected robot.

Usage

The event system is ready to be used after the start of OpenSwarm. Each event is identified by an integer eventID. To use an event the following steps have to be taken:

  1. An event (eventID ) can be (un)registered by Sys_Register_Event(uint16 eventID) and Sys_Unregister_Event(uint16 eventID). When an event is registered, it means that an event (eventID) can occur and be handled by OpenSwarm.
  2. After the event was registered, processes can be subscribed to it with Sys_Subscribe_to_Event(uint16 eventID, uint16 pid, pEventHandlerFunction handler, pConditionFunction condition) and Sys_Unsubscribe_from_Event(uint16 eventID, uint16 pid). During the subscription, an event handler (i.e. a function to process the event) is subscribed to a specific event (eventID ) and a process. Each event handler of a process for an specific event is unique. As a result, the same handler function can be used by multiple processes.
  3. After an event is registered, events can be sent with Sys_Send_Event(uint16 eventID, void *data, uint16 data_size) and Sys_Send_IntEvent(uint16 eventID, uint16 data).

Example

#include "os/system.h"
#define USER_EVENT_ID 0xCC
bool pConditionFunction(void *data){//only executes the eventHandler every 5th time.
static int counter = 0;
if(++counter >= 4){//if the event occurred the 5th time
counter = 0;
return true;//execute eventHandler
}
return false;//don't execute eventHandler
}
bool eventHandler(uint16 pid, uint16 eventID, sys_event_data *data){
//do something with the data
}
int main(void){
//initialise some global or local variables
int variable;
Sys_Register_Event(USER_EVENT_ID);
Sys_Start_Kernel();//OpenSwarm is running now.
while(true){
if( ... ){//under a certain condition
Sys_Send_Event(USER_EVENT_ID, &variable, sizeof(int));
//alternatively, you could use Sys_Send_IntEvent(USER_EVENT_ID, variable);
}
//do something
}
}

License

LICENSE: adapted FreeBSD License (see http://openswarm.org/license)
Copyright (c) 2015, Stefan M. Trenkwalder
All rights reserved.