Module Hydro_types


module Hydro_types: sig .. end
Basic type and exception definitions


Exceptions



These are the base exceptions of the runtime. Note that user code usually does not get them directly because they are wrapped into the Client_condition exception. E.g. user code could get Client_condition(`Connect_error(Proxy_error(`NoEndpointIsReachable))).

For technical reasons, Client_condition is defined below.

type protocol_violation = [ `BadMessageType
| `CompressionNotSupported
| `MessageFormatViolation of string ]
exception Protocol_violation of protocol_violation
A violation of the protocol has been detected:
exception Marshal_error of string
A value cannot be marshalled, i.e. converted into the string format that is sent over the wire. The argument explains the reason.
exception Unmarshal_error of string
A received message cannot be decoded into a value. The argument explains the reason.
type limitation = [ `UnsupportedEncodingVersion
| `UnsupportedEndpointType of int
| `UnsupportedProtocolVersion ]
exception Limitation of limitation
A Hydro limitation was hit:
type proxy_error = [ `NoCallableEndpointFound
| `NoEndpointIsReachable
| `NoLocatorIsReachable
| `ProxyIsDown ]
exception Proxy_error of proxy_error
The proxy is unable to fulfill the request:
exception Domain_not_found of string
A DNS name cannot be resolved. The argument is the name
exception Unbound_exception of exn
An exception that has not to be caught by a exception handler built into Hydro. Such exceptions always fall through to the user code.
exception Unimplemented_operation of string
This operation was called, but the actual definition is missing

See also the exception Client_condition below!

Values



This defines value, the abstract (non-mapped) representation of values that can be sent over the wire. value is mostly internally used, because hydrogen generates a user-friendlier representation of values that uses directly OCaml types.
type noreturn 
A type without value. May be used to indicate that functions or methods never return normally to the caller.

type value =
| VNothing
| VBool of bool
| VByte of int
| VShort of int
| VInt of int
| VInt32 of int32
| VLong of int64
| VFloat of float
| VDouble of float
| VString of string
| VSequence of value array
| VByteseq of string
| VDictionary of (value * value) array
| VEnum of int
| VStruct of value array
| VNull
| VClass of class_repr Pervasives.ref
| VProxy of proxy_addr
| VDirectWriter of (Netbuffer.t -> unit)
| VDirectMapping of exn
This is mostly clear: e.g. VLong n represents a value that is declared as "long" in the Ice IDL file. Some remarks:
type class_repr = [ `Placeholder of int32 | `Value of object_value ] 
type sliced_value = < hydro_effective_id : string; hydro_slices : slice list > 
Sliced values are used to marshal exceptions and object instances. For these there is an inheritance hierarchy. This type also exists as class type Hydro_lm.sliced_base.
type object_value = < hydro_effective_id : string;
hydro_inflate : string -> noreturn;
hydro_invoke_operation : string ->
value array ->
session -> unit;
hydro_slices : slice list >
Object values are subtypes of sliced_value. Additional methods: Basically this means that an object_value is a sliced_value that can be recovered as rich class type by the language mapping layer.

For an object_value that has callable operations, use the class type Hydro_lm.object_base.

type slice = [ `Decoded of string * value array | `Opaque of string * string ] 
It is possible that the ID of a slice is known or not. In the first case Hydro represents it as `Decoded(id,values) where id is the type ID of the slice, and values are the decoded values in order. If Hydro does not know the type ID, the slice is represented as `Opaque(id,values), and the values remain unmarshalled. It is still possible to forward an opaque value to another Ice node.
type proxy_addr = < facet : string option; id : identity;
mode : proxy_mode; parameters : proxy_parameters;
secure : bool >
The address of a remote object (for creating a proxy):
type proxy_mode = [ `Batch_datagram | `Batch_oneway | `Datagram | `Oneway | `Twoway ] 
type proxy_parameters = [ `Adapter of string | `Endpoints of endpoint array | `Well_known ] 
Where to find the Internet port(s) of the service behind the proxy:
type endpoint = [ `SSL of ssl_endpoint
| `TCP of tcp_endpoint
| `UDP of udp_endpoint
| `Unknown of int * string ]
type endpoint_type = [ `SSL | `TCP | `UDP | `Unknown of int ] 
type tcp_endpoint = < compress : bool; host : string; port : int; timeout : int32 > 
type udp_endpoint = < compress : bool; enc_major : int; enc_minor : int; host : string;
port : int; proto_major : int; proto_minor : int >
type ssl_endpoint = tcp_endpoint 
type identity = < category : string; name : string > 
The identity of a remote object

Type system



