Robotics Service Bus

h1. Events

{{>toc}}

Conceptually and when represented in programs, RSB Events consist of the following components:

|_.Name                  |_.Type                                                             |_.Comment                      |_.Required      |

| sequence number        | 32-bit unsigned integer                                           | Assigned by informer          | yes            |

| id                     | "UUID":http://en.wikipedia.org/wiki/Universally_unique_identifier | Unique Id of the event        | lazily derived |

| [[Glossary|scope]]     | Scope object                                                      | Destination scope             | yes            |

| [[Methods|method]]     | ASCII string                                                      | (see [[Methods]])             | no             |

| [[Glossary|data-type]] |                                                                   | (see [[Glossary]], [[Types]]) | no?            |

| [[Glossary|payload]]   | Domain-specific object                                            |                               | no             |

| meta-data              | (see below)                                                       | (see below)                   | no             |

The id component of an event is derived from the sequence number of the event and the id of the participant that sent the event as follows:

# Construct a string representation of the sequence number

** Radix 16

** Lower-case letters

** Zero-padding to width 8

# Use the UUID v.5 algorithm to construct the event id

** namespace: id of the sending participant

** name: the string constructed above

_Example/Test Cases:_

<pre>

sequence number        0

sender id              D8FBFEF4-4EB0-4C89-9716-C425DED3C527

sequence number string "00000000"

event id               v5-uuid(D8FBFEF4-4EB0-4C89-9716-C425DED3C527, "00000000")

                       => 84F43861-433F-5253-AFBB-A613A5E04D71

</pre>

<pre>

sequence number        378

sender id              BF948D47-618F-4B04-AAC5-0AB5A1A79267

sequence number string "0000017a"

event id               v5-uuid(BF948D47-618F-4B04-AAC5-0AB5A1A79267, "0000017a")

                       => BD27BE7D-87DE-5336-BECA-44FC60DE46A0

</pre>

h2. Meta Data

Events carry a set of meta data with themselves. Some meta data items are specified and processed by RSB while others are user-defined and not interpreted by RSB.

All timestamps are expressed in "Coordinated Universal Time (UTC)":http://en.wikipedia.org/wiki/Coordinated_Universal_Time and stored with microsecond precision (even if the clock source used by RSB cannot actually provide microsecond precision).

h3. RSB Meta Data Items

The current set of specified, required meta data items is given below:

* *senderId*: ID (a UUID) of the sending participant.

* *createTime*: a time stamp that is automatically filled with the time the event instance was created by the language binding. This should usually reflect the time at which the notified condition most likely occurred in the sender. If event instances are reused, it has to be reset manually by the client.

* *sendTime*: the time at which the generated notification for an event was sent on the bus (after serialization)

* *receiveTime*: the time at which an event is received by listener in its encoded form

* *deliverTime*: the time at which an event was decoded and will be dispatched to the client as soon as possible (set directly before passing it to the client handler)

h3. User-defined Meta Data Items

* *userTimes*: a set of key-value user-defined time-stamps

* *userInfos*: a set of key-value user-defined options with string keys and values

*createTime* and *sendTime* and *userTimes* are computed using the clock source of the sending process, whereas  *receiveTime* and *deliverTime* are filled using the clock source of receiving participant's process.

h2. Cause Vector

Each event hast a set of causing EventIds (idea from Luckham, The Power of Events: An Introduction to Complex Event Processing in Distributed Enterprise Systems).

The user who sends an Event needs to insert the respective EventIds manually if required.

Currently, no specification how these IDs shall be used exists, especially with respect to transitivity.

h2. Implementations

|_.Language   |_.File(s)                                                                      |

| C++         | source:trunk/cpp/core/src/rsb/Event.h,source:trunk/cpp/core/src/rsb/Event.cpp |

| Java        | source:trunk/java/core/src/rsb/Event.java                                     |

| Python      | source:"trunk/python/core/rsb/__init__.py"                                    |

| Common Lisp | source:trunk/cl/cl-rsb/src/event.lisp                                         |