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:

digraph timestamps {
fontname=Arial
fontsize=11
node [fontsize=11,fontname=Arial]
edge [fontsize=11,fontname=Arial]

rankdir=LR
node [shape="rect"]

subgraph cluster_informer {
  label = "Informer"

  event
  node [style="rounded,filled",fillcolor="#ffc0c0"]
  create
  serialize
  send
}

subgraph cluster_in_flight {
  label = "In-flight"

  helper [shape=none,label=""]
}

subgraph cluster_listener {
  label = "Listener"

  node [style="rounded,filled",fillcolor="#c0c0ff"]
  receive
  deserialize
  deliver
}

create -> event
event -> serialize
serialize -> send
send -> helper
helper -> receive
receive -> deserialize
deserialize -> deliver

node [shape=note,style="filled",fillcolor="#ffffe0"]
create_time [label="attach create time"]
create_time -> create
send_time [label="attach send time"]
send_time -> send
receive_time [label="attach receive time"]
receive_time -> receive
deliver_time [label="attach deliver time"]
deliver_time -> deliver
}

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++ “0.15” branch of https://code.cor-lab.org/git/rsb.git.cpp at src/rsb/Event.{h,cpp}
Java /../rsb-java/rsb-java/src/main/java/rsb/Event.java
Python /../rsb-python/rsb/__init__.py
Common Lisp /../rsb-cl/src/event.lisp