type htype =
| TVoid
| TBool
| TByte
| TShort
| TInt
| TInt32
| TLong
| TFloat
| TDouble
| TString
| TByteseq
| TEnum of string array
| TStruct of (string * htype) array
| TSequence of htype
| TDictionary of htype * htype
| TProxy of string
| TClass of string
| TDirectMapping of htype * (Netbuffer.t -> exn -> unit)
* (string -> int Pervasives.ref -> int -> exn)
type hexn = < elements : (string * htype) array; name : string;
super : hexn option >
type hintf = < elements : hfunction list; name : string;
super : hintf list >
type hfunction = < in_args : (string * htype) array; in_classes : bool;
mode : op_mode; name : string;
out_args : (string * htype) array; out_classes : bool;
result : htype >
type hclass = < elements : (string * htype) array; name : string;
super : hclass option >
type system = < classes : hclass Hydro_prelim.CiHashtbl.t;
ctors : (sliced_value -> object_value)
Hydro_prelim.CiHashtbl.t;
exceptions : hexn Hydro_prelim.CiHashtbl.t;
interfaces : hintf Hydro_prelim.CiHashtbl.t;
types : htype Hydro_prelim.CiHashtbl.t >
type op_mode = [ `Idempotent | `Nonmutating | `Normal ] 

Messages


type msg_type = [ `Batch_request
| `Close_connection
| `Reply
| `Request
| `Validate_connection ]
type compression_status = [ `Compressed | `Compression_unsupported | `Uncompressed ] 
type msg_header = < body_size : int; compression : compression_status;
enc_major : int; enc_minor : int; msg_type : msg_type;
proto_major : int; proto_minor : int >

type encap_buffer = {
   encap_buf : Netbuffer.t;
   encap_pos : int;
   encap_len : int;
   encap_enc_minor : int;
}
type msg_buffer = msg_header * encap_buffer list 
type msg = [ `Batch_request of batch_request_msg list
| `Close_connection
| `Reply of reply_msg
| `Request of request_msg
| `Validate_connection ]
type request_msg = < context : (string * string) array; facet : string option;
id : identity; mode : op_mode; operation :
string; params : encap_buffer; request_id : int32 >
type batch_request_msg = < context : (string * string) array; facet : string option;
id : identity; mode : op_mode; operation :
string; params : encap_buffer >
type reply_msg = < request_id : int32; result : result > 
type result = [ `Facet_does_not_exist of identity * string option * string
| `Object_does_not_exist of identity * string option * string
| `Operation_does_not_exist of identity * string option * string
| `Success of encap_buffer
| `Unknown_exception of string
| `Unknown_local_exception of string
| `Unknown_user_exception of string
| `User_exception of encap_buffer ]

Parameters



See the Hydro_params module for creating and modifying these objects
type call_params = < context : (string * string) list option;
destination : Unix.sockaddr option; msg_timeout : float option >
Parameters for a single call:
type exn_handler = < handle : exn -> unit > 
An exception handler encapsulated as object
type client_params = < exception_handler : exn_handler; idle_timeout : float;
max_enc_minor : int option; max_proto_minor : int option;
msg_timeout : float; trans_timeout : float >
Parameters for clients:
type server_params = < trans_timeout : float > 

Serving


type server_ops = < abort_connection : unit -> unit; endpoint : endpoint;
event_system : Unixqueue.event_system; server_id : int;
server_params : server_params;
shutdown_connection : unit -> unit; system : system >
- endpoint returns the endpoint name where this server is reachable by remote proxies
type session = < context : (string * string) list;
emit_result : value -> value array -> unit;
emit_unknown_exception : string -> unit;
emit_unknown_local_exception : string -> unit;
emit_unknown_user_exception : string -> unit;
emit_user_exception : sliced_value -> unit;
is_responded : bool; request_id : int32;
response : reply_msg option;
server_ops : server_ops >
- is_responded is true when a response has been sent, or when a response can no longer be sent, and false when a response is still expected
type operation_dispatcher = < hydro_effective_id : string;
hydro_invoke_operation : string ->
value array ->
session -> unit >
If you get Not_found after only passing the operation name to hydro_invoke_operation the operation does not exist.
type facet_dispatcher = < invoke_facet : string option -> operation_dispatcher > 
type object_dispatcher = < adapter_id : string option;
get_identity : operation_dispatcher -> identity;
invoke_object : identity -> facet_dispatcher;
replica_group_id : string option >
The invoke_object method either returns the next dispatcher, or raises Not_found. In the scope of a single object dispatcher we require that the mapping between identity and facet dispatcher is bijective, so there is also get_identity for the reverse mapping.

Client Exceptions


type client_condition = [ `Client_is_down
| `Connect_error of exn
| `Connect_timeout
| `Error of exn
| `Facet_does_not_exist of identity * string option * string
| `Message_lost of bool
| `Message_timeout
| `Object_does_not_exist of identity * string option * string
| `Operation_does_not_exist of identity * string option * string
| `Transport_timeout
| `Unknown_exception of string
| `Unknown_local_exception of string
| `Unknown_user_exception of string
| `User_exception of sliced_value ]
exception Client_condition of client_condition
These conditions may be passed back to the caller of a RPC function:

Miscelleneous


type transport_protocol_type = [ `Datagram | `Stream ] 
class type descriptor = object .. end
type network_port = [ `TCP of Unix.inet_addr * int | `UDP of Unix.inet_addr * int ]