|Home > Generic function call interface > JSON-RPC 2.0 function call format|
Iris interfaces use the JSON-RPC 2.0 format and semantics for function calls and responses.
JSON-RPC 2.0 is a lightweight Remote Procedure Call (RPC) mechanism that is easy to understand and implement.
In this documentation, the terms request, notification, and response refer to the Request, Notification, and Response Objects that are defined by JSON-RPC 2.0, see http://www.jsonrpc.org/specification.
All functions are called by name, and responses are associated with requests by using a request id, which the caller assigns to the request.
The JSON-RPC 2.0 standard supports various use patterns. For example, it supports argument passing by position or by name. Iris uses the following subset of, and extensions to, JSON-RPC 2.0:
Function arguments are passed by name, not by position.
In other words,
params is an object,
not an array. The order of the arguments in the Iris API documentation
When manually generating JSON or U64JSON requests, you can order function arguments alphabetically by name to speed up function call processing.
The request id that is passed to a function call is a NumberU64. The caller specifies bits[31:0] of the request id. This allows the caller to match function return values with function calls. It is usually an integer that increases with every request. This increasing id can wrap around, but ids of ongoing function calls must not be reused. There is no requirement to use an increasing id or even unique ids.
instId argument specifies the instance that the function operates on, similar to a
this pointer in C++. For more information about
instId, see 4.2 Instances. The caller must set bits[63:32] of the request id to the instance id,
instId, of the caller. This part of the id is used to route responses back to the caller. The usage of bits[63:32] is an Iris-specific extension of JSON RPC 2.0 to support the Iris Object Model. For more information about the Object Model, see Chapter 4 Object model
All Iris functions can be sent either as a request or as a notification, unless otherwise stated in the API documentation:
All strings, including object member names, are encoded using UTF-8. All Iris function names, function argument names, and object member names are plain ASCII and are C identifiers. Iris does not use String to transport binary data, because String cannot represent all binary byte sequences. For example, Strings cannot contain NUL bytes.
The following are case sensitive:
Functions can generally be called in both directions between two instances.
Iris does not support batch requests or batch responses, in other words, arrays of requests or arrays of responses. Independent function calls to independent instances do not map well onto the batch requests and batch responses as defined in JSON-RPC 2.0. However, IrisRpc uses persistent TCP connections, and sending individual requests has almost the same performance as sending them in an array as a batch request.