Module Server.RequestSource

Request Registry

Sourcetype json = Data.json
Sourcetype kind = [
  1. | `GET
  2. | `SET
  3. | `EXEC
]
Sourcemodule type Input = sig ... end
Sourcemodule type Output = sig ... end
Sourcetype 'a input = (module Input with type t = 'a)
Sourcetype 'b output = (module Output with type t = 'b)

Signals

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.

Sourcetype signal

The type of registered signals.

Sourceval signal : package:Package.package -> name:string -> descr:Frama_c_kernel.Markdown.text -> signal

Register a server signal. The signal name must be unique.

Sourceval emit : signal -> unit

Emit the signal to the client.

Sourceval on_signal : signal -> (bool -> unit) -> unit

Callback invoked each time the client is starting or stopping to listen to the given signal.

Simple Requests Registration

Sourceval register : package:Package.package -> kind:kind -> name:string -> descr:Frama_c_kernel.Markdown.text -> ?signals:signal list -> input:'a input -> output:'b output -> ('a -> 'b) -> unit

Register a simple request of type (a -> b) which depends on the given signals

Name, page and kind must be consistent with each others:

  • No publication on `Protocol pages
  • Kernel requests shall starts with "Kernel.*"
  • Plugin requests shall starts with "<Plugin>.*"
  • SET requests must contain "set" (case insensitive)
  • GET requests must contain "get" or "print" (case insensitive)
  • EXEC requests must contain "exec" or "compute" (case insensitive)

Requests with Named Parameters

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 () 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 ~package ~kind ~name ~descr
      (fun rq () ->
         let (c,d) = some_job (get_a rq) (get_b rq) in
         set_c rq c ; set_d rq d)
Sourcetype ('a, 'b) signature

Under definition request signature.

Sourceval signature : ?input:'a input -> ?output:'b output -> unit -> ('a, 'b) signature

Create an opened request signature. Depending on whether ~input and ~output datatype are provided, you shall define named parameters and results before registering the request processing function.

Sourcetype rq

Request JSON parameters.

Sourcetype 'a param = rq -> 'a

Named input parameter.

Sourcetype 'b result = rq -> 'b -> unit

Named output parameter.

Sourceval register_sig : package:Package.package -> kind:kind -> name:string -> descr:Frama_c_kernel.Markdown.text -> ?signals:signal list -> ('a, 'b) signature -> (rq -> 'a -> 'b) -> unit

Register the request JSON processing function. This call finalize the signature definition and shall be called once on the signature.

Named Parameters and Results

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

Sourceval param : (unit, 'b) signature -> name:string -> descr:Frama_c_kernel.Markdown.text -> ?default:'a -> 'a input -> 'a param

Named input parameter. If a default value is provided, the JSON input field becomes optional. Otherwized, it is required.

Sourceval param_opt : (unit, 'b) signature -> name:string -> descr:Frama_c_kernel.Markdown.text -> 'a input -> 'a option param

Named optional input parameter.

Sourceval result : ('a, unit) signature -> name:string -> descr:Frama_c_kernel.Markdown.text -> ?default:'b -> 'b output -> 'b result

Named output parameter. If a default value is provided, the JSON output field is initialized with it. Otherwise, it shall be set at each invocation of the request processing funciton.

Sourceval result_opt : ('a, unit) signature -> name:string -> descr:Frama_c_kernel.Markdown.text -> 'b output -> 'b option result

Named optional output parameter. The initial value is set to None.

Exporting Dictionaries

Sourceval dictionary : package:Package.package -> name:string -> descr:Frama_c_kernel.Markdown.text -> 'a Data.Enum.dictionary -> (module Data.S with type t = 'a)

Register a GET request dictionary.<name> to retrieve all tags registered in the dictionary.