Module Netplex_sharedvar

module Netplex_sharedvar: sig .. end

---

This plugin allows to have Netplex-global variables that can be read and written by all components. These variables are useful to communicate names and other small pieces of information across the whole Netplex. For instance, one component could allocate a shared memory object, and put its name into a variable to make it known to other components.

This implementation works in both multi-processing and multi-threading netplex environments. It is, however, not very fast, because the variables live in the controller, and the access operations are realized by RPC's. It is good enough when these operations are only infrequently called, e.g. in the post-start and pre-finish processor callbacks.

Furthermore, note that it is unwise to put large values into variables when using them in multi-processing contexts. The controller process is also the parent process of all forked children, and when a lot of memory is allocated in the controller, all this memory needs to be copied when the fork is done. As workaround, put such values into temporary files, and only pass the names of the files around via variables.

Variables come in two flavors:

• String variables
• Encapsulated variables (see Netplex_encap)

A string variable cannot be accessed as encapsulated variable, and vice versa.

The latter kind is useful to safely store structured ocaml values in Netplex variables.

More documentation can also be found here: Storing global state

Thread safety: Full. The functions can be called from any thread.

exception Sharedvar_type_mismatch of string

exception Sharedvar_no_permission of string

exception Sharedvar_not_found of string

exception Sharedvar_null

val plugin : Netplex_types.plugin

Classical API

Most of the folloing functions can be invoked in both container and controller contexts, with the notable exception of wait_for_value.

val create_var : ?own:bool ->
       ?ro:bool -> ?enc:bool -> ?timeout:float -> ?ssn:string -> string -> bool

val delete_var : string -> bool

val set_value : string -> string -> bool

val set_enc_value : string -> Netplex_types.encap -> bool

val get_value : string -> string option

val get_enc_value : string -> Netplex_types.encap option

val wait_for_value : string -> string option

val wait_for_enc_value : string -> Netplex_types.encap option

val get_lazily : string -> (unit -> string) -> string option

val get_enc_lazily : string -> (unit -> Netplex_types.encap) -> Netplex_types.encap option

val dump : string -> Netlog.level -> unit

API with versioned access

The API with versioned values can very quickly check whether newer values are available (the check consists just of a memory read). If a newer version is avaiable, the value still needs to be retrieved with an RPC call, though.

The central function is vv_update. See also the limitations mentioned there.

type 'a versioned_value 

val vv_access : string -> string versioned_value

val vv_access_enc : string -> Netplex_types.encap versioned_value

val vv_get : 'a versioned_value -> 'a option

val vv_version : 'a versioned_value -> int64

val vv_update : 'a versioned_value -> bool

val vv_set : 'a versioned_value -> 'a -> bool

Classical functor

module Make_var_type: 

Functor with versioned access

module type VV_TYPE = sig .. end

module Make_vv: 

Netsys_global

This is a propagator for Netsys_global. It is automatically activated when the Netplex controller is started.

val global_propagator : unit -> Netsys_global.propagator

val propagate_back : Netplex_types.controller -> unit

Examples

Example code:

Here, one randomly chosen container computes precious_value, and makes it available to all others, so the other container can simply grab the value. This is similar to what get_lazily does internally:

      let get_precious_value() =
        let container = Netplex_cenv.self_cont() in
        let var_name = "my_service.precious" in
        if Netplex_sharedvar.create_var var_name then (
          let precious_value = 
            try ...    (* some costly computation *)
            with exn ->
              ignore(Netplex_sharedvar.delete_var var_name);
              raise exn in
          let b = Netplex_sharedvar.set_value var_name precious_value in
          assert b;
          precious_value
        )
        else (
          match Netplex_sharedvar.wait_for_value var_name with
           | Some v -> v
           | None -> failwith "get_precious_value"
                       (* or do plan B, e.g. compute the value *)
        )
    

We don't do anything here for deleting the value when it is no longer needed. Finding a criterion for that is very application-specific. If the variable can be thought as being another service endpoint of a socket service, it is a good idea to acquire the ownership (by passing ~own:true to create_var), so the variable is automatically deleted when the socket service stops.

Of course, the plugin must be enabled, e.g. by overriding the post_add_hook processor hook:

 
    method post_add_hook sockserv ctrl =
      ctrl # add_plugin Netplex_sharedvar.plugin
   

This web site is published by Informatikbüro Gerd Stolpmann