json_rpc_client.pl -- JSON RPC client

This module implements a JSON RPC compliant client. The three predicates require a stream pair (see stream_pair/2) that connects us to a JSON RPC server.

 json_call(+Stream, +Goal, -Result, +Options) is det

Run Goal on a JSON RPC service identified by Stream and wait for Result. This predicate may be called from multiple threads. As replies come in in arbitrary order, this predicate starts a thread the reads the replies from Stream and informs the calling thread using a Prolog message queue.

If Stream is closed this library terminates the thread and related message queue.

Options are passed to json_write_dict/3 and thread_get_message/3. Additional options:

async(:Closure)

Do not wait for the request to complete. Instead, call call(Closure, Data) from the client reading thread when the request is completed. If Closure is true, ignore the reply. As we cannot inject errors as exceptions in the calling thread, possible errors are printed.

thread_alias(+Atom)

Alias name to use for the thread that deals with incomming replies and requests. Defaults to json_rpc_client:<N>, where N is a unique number.

Arguments:

Goal

- is a callable term. The functor name is the method. If there is a single argument that is a dict, we invoke a JSON-RPC method using named arguments. If there is a single argument that is a list, use the elements of the list as positional arguments. If there are zero or more than one arguments use these as positional arguments. Examples: Term Method Type JSON (params) f(#{a:1,b:2}) f named {"a":1, "b":2} f(["a", 42]) f positional ["a", 42] f([#{"a":1}]) f positional [{"a":1}] f() f positional [] f("a", 42) f positional ["a", 42] Options processed:

 json_notify(+Stream, +Goal, +Options) is det

Run Goal on a JSON RPC service identified by Stream without waiting for the result.

 json_batch(+Stream, +Notifications:list, +Calls:list, -Results:list, +Options) is det

Run a batch of notifications and normal calls on the JSON server at the other end of Stream. On success, Result is unified to a list with the same length as Calls. Each element either contains a value, similar to json_call/4 or a term error(Dict), where Dict holds the code, message and optional data field. Note that error(Dict) is not a valid JSON type and this is thus unambiguous. While the JSON RPC standard allows the server to process the messages in any order and allows for concurrent processing, all results are sent in one message and this client ensures the elements of the Results list are in the same order as the Calls list. If the Calls list is empty this predicate does not wait for a reply.

 json_full_duplex(+Stream, :Options) is det

Start the thread for incomming data and on requests, dispatch them using library(jso_rpc_server) in the module derived from the Options list.

 get_json_result_queue(+Stream, -Queue, +Options) is det[private]

Find the result queue associated to Stream. If this does not exist, create one, as well as a thread that handles the incomming results and dispatches these to the queue.

 cleanup_client(+Stream) is det[private]

Thread exit handler to remove the registration and queue.