Ocamlnet 4 Reference Manual : Rpc_netplex

# Module Rpc_netplex

    module Rpc_netplex: sig .. end

Netplex support for RPC servers (TCP only)

    val rpc_factory : configure:(Netplex_types.config_file -> Netplex_types.address -> 'a) ->
           ?socket_config:('a -> Rpc_server.socket_config) ->
           ?hooks:('a -> Netplex_types.processor_hooks) ->
           ?supported_ptypes:Netplex_types.parallelization_type list ->
           name:string ->
           setup:(Rpc_server.t -> 'a -> unit) -> unit -> Netplex_types.processor_factory

A factory for TCP-based RPC servers. In `name` the name of the processor is defined. This name can be referenced from the config file like:

        processor {
            type = "the passed [name]";
            ...
        }

Parameters may be included in the `processor` section:

- `portmapper`: This is a boolean parameter. If set to true, the Internet port is registered with the portmapper program. This will fail if there are several Internet bindings with distinct port numbers!
- `timeout`: This is a float parameter. It sets the transport timeout of the RPC server (see `Rpc_server.set_timeout`). If a connection hangs for this number of seconds, it is shut down by the server.

Further parameters and subsections can be defined by the user. These parameters should be parsed and checked for correctness by the `configure` callback. The result of `configure` is also passed to `setup` and other optional functions. The `configure` function is called just before the service is added to Netplex (i.e. from the controller context).

The return value of `configure` can be of any type. This value exists once for every time the processor is instantiated (used) by a service. It is not only useful for passing configuration values down, but also for storing intermediate results while establishing the service.

The `Rpc_server.t` structure is created every time a new connection is accepted. Of course, this is done from the context of the container. The `Rpc_server.t` is created without any binding; the user must bind procedures in the `setup` function. This can be done by calling `Rpc_server.bind` or the ocamlrpcgen-generated function (by the `-srv2` switch of ocamlrpcgen).

For example, a minimal factory for an RPC service may look like:

       let proc_ping () = ()     (* Trivial RPC procedure *)

       let my_factory() =
         Rpc_netplex.rpc_factory
           ~name:"my_rpc_service"
           ~factory:(fun _ _ -> ())
           ~setup:(fun rpc () ->
                     My_rpc_srv.bind ~proc_ping rpc
                  )
           ()

The `setup` function is also called once before a new connection is accepted to get a list of programs and procedures. The `Rpc_server.t` is a special one in this case, and one can test for it with the `Rpc_server.is_dummy` function.

`socket_config` : An optional function computing the socket configuration. By default, `Rpc_server.default_socket_config` is used. Special socket configuration would, for example, allow SSL.
`hooks` : An optional function returning the hooks to call. See `Netplex_types.processor_hooks` for documentation.
`supported_ptypes` : Which parallelization types are supported by the service. By default, both multi-processing and multi-threading are included in this list.

    val debug_rpc_internals : bool Pervasives.ref

    val debug_rpc_service : bool Pervasives.ref

These variables control debugging of `Rpc_server`. If set, the debug messages are sent to the Netplex logger. These variables must be set before an RPC connection is accepted.