polling_state_rpc v0.17.0 (latest)

module type Response = sig ... end

This is a subset of the diffable signature (without to_diffs and of_diffs) and with the diffable type also supporting bin_io

type ('query, 'response) t

The type representing the RPC itself. Similar to Rpc.Rpc.t and its friends.

val name : ('query, 'response) t -> string

val version : ('query, 'response) t -> int

val babel_generic_rpc : (_, _) t -> Babel.Generic_rpc.t

val create : 
  name:string ->
  version:int ->
  query_equal:('query -> 'query -> bool) ->
  bin_query:'query Core.Bin_prot.Type_class.t ->
  (module Response with type t = 'response) ->
  ('query, 'response) t

val implement : 
  on_client_and_server_out_of_sync:(Core.Sexp.t -> unit) ->
  ?for_first_request:
    ('connection_state -> 'query -> 'response Async_kernel.Deferred.t) ->
  ('query, 'response) t ->
  ('connection_state -> 'query -> 'response Async_kernel.Deferred.t) ->
  ('connection_state * Async_rpc_kernel.Rpc.Connection.t)
    Async_rpc_kernel.Rpc.Implementation.t

Handling the first request and handling the remaining requests is different because the first request you likely want to compute immediately, but for subsequent requests, it's more likely that you'll want to block until your data store changes and updates are made available.

val implement_with_client_state : 
  on_client_and_server_out_of_sync:(Core.Sexp.t -> unit) ->
  create_client_state:('connection_state -> 'client_state) ->
  ?on_client_forgotten:('client_state -> unit) ->
  ?for_first_request:
    ('connection_state ->
      'client_state ->
      'query ->
      'response Async_kernel.Deferred.t) ->
  ('query, 'response) t ->
  ('connection_state ->
    'client_state ->
    'query ->
    'response Async_kernel.Deferred.t) ->
  ('connection_state * Async_rpc_kernel.Rpc.Connection.t)
    Async_rpc_kernel.Rpc.Implementation.t

Similar to implement, but with support for per-client state. This allows you to support multiple clients, each with different server-side state, that share a single Rpc.Connection.t.

Note that, similar to the connection state, the client state cannot be shared between multiple connections - if a client reconnects after disconnecting, it will be given a new client state.

on_client_forgotten is called when the client calls Client.forget_on_server, or when the underlying connection is closed.

val implement_via_bus : 
  on_client_and_server_out_of_sync:(Core.Sexp.t -> unit) ->
  create_client_state:('connection_state -> 'client_state) ->
  ?on_client_forgotten:('client_state -> unit) ->
  ('query, 'response) t ->
  ('connection_state ->
    'client_state ->
    'query ->
    ('response -> unit, [> Core.read ]) Bus.t Async_kernel.Deferred.t) ->
  ('connection_state * Async_rpc_kernel.Rpc.Connection.t)
    Async_rpc_kernel.Rpc.Implementation.t

Like implement, except the callback is invoked only once per query, and must return a bus instead of a single result. Each time a client polls, it will receive the newest response that it has not yet seen. If it has seen the newest response, then the RPC implementation will block until there is a newer response.

This function immediately subscribes to the returned bus and cancels any previous subscriptions each time it invokes the callback. It is recommended that the bus use Allow_and_send_last_value, so that each new query doesn't miss the first response for each query (or even raise, if on_subscription_after_first_write is set to Raise).

val implement_via_bus' : 
  on_client_and_server_out_of_sync:(Core.Sexp.t -> unit) ->
  create_client_state:('connection_state -> 'client_state) ->
  ?on_client_forgotten:('client_state -> unit) ->
  ('query, 'response) t ->
  ('connection_state ->
    'client_state ->
    'query ->
    ('response -> unit, [> Core.read ]) Bus.t) ->
  ('connection_state * Async_rpc_kernel.Rpc.Connection.t)
    Async_rpc_kernel.Rpc.Implementation.t

Like implement_via_bus, except that the callback does not return a deferred.

implement_via_bus' will call Bus.subscribe immediately after the callback returns. When the client is no longer polling for the given query, this will call Bus.unsubscribe', meaning that Bus.num_subscribers will count the client as a subscriber iff the client is still polling for this query.

module Client : sig ... end

module Private_for_testing : sig ... end

package polling_state_rpc