<-Controller Go to ToC Storage ->
1 Reference Model
Figure 1 depicts the Reference Model of Communication.
Figure 1 – Reference Model of Communication
Communication is how data moves: between the AIMs of a Module, between the User Agent and the boundary of the Module, between a Module and AIMs on other machines, and between Controllers. Every way data moves is a Channel or a Storage, and every Channel is served by a transport behind one interface. The Controller decides which end may reach which Channel; the transports carry the data.
Table 1 – Elements of Communication
| Element | Definition |
| Channel | Joins one Output Port to the Input Ports the Topology connects to it. It has an identity, a behaviour at each reader and a transport. |
| Channel end | The Output Port that writes to a Channel, or an Input Port that reads from it. The boundary Ports of a Module are Channel ends too, held by the User Agent. |
| Handle | What an AIM, or the User Agent, holds to act on its own ends, bound by the Controller together with a Grant. No other access to a Channel exists. |
| Message | An Object, as the schema of its Data Type defines it, with its Qualifier and the Controller’s stamp. |
| Payload | A large part of an Object – speech, a picture, a LiDAR sweep – that may travel apart from its Message. |
| Transport | What carries the Messages of a Channel and, where it can, its payloads. |
| Control path | Carries the life-cycle signals of the Controller. No AIM can write to it. |
2 Channels
A Channel has an identity: the Module instance, and the AIM Instance, Data Type and Port Number of its writer. The Controller opens both ends of every Channel the Topology declares, through its transport, and gives each AIM, and the User Agent at the boundary, only the handles to its own ends. An AIM cannot open a Channel of its own, and the AIMs never know which transport serves a Channel.
Channels are unicast from each writer: one Output Port writes to a Channel, which delivers each Message to every Input Port it joins. The Communication component is turned on jointly with the Controller and need not be persistent.
3 Messages
A Message is an Object with its Qualifier. Within one process it need not be serialised; it is serialised when it leaves the process. A reader knows what a Message is from its Data Type and Qualifier, before reading its data.
The life-cycle signals – START, STOP, PAUSE, RESUME, the High-Priority Messages – are the Controller’s own, carried on its control path, which no AIM can write. All other Messages – the Normal-Priority Messages, of MPAI-AIF defined types – are Messages on Channels.
MPAI-AIF V3.0 has no separate Event mechanism. An occurrence that AIMs must react to is a Message on a Channel. An occurrence concerning the execution of a Module is a change in the status of an AIM – Alive, Degraded, Dead – which the Controller reports through the status functions of the Controller API, and which triggers the policy the Module declares for degradation and the on Degraded: section of its Workflow.
4 Transports
Table 2 lists the transports.
Table 2 – Transports
| Transport | Ends | Messages | Payloads |
| Controller | Any | Relayed by the Controller | Through the Controller |
| InProcess | One process | In-memory bounded queue of Objects | Shared without copying |
| PointToPoint | Two processes of one machine | Length-prefixed JSON over a local socket or pipe | Shared-memory ring created by the Controller |
| Remote | An end on another machine | Length-prefixed JSON over TLS, addressed by Module instance, AIM Instance, Data Type and Port Number | Inlined |
| External | A Port of another Controller | As Remote, with the writing Controller’s stamp | Inlined |
The transport of a Channel is decided in this order: where an end is an AIM placed on another machine, Remote; otherwise the transport the Output Port’s Metadata states; the Controller transport where it states none. An Input Port may state which transports it accepts; where the Output Port’s transport is not among them, the Module does not load. A transport is never silently replaced by a slower one.
On the Remote transport, a reader end on another machine keeps the behaviour its Input Port declares, and a blocking reader holds the writer across machines as on one: a Message is acknowledged once it is put into its reader end. A link that fails delivers nothing more: the AIM at its far end is DEGRADED, and the writer goes on. The control path of an AIM host and the Channels to it share one link.
MPAI-MAS is not a transport of MPAI-AIF: it is built on MPAI-AIF and carries the Controller API between a Remote Client Application and a Service (MPAI as a Service). A Controller reaches a remote AIM through an AIM host and the Remote transport.
A Controller provides the InProcess and the Controller transports, and the Remote transport for a Channel with an end on another machine. An Output Port may declare the transport of its Channel; where it does not, the Channel uses the Controller’s default transport, and a Channel with an end on another machine uses Remote. A Controller shall not start a Module if a Channel requires a transport the Controller does not provide, or one that a reader of the Channel does not accept.
5 Port behaviour
An Input Port may declare its behaviour (Table 3).
Table 3 – Behaviour of an Input Port
| Property | Meaning |
| Depth | The number of Messages the Port holds. |
| Overflow | What a write to a full Port does: Block, DropOldest or DropNewest. |
| MaxAge | The age beyond which a Message is discarded rather than delivered. |
| AcceptedTransports | The transports the Port accepts. |
A Port that declares none is Block, with a Depth of the Implementation’s choosing and no MaxAge – the behaviour suited to an exchange. Messages dropped or discarded are counted. Every blocking operation takes a timeout.
A loop needs its feedback declared. A feedback input that Blocks deadlocks the loop when inputs come faster than it turns, since the writer of the feedback waits on a full Port that only new inputs empty. A feedback input therefore keeps its latest value: Depth 1, DropOldest.
6 Communication in the two execution models
A Module is executed by exchange or continuously, as its Metadata declares (Execution). The two models communicate differently (Table 4).
Table 4 – Communication in the two execution models
| Exchange | Continuous | |
| User Agent at the boundary | Writes the inputs it has to boundary Input Ports, then reads the boundary Output Ports it wants. Over MPAI-MAS, an exchange closes at the first Output read after one or more Input writes: that read runs the Module on the inputs written. | Binds devices to boundary Ports for the life of the Workflow. Messages flow as streams. |
| Port behaviour | Block, the default. A Port receives at most one Message in an exchange. | As each Input Port declares: a sensor stream typically with MaxAge and DropOldest; a feedback input with Depth 1 and DropOldest. |
| Nothing produced | A boundary Output Port that produced nothing returns NOT_PRODUCED, which is not an error. | The Port has no pending Message. A reader selects among the Ports with pending Messages. |
| Waiting | No suspension: a Module never waits for an input the User Agent did not undertake to give. | No suspension at the boundary either. A required input that delivers nothing within its MaxAge makes the AIM DEGRADED. |
An exchange is a special case of continuous execution: Messages written to the boundary, each AIM run once on what it has received, the Outputs read. The same Channels, transports and Port behaviours serve both.
7 Payloads
A large payload may travel apart from its Message. The writer places it on the path of its Channel, and the Object carries its length and a reference to it, as the schemas of media Objects allow. The Qualifier always travels in the Message, so that a reader knows what a payload is before fetching it. Only a reader at the far end of that Channel can resolve the reference, and a payload is freed when every reader has released it or its Port’s MaxAge has passed. At the boundary of a Controller – Remote, External, MPAI-MAS – a payload is inlined: a reference means nothing outside the Controller that issued it.
The writer of an Object decides whether its data travel inline or by reference, within the forms its Data Type allows; no size threshold applies. A reference issued by a Controller has the form aif:payload/<Channel>/<sequence>, where <Channel> identifies the Channel as <Module>/<writer AIM>.<DataType>#<PortNumber>. It is valid only within the Controller that issued it, and is released when every reader of the Channel has taken the Message or the largest MaxAge of its readers has passed. Where a Message leaves the Controller that issued its references – to an AIM host, to another Controller, or to the User Agent – the Controller replaces each reference with the data.
8 Time
A Controller has one time base, declared in its Metadata. Every Message is stamped, when written, with the time on that base, through the handle the Controller bound; the writer supplies no stamp. A Message written on another machine is stamped on the same base: the machine moves its clock by the offset of the Controller’s, measured over the link when a Module starts there.
A time an Object carries of its own – the time of its acquisition, for instance – is a different fact, and travels in the Object. An AIM that must run at a period, or complete within a deadline, declares Period or Deadline in its Metadata, and a Controller that cannot honour them refuses the Module when it is started.
An AIM host stamps Messages on the time base of the Controller it serves: before running the AIMs placed on it, it estimates the offset of the Controller’s clock from its own by request and response, taking the Controller’s time as of the midpoint of the fastest of several exchanges. MaxAge is measured on the local monotonic clock from the arrival of a Message. Controllers stamp in UTC; a Message between Controllers carries the identifier and the stamp of the Controller that wrote it. How a Controller keeps its clock close to UTC – for instance with GNSS or gPTP in a vehicle – is a matter of the Implementation.
9 Between Controllers
A Controller may discover Controllers in range running the same type of Module – other vehicles, for instance – and exchange Messages with Ports of theirs, the External Ports, over the External transport. The identifier of a discovered Controller is valid from the discovery that returned it until that Controller leaves range. A Message from another Controller carries that Controller’s stamp and is signed by it.
Channels between Controllers exist only between Controllers that discover each other as specified above: each Controller announces its controllerID, the type of its Module and its address; Controllers running the same type of Module that are in range open one link, admitted by the Trust Protocol, and close it when the other is no longer heard or no longer in range.
10 Security
Every read and write passes through a handle the Controller bound, and the transport checks the Grant of that handle at every operation, not once at opening. Messages are immutable once written. Between processes, Channels are authenticated local channels; between machines and between Controllers, Messages travel over TLS and payloads are inlined. The handles of a stopped Module are dead (Zero Trust and Profiles).
11 Requirements
Table 5 – Requirements of Communication
| # | Requirement |
| COM-1 | Data shall move between AIMs, and between a User Agent and a Module, only on Channels the Controller established, or through Storage. |
| COM-2 | A Channel shall be addressed by Data Type and Port Number, never by a Port name. |
| COM-3 | A Message shall carry its Qualifier, including when its payload travels apart. |
| COM-4 | A transport shall check the Grant of a handle at every operation. |
| COM-5 | A transport shall not be replaced by another that the Input Port does not accept, nor silently by a slower one. |
| COM-6 | Every Message shall be stamped on the Controller’s time base when written; the writer shall supply no stamp. |
| COM-7 | A payload shall be inlined when it crosses the boundary of a Controller. |
| COM-8 | Messages dropped or discarded shall be counted. |
