module Request:sig
..end
typejson =
Data.json
typekind =
[ `EXEC | `GET | `SET ]
module type Input =sig
..end
module type Output =sig
..end
type'a
input =(module Request.Input with type t = 'a)
type'b
output =(module Request.Output with type t = 'b)
A signal is a one-way message from server to client for indicating that something happened. To avoid unecessary noise, the client must be registered on each signal it is interested in. The client will then send a proper get requests to the server to retrieve the updated data.
As a matter of fact, update events are much more frequent than what a
typical GUI client can handle. Hence, signal emissions can not carry data and
are grouped (or « debounced ») until the next server response to client.
type
signal
val signal : page:Doc.page ->
name:string ->
descr:Markdown.text -> ?details:Markdown.block -> unit -> signal
name
must be unique.val emit : signal -> unit
val on_signal : signal -> (bool -> unit) -> unit
val register : page:Doc.page ->
kind:kind ->
name:string ->
descr:Markdown.text ->
?details:Markdown.block ->
input:'a input -> output:'b output -> ('a -> 'b) -> unit
(a -> b)
.
Name, page and kind must be consistent with each others:
`Protocol
pages"Kernel.*"
"<Plugin>.*"
"set"
(case insensitive)"get"
or "print"
(case insensitive)"exec"
or "compute"
(case insensitive)The API below allows for creating requests with named and optional parameters. Although such requests could be defined with simple registration and record datatypes, the helpers below allow more flexibility and a better correspondance between optional parameters and OCaml option types.
To register a request with named parameters and/or named results, you first create a signature. Then you define named parameters and results, and finally you register the processing function:
(* ---- Exemple of Request Registration --- *)
let () =
let s = Request.signature ~page ~kind ~name ~descr () in
let get_a = Request.param s ~name:"a" ~descr:"..." (module A) in
let get_b = Request.param s ~name:"b" ~descr:"..." (module B) in
let set_c = Request.result s ~name:"c" ~descr:"..." (module C) in
let set_d = Request.result s ~name:"d" ~descr:"..." (module D) in
Request.register_sig s
(fun rq () ->
let (c,d) = some_job (get_a rq) (get_b rq) in
set_c rq c ; set_d rq d)
type ('a, 'b)
signature
val signature : page:Doc.page ->
kind:kind ->
name:string ->
descr:Markdown.text ->
?details:Markdown.block ->
?input:'a input ->
?output:'b output -> unit -> ('a, 'b) signature
~input
and ~output
datatype are provided,
you shall define named parameters and results before registering the
request processing function.type
rq
type'a
param =rq -> 'a
type'b
result =rq -> 'b -> unit
val register_sig : ('a, 'b) signature -> (rq -> 'a -> 'b) -> unit
The functions bellow must be called on a freshly created signature before its final registration. The obtained getters and setters shall be only used within the registered process.
The correspondance between input/output JSON syntax and OCaml values is summarized in the tables below.Abstract_domain
For named input parameters:
API: Input JSON OCaml Getter
-----------------------------------------------------------------------
Request.param { f: a } 'a (* might raise an exception *)
Request.param ~default { f: a? } 'a (* defined by default *)
Request.param_opt { f: a? } 'a option
For named output parameters:
API: Input JSON OCaml Setter
----------------------------------------------------------------------
Request.result { f: a } 'a (* shall be set by process *)
Request.result ~default { f: a } 'a (* defined by default *)
Request.result_opt { f: a? } 'a option
val param : (unit, 'b) signature ->
name:string ->
descr:Markdown.text -> ?default:'a -> 'a input -> 'a param
val param_opt : (unit, 'b) signature ->
name:string ->
descr:Markdown.text -> 'a input -> 'a option param
val result : ('a, unit) signature ->
name:string ->
descr:Markdown.text -> ?default:'b -> 'b output -> 'b result
val result_opt : ('a, unit) signature ->
name:string ->
descr:Markdown.text -> 'b output -> 'b option result
None
.val dictionary : 'a Data.Enum.dictionary -> unit
GET
request dictionary.<name>
to retrieve all tags registered
in the dictionary.