In many RPC situations, synchronization between the two communicating endpoints is a matter of correctly designing the RPC application: when synchronization is needed, requests (which are blocking) should be used; when it isn’t, notifications should suffice. However, when Emacs acts as one of these endpoints, asynchronous events (e.g. timer- or process-related) may be triggered while there is still uncertainty about the state of the remote endpoint. Furthermore, acting on these events may only sometimes demand synchronization, depending on the event’s specific nature.
The :deferred
keyword argument to jsonrpc-request
and
jsonrpc-async-request
is designed to let the caller indicate
that the specific request needs synchronization and its actual
issuance may be delayed to the future, until some condition is
satisfied. Specifying :deferred
for a request doesn’t mean it
will be delayed, only that it can be. If the request
isn’t sent immediately, jsonrpc
will make renewed efforts to
send it at certain key times during communication, such as when
receiving or sending other messages to the endpoint.
Before any attempt to send the request, the application-specific
conditions are checked. Since the jsonrpc
library can’t know
what these conditions are, the program can use the
jsonrpc-connection-ready-p
generic function (see Generic Functions) to specify them. The default method for this function
returns t
, but you can add overriding methods that return
nil
in some situations, based on the arguments passed to it,
which are the jsonrpc-connection
object (see Overview) and whichever value you passed as the :deferred
keyword argument.