Sending a request

Requests are defined in the JSON RPC 2.0 specification. For more information, see 3.2 JSON-RPC 2.0 function call format.

A request sent by the caller to the callee, and a response sent by the callee to the caller, are equivalent to a function call with a return value. The caller typically takes the following steps to complete a blocking function call:

1. The caller chooses a 32-bit request id, which it will use to match responses to requests. It puts its own instId, which is also 32 bits wide, into the top 32 bits of the request id to form the 64-bit request id that is passed with the request. This is required by the global instance to route responses back to the caller.
2. The caller encodes the JSON RPC 2.0 request object in U64JSON.
3. The caller calls irisHandleMessage() on the IrisInterface that it is connected to. This is usually provided by IrisCoreConnection for in-process instances or IrisClientConnection for out-of-process instances. This forwards the request to the callee.
4. The caller can do other work or send other requests to the same instance or to other instances.
5. The caller receives the response, which comes through the irisHandleMessage() function of the IrisInterface of the caller.

In practice, these steps are handled by a support library and the caller is not exposed to them. Requests can be sent from different threads. The caller does not have to wait for a response before sending another request. Requests can overlap. Responses can come from different threads and in any order. The caller must use the request id to match the response to a request.

Sending a notification

Notifications are defined in the JSON RPC 2.0 specification. For more information, see 3.2 JSON-RPC 2.0 function call format. Notifications are used, for example, by non-blocking, asynchronous callbacks. Sending a notification differs from sending a request in the following ways:

• The caller does not specify a request id. This also means that the caller does not send its instance id to the callee.
• The caller does not receive any response, including any error response, not even E_function_not_supported_by_instance, E_unknown_instance_id, or any low-level I/O error codes from the transport layer. This might limit the usefulness of notifications.
• The callee does not send a response.

Sending a response

Responses are defined in the JSON RPC 2.0 specification. For more information, see 3.2 JSON-RPC 2.0 function call format. After processing the request, the callee takes the following steps to send a response to the request:

1. Extracts the instId of the caller from the request id of the request.
2. Constructs a JSON RPC 2.0 response object encoded in U64JSON using the caller's instId and the original 64-bit request id.