RabbitMQ Transport

Note

Many file names and identifiers in this API contain placeholders for event, monitor, and synchronous set names. These placeholders are marked by the use of ALLCAPS.

This asynchronous transport sends events as messages through a RabbitMQ server. Asynchronous events are only sent or received during a call to run_manager(), so the target program should ensure this is called from time to time.

This transport also works well for pure synchronous monitor systems, where all monitors and the “pedl” keyword are in the same synchronous set. In that case, no RabbitMQ code is actually generated.

RabbitMQ Configuration

A SYSNAME.cfg file is generated along with the rest of the code for the monitors. This contains the configuration options the monitors will use for RabbitMQ. It must be located in the current directory when the monitors are started. If it cannot be found or opened, default configuration is used instead.

These are the keys that can be set:

“hostname”

Hostname or IP address for the RabbitMQ server. Default: “localhost”

“port”

Port number for the RabbitMQ server. Default: 5672

“username”

Username to log in to the RabbitMQ server with. Default: “guest”

“password”

Password to log in to the RabbitMQ server with. Default: “guest”

“exchange”

Exchange name to use. Default: “smedl.SYSNAME”

“vhost”

Vhost to use. Default: “/”

Message Format

Normally, the synchronous set to which PEDL events belong must be linked against the target program. (Usage as a shared library should also be possible, but the automatically generated Makefile would have to be modified.) When PEDL events are all placed in their own synchronous set (the default when no syncset contains the pedl, imported, or exported keywords), there is an alternative option: Have the target program emit and receive RabbitMQ messages directly.

SMEDL uses the “topic” exchange type, with routing keys that look like <channel_name>.<event_name> for PEDL events emitted from the target program and <channel_name>.<monitor_name>.<event_name> for events emitted from monitors.

RabbitMQ messages can have certain properties attached to them. SMEDL uses the following message properties:

content-type

Optional, but recommended. Set to application/json.

correlation-id

Optional. If set on an imported event, it will be copied to any exported events that result. Can be used to link exported events to their cause.

type

Optional, but highly recommended. If used, it must be set to smedl-fmt<major>.<minor>, where <major> and <minor> are the major and minor message format version. See the FMT_VERSION_* macros in the generated RabbitMQ header for the numbers to use. At the time of this writing, it is smedl-fmt2.0.

SMEDL uses JSON-formatted messages to encode events. Here is an example event message:

{
    "event": "FooMonitor.bar",
    "identities": [1],
    "params": ["baz", 123.456],
    "aux": null
}

These are the keys:

“event”

Optional and for human reference only, but for SMEDL-generated events, it will be "<monitor>.<event>". For PEDL events generated by the target system, "<event>" is recommended.

“identities”

An array of the source monitor’s identities. Should be omitted for PEDL events from the target system.

“params”

An array of the source event’s parameters.

“aux”

May be set to any valid JSON data. If not needed, it should be set to null.

For the identities and params arrays, here is how the various SMEDL types are represented in JSON:

SMEDL Type	JSON Representation
int	Number
char	Number
float	Number
string	String
pointer	String (by converting to uintptr_t and then rendering that in hexadecimal)
opaque	String