YAMI4 Wolfram reference

The YAMI4 package allows Wolfram scripts and Mathematica notebooks participate in YAMI4 messaging via the gateway service.

The gateway service is a separate process and it is recommended to have its executable installed somewhere on the $Path, preferably together with the YAMI4.wl file itself. The YAMI4 package encapsulates the communication with the gateway and provides the “fat” API for convenient use within Wolfram programs.

General conventions

The YAMI4 data model relies on dictionaries (Associations) where keys are Strings and values have one of the following types:

Boolean, which is either True or False

Integer

Long Long, which can be constructed by wrapping Wolfram’s Integer in YAMI4LongLong

Real

String

Binary, which can constructed by wrapping a List of Integer values 0..255 in YAMI4Binary

List of any of the above.

When such dictionary objects are returned from YAMI4 functions, keys are always Strings, but for convenience they can be also constructed (and passed to YAMI4 as parameters) by using regular symbols as keys.

For example, the following is a dictionary with two Integer and one String fields, with keys formed from regular symbols:

Assuming that x, y and color do not evaluate into something else, the meaning of this object is the same as:

The meaning of fields in YAMI4 messaging is entirely up to the communicating parties, although run-time options have predefined (as for the C++ module) meaning.

Targets/sources (which include protocols, addresses, ports, etc.), object names and message names are Strings.

Functions

Common functions and symbols

Finds and opens the gateway process.
Path is optional and if empty, gateway is searched on $Path.
This function returns the gateway handle that is expected as a parameter to most other functions.

Initializes the agent.
Configuration options, if present, can be provided like any other parameters object (as Association).

Wrapper head for long long numeric values.

Wrapper head for binary values (list of byte values).

Closes the given object and cleans up its resources.
The object can be:
- a gateway process (if blocked, use killGateway),
- an outgoing message.

Unconditionally kills the gateway process.

Client-side functions

Send a one-way message (no reply expected) to the given remote target and object name.
Parameters are optional.

Send a message to the given remote target and object name.
Returns a handle to the outgoing message object, that can be used for further interactions with the message.
Parameters are optional.

Possible outgoing message states.

Returns the current state of the given outgoing message.

Blocks until the given message is fully transmitted.
Note : the blocking happens in the gateway object, not in the Wolfram kernel or front-end.

Blocks until response or rejection is received for the given outgoing message.
Note : the blocking happens in the gateway object, not in the Wolfram kernel or front-end.

Returns the reponse parameters (if available, for messages in replied state) for the given outgoing message.

Returns the exception message (if available, for messages in rejected state) for the given outgoing message.

Server-side functions

Adds a listener in the agent, for the specific target.
Returns the resolved target name.

Creates a new server-side object with the given name.

Returns True if the given server-side object has an incoming message ready for processing.

Blocks execution until a new incoming message is available for the given object.
Note : the blocking happens in the gateway object, not in the Wolfram kernel or front-end.

Returns remote endpoint of the client that sent request to the given object.

Returns message name of the incoming request.

Returns parameters (Association) of the object' s incoming message.

Sends reply to the client, with regard to the message received by the given object.
Reply parameters are optional.

Sends rejection to the client, with regard to the message received by the given object.
Exception message is optional.

Consumes (drops) the last message that was received for the given object.
The consumption can be necessary if neither reply nor reject is intended (for one-way messages),
so that subsequent messages can be received and processed.