Event

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
Sender id	UUID	Unique Id of the informer	yes
Event id	UUID	Unique Id of the event	lazily derived
Scope	Scope object	Destination scope	yes
Method	ASCII string		no
Data type	ASCII string	Specifies type of payload	no?
Event payload	Domain-specific object		no
Timestamps	Multiple named 64-bit integers		no
Cause vector	Set of event ids		no

Sequence Number

Event sequence numbers are 32-bit unsigned integers which indicate the order of events published by a particular informer. Sequence numbers start at 0 corresponding to the first event and are incremented by 1 for each subsequent event. Sequence numbers wrap around to 0 at 4294967296 (that is, the largest sequence number is 4294967295).

Important

Participants which receive events cannot generally rely on

1. receiving all events (according to sequence numbers) published by a particular informer. This assumption may hold, however, if the informer in question behaves according to some constraints (i.e. publishing only to one particular scope).

2. receiving events published by a particular informer in order (according to sequence numbers).

   TODO cross-reference quality of service

Sender Id

ID (a UUID) of the sending participant.

Event ID

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:

1. Construct a string representation of the sequence number

   • Radix 16

   • Lower-case letters

   • Zero-padding to width 8

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

   • namespace: id of the sending participant

   • name: the string constructed above

Examples / Test Cases:

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

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

Method

Events can carry an optional method string which indicates the role of the event in a particular communication pattern or some kind of action performed by the respective event.

Currently, the following method strings are defined:

String	Meaning
"REQUEST"	Request event of a method call
"REPLY"	Reply event of a method call

Note

The values mentioned above should not be used to indicate application-level semantics. Further, it has not yet been decided, whether new values should be introduced as needed or if some kind of coordination is required.

Timestamps

Events carry a set of timestamps. All timestamps are expressed in

1. Coordinated Universal Time (UTC)

2. since UNIX epoch

3. and stored with microsecond precision

(even if the clock source used by RSB cannot actually provide microsecond precision).

Note

When considering the issue of representing time rigorously, the above description is far from unambiguous. Since we are no experts with respect to representing time, we just say “convert your UTC time to UNIX time keeping up to 6 decimals of the remainder”.

For each event, the following timestamps are maintained by RSB:

create time

A timestamp that is automatically filled with the time at which the event object was created in the client program. This should usually reflect the time at which the notified condition most likely occurred in the sending process. If event objects are reused, this timestamp has to be reset manually by the client.

send time

The time at which the generated notification for an event was sent on the bus (after serialization).

receive time

The time at which an event is received by a listener in its serialized form (before deserialization).

deliver time

The time at which an event is dispatched to the client (after deserialization). The timestamp is set directly before passing the event to the handler.

The relation between the various timestamps is illustrated in the below figure:

Important

As indicated in the above figure, create time, send time and user times are computed using the clock source of the sending process, whereas receive time and deliver time are filled using the clock source of receiving participant’s process.

User-defined Meta Data

The following meta data items are user-defined:

user times

A set of user-defined keys and associated timestamps. These timestamps use the same encoding as the framework-maintained timestamps.

Note

The benefit of storing timestamps inside events (as opposed to within payloads) is that these timestamps can be read and manipulated by framework-level tools. E.g. when replaying a recorded data set, the replay tool can automatically adapt all timestamps to the current date, so that it appears as if the data was really sent at the current moment in time.

A drawback of maintaining timestamps inside events instead of payloads is that client programs need to extract information from two different sources: the event for the timestamp information and the payload for remaining data.

Case by case decisions need to be made regarding whether automated handling of timestamps might be beneficial or not. Generally, at least timestamps relevant to the communication should be maintained in the user timestamp structures of events.

user infos

A set of key-value user-defined options with string keys and values.

Cause Vector

Each event can have a set of causing event ids (the idea is based on [Luckham2001PEI]). The user who sends an event needs to insert the respective event ids manually if required.

Important

Currently, there is no specification regarding how these ids shall be used. Especially the handling of questions related to transitivity has not yet been solved.

Implementations

Language	File(s)
C++	“1.0” branch of https://github.com/open-rsx/rsb-cpp at src/rsb/Event.{h,cpp}
Java	upstream/rsb-java/rsb-java/src/main/java/rsb/Event.java
Python	upstream/rsb-python/rsb/__init__.py
Common Lisp	upstream/rsb-cl/src/event.lisp