<-Execution Go to ToC MPAI Store ->
1 Reference Model
Figure 1 depicts who calls which API.
Figure 1 – The Basic API
The Controller API is the one interface of the Controller. It has four faces: called by the User Agent (3), called by the AIMs of the Module (4), called by another Controller (5), and called by a Provider (6). The Store API is specified in MPAI Store, the Security API in Security API.
2 Conventions
The API is written in a C-like fashion. It is meant as a definition for any programming language. The functions of the Controller API called by the User Agent begin with MPAI_AIFU_, those called by AIMs and by the Controller with MPAI_AIFM_, those of the Store API with MPAI_AIFS_ (MPAI Store).
2.1 API types
Table 1 – API types
| Type | Meaning |
| message_t | The type of the Messages passed through Ports and Channels: an Object with its Qualifier. |
| parser_t | The type of a parsed Message data type (the high-level protocol). |
| error_t | The type of the outcome a function returns (2.3). |
| storage_time_t | How long a datum is kept: until the Module instance stops, until the session ends, as long as the scope is kept, or within a duration (Storage). |
| storage_rule_t | The general rules of a category: its writers, its readers and its longest time. |
| storage_trace_t | What is known of a datum: its writer, its stamp, its category, its readers, its time and the rule under which it was written. |
| key_info_t | The provenance and length of the value at a key (3.11.2). |
| aim_report_t | The status of an AIM with what it has reported. |
These types are opaque, and their definition is left to the Implementer. The only meaningful way to operate on them is through the functions of the API. The type of AIM Implementations is always
typedef error_t *(module_t)()
across all Implementations, to ensure cross-compatibility. Types such as void, size_t, char, int, bool and float are regular C types.
2.2 Addressing
A Module is addressed by the MODULE_ID the Controller returned when it started it. A Port is addressed by its Data Type and its Port Number: where a Module or an AIM declares one Port of a Direction and Data Type, its Metadata omits the Port Number and a call gives 1. A Port name is a label for the reader of the Metadata and addresses nothing. An AIM is addressed by its AIM Instance Identifier; where several Sub-AIMs of a Composite AIM share one, by it and its AIM Number.
2.3 Outcomes
Every function returns an outcome, so that a caller can tell apart what did not happen from what went wrong (Table 2).
Table 2 – Outcomes
| Outcome | Meaning |
| MPAI_AIF_OK (0) | The call succeeded. |
| MPAI_AIF_NOT_PRODUCED | The Port produced nothing: in an exchange, in the run just completed; in continuous execution, nothing was pending when the timeout expired. This is not an error. |
| MPAI_AIF_TIMEOUT | Nothing happened within the timeout of the call. This is an outcome, not an error of the AIM. |
| MPAI_AIF_NO_SUCH_PORT | No Port of that Data Type and Port Number exists. |
| MPAI_AIF_TYPE_NOT_ACCEPTED | The Port does not accept the Data Type of the datum. |
| MPAI_AIF_NOT_STARTED | The Module or the AIM is not running. |
| MPAI_AIF_NOT_AUTHORISED | The caller has no Grant for the operation, or the rules of the data do not allow it. |
| MPAI_AIF_NOT_TRUSTED | The Module was refused: an Implementation or a model is not what the MPAI Store approved. |
| MPAI_AIF_BUFFER_TOO_SMALL | The buffer supplied is smaller than the value; the size required is returned (2.4). |
| MPAI_AIF_FAILED | The operation failed for another reason, which the Controller states. |
The status of an AIM is one of MPAI_AIM_ALIVE (1), MPAI_AIM_DEAD (2) and MPAI_AIM_DEGRADED (3). An Implementation may return, in place of MPAI_AIF_FAILED, the more specific error codes of Table 3.
Table 3 – Error codes
| Code | Meaning |
| MPAI_ERROR | A generic error. |
| MPAI_ERROR_MEM_ALLOC | A memory allocation error. |
| MPAI_ERROR_MODULE_NOT_FOUND | The operation requested of a Module cannot be executed, since the Module has not been found. |
| MPAI_ERROR_INIT | The AIM cannot be initialised. |
| MPAI_ERROR_TERM | The AIM cannot be properly terminated. |
| MPAI_ERROR_MODULE_CREATION_FAILED | A new AIM cannot be created. |
| MPAI_ERROR_PORT_CREATION_FAILED | A new AIM Port cannot be created. |
| MPAI_ERROR_CHANNEL_CREATION_FAILED | A new Channel between AIMs cannot be created. |
| MPAI_ERROR_WRITE | A generic Message writing error. |
| MPAI_ERROR_TOO_MANY_PENDING_MESSAGES | A write failed because too many Messages are waiting to be delivered. |
| MPAI_ERROR_PORT_NOT_FOUND | One or both Ports of a connection have been removed. |
| MPAI_ERROR_READ | A generic Message reading error. |
| MPAI_ERROR_OP_FAILED | The requested operation failed. |
| MPAI_ERROR_EXTERNAL_CHANNEL_CREATION_FAILED | A new Channel between Controllers cannot be created. |
2.4 Timeouts and buffers
Every blocking call takes timeout_ms, in milliseconds: 0 means do not block, a negative value means wait without limit. On expiry the call returns MPAI_AIF_TIMEOUT.
A function returning a value of unknown length follows one convention: on entry the caller states the size of the buffer it supplies; where the value is longer, the function returns MPAI_AIF_BUFFER_TOO_SMALL and the size required, so that the caller may allocate and retry. A call with a NULL buffer is permitted purely to learn that size. The caller owns what it supplied; it does not own what a function returns beyond the next call.
2.5 Life-cycle signals
The life-cycle signals – the High-Priority Messages – are the Controller’s own, carried on its control path, which no AIM can write (Table 4).
Table 4 – Life-cycle signals
| Signal | Numeric value |
| MPAI_AIM_SIGNAL_START | 1 |
| MPAI_AIM_SIGNAL_STOP | 2 |
| MPAI_AIM_SIGNAL_RESUME | 3 |
| MPAI_AIM_SIGNAL_PAUSE | 4 |
3 Controller API called by the User Agent
With these functions the User Agent initialises the Controller; starts, pauses, resumes and stops a Module; gives data to its boundary Input Ports and collects data from its boundary Output Ports; inquires the status of its AIMs; initialises Storage and records the boundary; keeps the sessions of its clients; and manages resources. Over the network the same functions are carried by MPAI-MAS (MPAI as a Service).
3.1 The Controller
3.1.1 MPAI_AIFU_Controller_Initialize
error_t MPAI_AIFU_Controller_Initialize()
Switches on and initialises the Controller, in particular the Communication component, and begins the session of the User Agent.
3.1.2 MPAI_AIFU_Controller_Destroy
error_t MPAI_AIFU_Controller_Destroy()
Switches off the Controller, after the data structures of the running Modules have been disposed of.
3.2 Module life cycle
An error in transmitting or receiving a life-cycle signal does not terminate the Module: the AIM concerned becomes DEGRADED, and the Module’s OnDegraded policy applies (Controller).
3.2.1 MPAI_AIFU_MODULE_Start
error_t MPAI_AIFU_MODULE_Start(const char* name, int* MODULE_ID)
Starts an instance of the Module whose AIM Instance Metadata is identified by name, after the Controller has obtained, verified and built it. The ID of the instance is returned in MODULE_ID. Returns MPAI_AIF_NOT_TRUSTED where an Implementation or a model is not what the MPAI Store approved, and MPAI_AIF_FAILED, with the reason, where the Metadata cannot be resolved or a declared Period or Deadline cannot be honoured.
3.2.2 MPAI_AIFU_MODULE_Pause
error_t MPAI_AIFU_MODULE_Pause(int MODULE_ID)
Pauses the Module with ID MODULE_ID. If the operation succeeds, it has immediate effect.
3.2.3 MPAI_AIFU_MODULE_Resume
error_t MPAI_AIFU_MODULE_Resume(int MODULE_ID)
Resumes the Module with ID MODULE_ID. If the operation succeeds, it has immediate effect.
3.2.4 MPAI_AIFU_MODULE_Stop
error_t MPAI_AIFU_MODULE_Stop(int MODULE_ID)
Stops the Module with ID MODULE_ID. Its Grants are revoked, its handles are dead, and what was placed on AIM hosts is released. If the operation succeeds, it has immediate effect.
3.2.5 MPAI_AIFU_AIM_Stop
error_t MPAI_AIFU_AIM_Stop(int MODULE_ID, const char* AIM_name)
Stops the AIM with AIM Instance Identifier AIM_name of the Module with ID MODULE_ID. The other AIMs go on without it.
3.3 Data exchange
3.3.1 MPAI_AIFU_MODULE_Input_Write
error_t MPAI_AIFU_MODULE_Input_Write(int MODULE_ID, const char* DataType,
int PortNumber, message_t* message, int timeout_ms)
Gives message to the boundary Input Port identified by DataType and PortNumber of the Module with ID MODULE_ID. Returns MPAI_AIF_NO_SUCH_PORT where the Module declares no such boundary Port, and MPAI_AIF_TYPE_NOT_ACCEPTED where the Data Type is not among those the Port accepts. In continuous execution, the write follows the Overflow of the Port and observes timeout_ms.
3.3.2 MPAI_AIFU_MODULE_Output_Read
error_t MPAI_AIFU_MODULE_Output_Read(int MODULE_ID, const char* DataType,
int PortNumber, message_t* message, int timeout_ms)
Collects a Message from the boundary Output Port identified by DataType and PortNumber of the Module with ID MODULE_ID. In an exchange, the first read after one or more writes runs the Module on the inputs written; a Port that produced nothing returns MPAI_AIF_NOT_PRODUCED, which is not an error. In continuous execution, the read returns the oldest pending Message, and MPAI_AIF_NOT_PRODUCED means that nothing was pending when timeout_ms expired.
3.3.3 MPAI_AIFU_Payload_Put, _Get and _Release
error_t MPAI_AIFU_Payload_Put(int MODULE_ID, const char* DataType, int PortNumber,
const void* data, size_t data_length,
char* reference, size_t* reference_length)
error_t MPAI_AIFU_Payload_Get(int MODULE_ID, const char* reference, void* data,
size_t* data_length, size_t offset)
error_t MPAI_AIFU_Payload_Release(int MODULE_ID, const char* reference)
The functions of 4.8, for the boundary Ports of the Module with ID MODULE_ID. A User Agent supplying an Object with a large payload places the payload with MPAI_AIFU_Payload_Put on the path of the boundary Input Port, and writes a Message whose data entry references it. It collects such an Object from a boundary Output Port in the reverse order.
3.4 Status
3.4.1 MPAI_AIFU_AIM_GetStatus
error_t MPAI_AIFU_AIM_GetStatus(int MODULE_ID, const char* AIM_name, int* status)
Returns in status the status of the AIM AIM_name of the Module with ID MODULE_ID: MPAI_AIM_ALIVE, MPAI_AIM_DEGRADED or MPAI_AIM_DEAD. An AIM is DEGRADED while it runs on less than it was designed to.
3.4.2 MPAI_AIFU_MODULE_GetStatus
error_t MPAI_AIFU_MODULE_GetStatus(int MODULE_ID, aim_report_t* aims, int* count)
Returns, for every AIM of the Module with ID MODULE_ID, its status with what it has reported (4.10), and in count their number, with the convention of 2.4.
3.5 Storage
3.5.1 MPAI_AIFU_SharedStorage_Init
error_t MPAI_AIFU_SharedStorage_Init(int MODULE_ID, const char* location,
const char* control_MODULE)
Initialises the Storage scope of the Module with ID MODULE_ID at location – one location for several Modules to share it – and names, where there is one, the Module whose central control governs it (control_MODULE, or NULL). The interpretation of location is an Implementation matter. The User Agent says where Storage is and nothing else: it cannot say what identity a write will carry.
3.5.2 MPAI_AIFU_SharedStorage_Keep
error_t MPAI_AIFU_SharedStorage_Keep(const char* location, const char* category,
storage_time_t time)
States how long the data of category are kept at location where their writer does not say – a decision of the deployment, for example: what the persons of a session register, as long as the session.
3.6 Record of the boundary
3.6.1 MPAI_AIFU_Record_Start
error_t MPAI_AIFU_Record_Start(int MODULE_ID, char* record_ID, size_t* record_ID_length)
Starts the record of the boundary of the Module with ID MODULE_ID into its Private Storage (Storage), and returns its identifier. The Storage scope of the Module shall have been initialised.
3.6.2 MPAI_AIFU_Record_Stop
error_t MPAI_AIFU_Record_Stop(int MODULE_ID, char* totals, size_t* totals_length)
Stops the record and returns, per boundary Port, how many Messages were recorded and how many could not be. Returns MPAI_AIF_NOT_AUTHORISED where the Metadata of the Module declares Record Always.
3.7 Sessions
3.7.1 MPAI_AIFU_Session_Serve
error_t MPAI_AIFU_Session_Serve(int MODULE_ID, const char* session)
Declares whose session the next exchanges of the Module with ID MODULE_ID serve: the data they keep for a session are that client’s. NULL returns to the session of the User Agent.
3.7.2 MPAI_AIFU_Session_End
error_t MPAI_AIFU_Session_End(const char* session)
Ends session. What the exchanges kept for the session is deleted at once.
3.8 Resource allocation
3.8.1 MPAI_AIFU_Resource_GetGlobal
error_t MPAI_AIFU_Resource_GetGlobal(const char* key, const char* min_value,
const char* max_value, const char* requested_value)
Interrogates the resource allocation for one AIF Metadata entry.
3.8.2 MPAI_AIFU_Resource_SetGlobal
error_t MPAI_AIFU_Resource_SetGlobal(const char* key, const char* min_value,
const char* max_value, const char* requested_value)
Initialises the resource allocation for one AIF Metadata entry.
3.8.3 MPAI_AIFU_Resource_GetMODULE
error_t MPAI_AIFU_Resource_GetMODULE(int MODULE_ID, const char* key, const char* min_value,
const char* max_value, const char* requested_value)
Interrogates the resource allocation for one AIM Instance Metadata entry of the Module with ID MODULE_ID.
3.8.4 MPAI_AIFU_Resource_SetMODULE
error_t MPAI_AIFU_Resource_SetMODULE(int MODULE_ID, const char* key, const char* min_value,
const char* max_value, const char* requested_value)
Initialises the resource allocation for one AIM Instance Metadata entry of the Module with ID MODULE_ID.
3.9 Access
With these functions the User Agent provides the content of a Source of Access of which the User is the Writer.
3.9.1 MPAI_AIFU_Access_Create
error_t MPAI_AIFU_Access_Create(const char* source)
Creates the Source source, whose Writer the User becomes. Fails if the Source exists.
3.9.2 MPAI_AIFU_Access_Put
error_t MPAI_AIFU_Access_Put(const char* source, const char* key, const void* data, size_t data_length)
Writes data at key in source and raises the Version of the Source. Returns MPAI_AIF_NOT_AUTHORISED if the User is not the Writer of the Source.
3.9.3 MPAI_AIFU_Access_Delete
error_t MPAI_AIFU_Access_Delete(const char* source, const char* key)
Removes the item at key from source and raises the Version of the Source. Returns MPAI_AIF_NOT_AUTHORISED if the User is not the Writer of the Source.
4 Controller API called by AIMs
4.1 General
These functions are a control plane. They govern which AIM may reach which Port, when an AIM runs and what it may obtain; they do not prescribe how the bytes of a Message travel. An Implementation in which the Controller hands a Message to an AIM and takes one back conforms, as does one in which an AIM reads and writes its own Ports through handles the Controller bound, provided that in both the Controller alone decides what an AIM may reach.
For each Channel the Topology declares, the Controller establishes the path by which its Messages travel, which may or may not pass through the Controller (Communication). An AIM cannot open a path of its own, or reach a Port the Controller has not bound to it. What the framework records of a Message – its time, what a Port drops – is recorded through the handle, never supplied by the AIM.
The Metadata is authoritative. An AIM may not register an AIM, or create a Channel, that the Module’s Metadata does not declare. Where a Controller builds the Module from its Metadata, the functions of 4.3 and 4.5 need not be exposed, and an Implementation that does not expose them conforms.
4.2 Resource allocation
4.2.1 MPAI_AIFM_Resource_GetGlobal
error_t MPAI_AIFM_Resource_GetGlobal(const char* key, const char* min_value,
const char* max_value, const char* requested_value)
With this function the AIM interrogates the resource allocation for one AIF Metadata entry.
4.2.2 MPAI_AIFM_Resource_SetGlobal
error_t MPAI_AIFM_Resource_SetGlobal(const char* key, const char* min_value,
const char* max_value, const char* requested_value)
With this function the AIM initialises the resource allocation for one AIF Metadata entry.
4.2.3 MPAI_AIFM_Resource_GetMODULE
error_t MPAI_AIFM_Resource_GetMODULE(int MODULE_ID, const char* key, const char* min_value,
const char* max_value, const char* requested_value)
With this function the AIM interrogates the resource allocation for one AIM Instance Metadata entry of the Module with ID MODULE_ID.
4.2.4 MPAI_AIFM_Resource_SetMODULE
error_t MPAI_AIFM_Resource_SetMODULE(int MODULE_ID, const char* key, const char* min_value,
const char* max_value, const char* requested_value)
With this function the AIM initialises the resource allocation for one AIM Instance Metadata entry of the Module with ID MODULE_ID.
4.3 Registering AIMs
4.3.1 MPAI_AIFM_AIM_Register_Local
error_t MPAI_AIFM_AIM_Register_Local(const char* AIM_name)
Registers the AIM AIM_name with the Controller, to run where the Controller runs. The AIM shall be one the Metadata of the Module declares; the Controller refuses any other. Its Implementation shall have been obtained, and verified, as the AIM Instance Metadata states.
4.3.2 MPAI_AIFM_AIM_Register_Remote
error_t MPAI_AIFM_AIM_Register_Remote(const char* AIM_name, const char* uri)
Registers the AIM AIM_name with the Controller, to run on the AIM host identified by uri, under the Controller’s control (Controller). The AIM shall be one the Metadata of the Module declares.
4.3.3 MPAI_AIFM_AIM_Deregister
error_t MPAI_AIFM_AIM_Deregister(const char* AIM_name)
Deregisters the AIM AIM_name from the Controller.
4.4 Life-cycle requests to other AIMs
Where allowed, an AIM may ask the Controller to change the life cycle of another AIM of its Module. An error in transmitting or receiving a life-cycle signal does not terminate the AIM: it is reported to the Controller and to the AIMs at both ends of the Channel concerned, the AIM becomes DEGRADED, and the Module’s OnDegraded policy applies.
4.4.1 MPAI_AIFM_AIM_Start
error_t MPAI_AIFM_AIM_Start(const char* AIM_name)
Asks the Controller to start the AIM AIM_name. If the operation succeeds, it has immediate effect.
4.4.2 MPAI_AIFM_AIM_Pause
error_t MPAI_AIFM_AIM_Pause(const char* AIM_name)
Asks the Controller to pause the AIM AIM_name. If the operation succeeds, it has immediate effect.
4.4.3 MPAI_AIFM_AIM_Resume
error_t MPAI_AIFM_AIM_Resume(const char* AIM_name)
Asks the Controller to resume the AIM AIM_name. If the operation succeeds, it has immediate effect.
4.4.4 MPAI_AIFM_AIM_Stop
error_t MPAI_AIFM_AIM_Stop(const char* AIM_name)
Asks the Controller to stop the AIM AIM_name. If the operation succeeds, it has immediate effect.
4.5 Channels
4.5.1 MPAI_AIFM_Channel_Create
error_t MPAI_AIFM_Channel_Create(const char* name,
const char* out_AIM_name, const char* out_DataType, int out_PortNumber,
const char* in_AIM_name, const char* in_DataType, int in_PortNumber)
Asks the Controller to create the Channel name between an Output Port and an Input Port, each identified by its AIM, Data Type and Port Number. The Channel shall correspond to a connection the Topology declares; the Controller refuses any other.
4.5.2 MPAI_AIFM_Channel_Destroy
error_t MPAI_AIFM_Channel_Destroy(const char* name)
Asks the Controller to destroy the Channel name. The Ports of the Channel are closed.
4.6 Ports
A Port behaves as its Metadata declares – Depth, Overflow, MaxAge – and Messages dropped or discarded are counted (Communication).
4.6.1 MPAI_AIFM_Port_Output_Read
message_t* MPAI_AIFM_Port_Output_Read(const char* AIM_name,
const char* DataType, int PortNumber, int timeout_ms)
Reads a Message from the Port identified by AIM_name, DataType and PortNumber, waiting at most timeout_ms. It returns a copy of the original Message.
4.6.2 MPAI_AIFM_Port_Input_Write
error_t MPAI_AIFM_Port_Input_Write(const char* AIM_name, const char* DataType,
int PortNumber, message_t* message, int timeout_ms)
Writes message to the Port identified by AIM_name, DataType and PortNumber, following its Overflow and waiting at most timeout_ms. The Message shall remain available until the function returns. The Controller stamps the Message with its time; the writer supplies no stamp.
4.6.3 MPAI_AIFM_Port_Reset
error_t MPAI_AIFM_Port_Reset(const char* AIM_name, const char* DataType, int PortNumber)
Resets the Port by deleting all its pending Messages.
4.6.4 MPAI_AIFM_Port_CountPendingMessages
size_t MPAI_AIFM_Port_CountPendingMessages(const char* AIM_name,
const char* DataType, int PortNumber)
Returns the number of pending Messages of the Port.
4.6.5 MPAI_AIFM_Port_CountDropped
size_t MPAI_AIFM_Port_CountDropped(const char* AIM_name, const char* DataType, int PortNumber)
Returns the number of Messages the Port has dropped or discarded.
4.6.6 MPAI_AIFM_Port_Probe
error_t MPAI_AIFM_Port_Probe(const char* AIM_name, const char* DataType,
int PortNumber, int timeout_ms)
Returns MPAI_AIF_OK if the Port is an Input Port an AIM can write to, or an Output Port from which data can be read, within timeout_ms.
4.6.7 MPAI_AIFM_Port_Output_Select
int MPAI_AIFM_Port_Output_Select(int timeout_ms, int count,
const char* AIM_name_1, const char* DataType_1, int PortNumber_1, ...)
Given a list of Ports, returns the index of one for which a Message has become available, waiting at most timeout_ms. An AIM that selects among its Ports runs whenever a Message arrives: this is continuous execution (Execution).
4.7 Messages
All Implementations provide a common Message passing functionality, abstracted by the following functions. The type system is specified in Metadata.
4.7.1 MPAI_AIFM_Message_Copy
message_t* MPAI_AIFM_Message_Copy(message_t* message)
Makes a copy of message.
4.7.2 MPAI_AIFM_Message_Delete
message_t* MPAI_AIFM_Message_Delete(message_t* message)
Deletes message and its allocated memory.
4.7.3 MPAI_AIFM_Message_GetBuffer
void* MPAI_AIFM_Message_GetBuffer(message_t* message)
Gives access to the low-level memory buffer of message.
4.7.4 MPAI_AIFM_Message_GetBufferLength
size_t MPAI_AIFM_Message_GetBufferLength(message_t* message)
Returns the size in bits of the low-level memory buffer of message.
4.7.5 MPAI_AIFM_Message_Parse
parser_t* MPAI_AIFM_Message_Parse(const char* type)
Creates a parsed representation of the data type type, to parse the raw memory buffers of Messages with the functions below.
4.7.6 MPAI_AIFM_Message_Parse_Get_StructField
void* MPAI_AIFM_Message_Parse_Get_StructField(parser_t* parser, void* buffer,
const char* field_name)
Where buffer holds data of a struct_type whose parsed definition is in parser, fetches the element named field_name and returns it in a freshly allocated buffer; NULL if there is no such element.
4.7.7 MPAI_AIFM_Message_Parse_Get_VariantType
void* MPAI_AIFM_Message_Parse_Get_VariantType(parser_t* parser, void* buffer,
const char* type_name)
Where buffer holds data of a variant_type whose parsed definition is in parser, fetches the member named type_name and returns it in a freshly allocated buffer; NULL if there is no such member.
4.7.8 MPAI_AIFM_Message_Parse_Get_ArrayLength
int MPAI_AIFM_Message_Parse_Get_ArrayLength(parser_t* parser, void* buffer)
Where buffer holds data of an array_type whose parsed definition is in parser, returns the length of the array; -1 if buffer does not hold an array.
4.7.9 MPAI_AIFM_Message_Parse_Get_ArrayField
void* MPAI_AIFM_Message_Parse_Get_ArrayField(parser_t* parser, void* buffer,
const int field_num)
Where buffer holds data of an array_type whose parsed definition is in parser, fetches the element field_num and returns it in a freshly allocated buffer; NULL if there is no such element.
4.7.10 MPAI_AIFM_Message_Parse_Delete
void MPAI_AIFM_Message_Parse_Delete(parser_t* parser)
Deletes the parsed representation parser and deallocates its memory.
4.8 Payloads
A Message may carry the payload of its Object by reference, and an Implementation may require it to above a size it declares. The data entry of the Object carries DataLength and, as DataURI, the reference returned. The Qualifier always travels in the Message, so that a reader knows what a payload is before it fetches it, and may decline to.
4.8.1 MPAI_AIFM_Payload_Put, _Get and _Release
error_t MPAI_AIFM_Payload_Put(const char* AIM_name, const char* DataType, int PortNumber,
const void* data, size_t data_length,
char* reference, size_t* reference_length)
error_t MPAI_AIFM_Payload_Get(const char* reference, void* data,
size_t* data_length, size_t offset)
error_t MPAI_AIFM_Payload_Release(const char* reference)
MPAI_AIFM_Payload_Put places data on the path of the Channel leaving the Output Port identified by AIM_name, DataType and PortNumber, and returns the reference to write into the Object. MPAI_AIFM_Payload_Get retrieves it with the convention of 2.4, and returns MPAI_AIF_NOT_AUTHORISED unless the caller is at the far end of that Channel. MPAI_AIFM_Payload_Release declares that the caller has finished with it. A payload is freed when every reader has released it or the MaxAge of its Port has passed, whichever comes first. Where the path permits, an Implementation may give a reader the payload without copying it.
4.9 Time
4.9.1 MPAI_AIFM_Time_Get
error_t MPAI_AIFM_Time_Get(char SimpleTime[32])
Returns the present time on the Controller’s time base, declared in the AIF Metadata, as Simple Time.
4.9.2 MPAI_AIFM_Message_GetTime
error_t MPAI_AIFM_Message_GetTime(message_t* message, char SimpleTime[32])
Returns the time at which message was written, recorded through the handle the Controller bound and never supplied by the writer. A time the Object carries of its own, such as the time of an acquisition, is a different fact and is unaffected.
4.10 Reports
4.10.1 MPAI_AIFM_AIM_Report
error_t MPAI_AIFM_AIM_Report(const char* AIM_name, const char* text)
Reports, to whoever operates the AIF, something the AIM did or could not do: a resource absent and substituted for, an input accepted with a reduced interpretation, a model falling back to a simpler path. The Controller conveys the report, does not interpret it and takes no action on it; where nothing has asked to receive reports, the call succeeds and the report is discarded. A report is not an error: an AIM that cannot proceed returns an error through its normal result.
4.11 Storage
An AIM reaches its Private Storage, the Private Storage of its Module and Shared Storage through handles the Controller bound to its identity when it instantiated it (Storage). Every write is stamped by the Controller with the Module, the AIM and the time; the caller supplies neither.
4.11.1 Storage under rules
4.11.1.1 MPAI_AIFM_RuledStorage_Put
error_t MPAI_AIFM_RuledStorage_Put(const char* key, const void* data, size_t data_length,
const char* category, const char** readers,
int readers_count, storage_time_t* time)
Stores data at key under category, naming its readers (Modules, AIM Instances, the User Agent) and its time; NULL readers or time leave them to the rules. Where a central control governs the Storage, a writer may restrict its general rules and may not extend them: a write that tries returns MPAI_AIF_NOT_AUTHORISED.
4.11.1.2 MPAI_AIFM_RuledStorage_Get
error_t MPAI_AIFM_RuledStorage_Get(const char* key, void* data, size_t* data_length)
Retrieves the value at key, with the convention of 2.4, where the rules allow the caller to read it; MPAI_AIF_NOT_AUTHORISED otherwise.
4.11.1.3 MPAI_AIFM_RuledStorage_Delete
error_t MPAI_AIFM_RuledStorage_Delete(const char* key)
Deletes the value at key, where the rules allow the caller to.
4.11.1.4 MPAI_AIFM_RuledStorage_List
error_t MPAI_AIFM_RuledStorage_List(const char* category, const char* prefix,
char** keys, int* count)
Returns the keys the caller may read that begin with prefix, of category or, where category is NULL, of any category, with the convention of 2.4.
4.11.1.5 MPAI_AIFM_RuledStorage_Exists
error_t MPAI_AIFM_RuledStorage_Exists(const char* key, bool* exists)
Sets exists to true where a value the caller may read is stored at key.
4.11.1.6 MPAI_AIFM_RuledStorage_Trace
error_t MPAI_AIFM_RuledStorage_Trace(const char* key, storage_trace_t* trace)
Returns what is known of the datum at key: its writer, its stamp, its category, its readers, its time and the rule under which it was written. No field is supplied by a caller.
4.11.1.7 MPAI_AIFM_RuledStorage_SetRule
error_t MPAI_AIFM_RuledStorage_SetRule(const char* category, storage_rule_t* rule)
Sets the general rules of category: who may write, who may read, the longest time. Only the central control – the AIM the Metadata names as StorageControl – may call it; a narrowing applies at once to what was written.
4.11.2 Key-value Storage
Key-value functions. They operate on the Storage scope initialised for the Module with MPAI_AIFU_SharedStorage_Init, under the rules of the data.
4.11.2.1 MPAI_AIFM_SharedStorage_Put
error_t MPAI_AIFM_SharedStorage_Put(const char* key, const void* data,
size_t data_length, size_t offset)
Stores data at key, from offset for data_length, visible to every AIM of the Module instance. A Put at offset 0 replaces the whole value; a Put beyond the current length zero-fills the gap; a Put to a key that does not exist creates it. A Put is atomic with respect to a key: a reader observes either the whole previous value or the whole new one, never a mixture, and never a value without its provenance. Ordering between writers is not guaranteed: concurrent Puts to one key resolve last-writer-wins.
4.11.2.2 MPAI_AIFM_SharedStorage_Get
error_t MPAI_AIFM_SharedStorage_Get(const char* key, void* data,
size_t* data_length, size_t offset)
Retrieves the value at key, from offset, with the convention of 2.4. Returns an error if no value exists at key.
4.11.2.3 MPAI_AIFM_SharedStorage_Delete
error_t MPAI_AIFM_SharedStorage_Delete(const char* key)
Removes the value at key, if any. Deleting a key that does not exist is not an error.
4.11.2.4 MPAI_AIFM_SharedStorage_List
error_t MPAI_AIFM_SharedStorage_List(const char* prefix, char** keys, int* count)
Returns every stored key that begins with prefix (an empty prefix matches every key), with the convention of 2.4. It is the only enumeration primitive: every richer query is a List with a suitable prefix.
4.11.2.5 MPAI_AIFM_SharedStorage_Exists
error_t MPAI_AIFM_SharedStorage_Exists(const char* key, bool* exists)
Sets exists to true if a value is stored at key, without transferring it.
4.11.2.6 MPAI_AIFM_SharedStorage_GetKeyInfo
typedef struct {
char StoredBy[256]; // Module, and the AIM within it, that performed the Put
char RequestedBy[256]; // the client of the User Agent on whose behalf it was made, or empty
char StoredAt[32]; // Simple Time of the most recent Put
size_t Length; // size in bytes of the value currently stored
} key_info_t;
error_t MPAI_AIFM_SharedStorage_GetKeyInfo(const char* key, key_info_t* info)
Retrieves the provenance of the most recent Put to key, recorded by the framework at each Put and never supplied by a caller. StoredBy identifies the Module and the AIM within it: an AIM name alone identifies nothing, since the same AIM may be a Sub-AIM of many Modules.
Where a Put is made on behalf of a User Agent, StoredBy identifies the AIM that performed it and RequestedBy the client of the User Agent: the identity the Controller admitted for that client (MPAI as a Service).
4.11.3 Access
With these functions an AIM reads Access. There is no function with which an AIM writes it.
4.11.3.1 MPAI_AIFM_Access_Get
error_t MPAI_AIFM_Access_Get(const char* source, const char* key, void* data, size_t* data_length)
Retrieves the item at key in source, with the convention of 2.4.
4.11.3.2 MPAI_AIFM_Access_List
error_t MPAI_AIFM_Access_List(const char* source, const char* prefix, int* num_keys, const char** keys)
Returns the number num_keys and the vector keys of the Keys of source that begin with prefix.
4.11.3.3 MPAI_AIFM_Access_Version
error_t MPAI_AIFM_Access_Version(const char* source, int64_t* version)
Returns the current Version of source, which changes whenever its content changes.
4.12 Machine learning
The Framework supports the reliable update of AIMs with Machine Learning functionality, and hooks for Explainability.
4.12.1 MPAI_AIFM_Model_Update
error_t MPAI_AIFM_Model_Update(const char* model_name)
The URI model_name points to the updated model. The update occurs through the MPAI Store or through Storage. Where it must not impact the operation of the system, how it is effected is left to the Implementer. A model is checked against the hash its settings state before use.
4.12.2 MPAI_AIFM_Model_Drift
float MPAI_AIFM_Model_Drift(const char* AIM_name)
Detects a possible degradation of an ML operation caused by input data significantly different from those used in training.
5 Controller API called by Controller
With these functions an AIM communicates through External Ports with an AIM of a Module of the same type run by another Controller in range. An External Port is identified by controllerID, AIM_name, DataType and PortNumber, and follows 4.6 in every respect, including timeout_ms. A controllerID is valid from the MPAI_AIFM_External_List call that returned it until the Controller it names leaves range, and is not reused for another Controller within one run. A Message read from an External Port carries the stamp of the Controller that wrote it and is signed by it.
5.1 MPAI_AIFM_External_List
error_t MPAI_AIFM_External_List(int* num_in_range, const char** controllers_metadata)
Returns the number num_in_range of Controllers in range with which communication can be established and that run the same type of Module, and a vector controllers_metadata with the Metadata of the Module of each. Where a Controller runs more than one Module of the type, each is a separate element.
5.2 MPAI_AIFM_External_Probe
error_t MPAI_AIFM_External_Probe(int controllerID, const char* AIM_name,
const char* DataType, int PortNumber, int timeout_ms)
Probes an External Port, as MPAI_AIFM_Port_Probe probes a Port.
5.3 MPAI_AIFM_External_Output_Read
message_t* MPAI_AIFM_External_Output_Read(int controllerID, const char* AIM_name,
const char* DataType, int PortNumber, int timeout_ms)
Reads a Message from an External Port, waiting at most timeout_ms. The call fails if the Controller is no longer in range or the communication fails.
5.4 MPAI_AIFM_External_Input_Write
error_t MPAI_AIFM_External_Input_Write(int controllerID, const char* AIM_name,
const char* DataType, int PortNumber, message_t* message, int timeout_ms)
Writes message to an External Port, waiting at most timeout_ms. The Message shall remain available until the function returns. The call fails if the Controller is no longer in range or the communication fails.
6 Controller API called by a Provider
With these functions a Provider – a third party holding the rights to data, and wanting to be their only provider – writes a Source of Access directly, without passing through the User Agent. The Controller accepts them only on a link it admitted with the Trust Protocol, from the credential that created the Source, and only for items whose Data Exchange Metadata it verifies (Storage, 6.3).
6.1 MPAI_AIFP_Access_Create
error_t MPAI_AIFP_Access_Create(const char* source)
Creates the Source source, whose Writer the Provider becomes. Fails if the Source exists.
6.2 MPAI_AIFP_Access_Put
error_t MPAI_AIFP_Access_Put(const char* source, int64_t version, const char* key,
const void* data, size_t data_length, const char* data_exchange_metadata)
Writes data at key in source, with the Data Exchange Metadata that signs it, and makes version the Version of the Source. Returns MPAI_AIF_NOT_AUTHORISED if the caller is not the Writer of the Source, and fails if the signature does not verify or version is not higher than the current Version.
6.3 MPAI_AIFP_Access_Delete
error_t MPAI_AIFP_Access_Delete(const char* source, int64_t version, const char* key)
Removes the item at key from source and makes version the Version of the Source, under the conditions of 6.2.
