module Hydro_types:Basic type and exception definitionssig
..end
Client_condition
exception. E.g. user code could get
Client_condition(`Connect_error(Proxy_error(`NoEndpointIsReachable)))
.
For technical reasons, Client_condition
is defined below.
typeprotocol_violation =
[ `BadMessageType
| `CompressionNotSupported
| `MessageFormatViolation of string ]
exception Protocol_violation of protocol_violation
`MessageFormatViolation reason
: The data received over the wire
cannot be even split into messages. reason
explains why.`CompressionNotSupported
: A compressed message was received
although Hydro announces that it does not support compression.`BadMessageType
: XXXexception Marshal_error of string
exception Unmarshal_error of string
typelimitation =
[ `UnsupportedEncodingVersion
| `UnsupportedEndpointType of int
| `UnsupportedProtocolVersion ]
exception Limitation of limitation
`UnsupportedEncodingVersion
: Hydro only understands version 1.0`UnsupportedProtocolVersion
: Hydro only understands version 1.0typeproxy_error =
[ `NoCallableEndpointFound
| `NoEndpointIsReachable
| `NoLocatorIsReachable
| `ProxyIsDown ]
exception Proxy_error of proxy_error
`NoCallableEndpointFound
: After the endpoint resolution procedure
no endpoint turns out to be usable. Note that also DNS failures
can lead to this error.`NoEndpointIsReachable
: None of the resolved endpoints is
actually reachable.`NoLocatorIsReachable
: No locator (i.e. IceGrid node) is
actually reachable, and the resolution procedure fails because of
this.`ProxyIsDown
: The proxy has been shut downexception Domain_not_found of string
exception Unbound_exception of exn
exception Unimplemented_operation of string
Client_condition
below!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
typevalue =
[ `Bool of bool
| `Byte of int
| `Byteseq of string
| `Class of class_repr Pervasives.ref
| `Dictionary of (value * value) array
| `DirectWriter of Netbuffer.t -> unit
| `Double of float
| `Enum of int
| `Float of float
| `Int of int
| `Int32 of int32
| `Long of int64
| `Nothing
| `Null
| `Proxy of proxy_addr
| `Sequence of value array
| `Short of int
| `String of string
| `Struct of value array ]
`Long n
represents a value that is declared
as "long" in the Ice IDL file. Some remarks:`Nothing
is the fictive value for `Void
types (think of ()
in
OCaml)`Int n
and `Int32 n
,
so the user can select which representation to prefer`Float f
means that f
is only single-precision, although the
OCaml float
type corresponds to double-precision floats.`Byteseq s
is used for values of sequence<byte>
Ice type.`Enum k
: The number k
is the position in the declaration.`Class cls_ref
: We use a reference as argument to simply the
unmarshalling algorithm. User code should never see `Placeholder
inside this reference, but only `Value
.typeclass_repr =
[ `Placeholder of int32 | `Value of object_value ]
typesliced_value =
< hydro_effective_id : string; hydro_slices : slice list >
hydro_slices
: These are the slices in base-to-derived order,
i.e. the root slice for the root of the inheritance hierarchy
comes first, and the most derived slice comes last.hydro_effective_id
: The effective type ID of the class or
exception. This is the most derived ID the local type system
knows = the latest element in hydro_slices
with a decoded slice.Hydro_lm.sliced_base
.typeobject_value =
< hydro_effective_id : string;
hydro_inflate : string -> noreturn;
hydro_invoke_operation : string ->
value array ->
session -> unit;
hydro_slices : slice list >
sliced_value
. Additional
methods:hydro_inflate id
: Used in the language-mapping layer to restore
the full object type for the object_value
. This is done by
calling hydro_inflate
with the class id
of the desired class.
The method in turn raises a special exception E obj
that has to be caught by the caller in order to get obj
.
The argument obj
is the object itself, but with a richer type
that corresponds to id
.hydro_invoke_operation name args sess
: invoke the operation
name
(always passed in lowercase letters) with arguments args
and session sess
.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
.
typeslice =
[ `Decoded of string * value array | `Opaque of string * string ]
`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.typeproxy_addr =
< facet : string option; id : identity;
mode : proxy_mode; parameters : proxy_parameters;
secure : bool >
id
is the identity of the remote objectfacet
is the facet if anymode
is the mode of the proxysecure
may demand that only SSL endpoints are chose in order
to access the remote objectparameters
denotes the endpoint(s) where the object is reachable
in a transport-dependent formtypeproxy_mode =
[ `Batch_datagram | `Batch_oneway | `Datagram | `Oneway | `Twoway ]
typeproxy_parameters =
[ `Endpoints of endpoint array | `Indirect of string ]
typeendpoint =
[ `SSL of ssl_endpoint
| `TCP of tcp_endpoint
| `UDP of udp_endpoint
| `Unknown of int * string ]
typeendpoint_type =
[ `SSL | `TCP | `UDP | `Unknown of int ]
typetcp_endpoint =
< compress : bool; host : string; port : int; timeout : int32 >
typeudp_endpoint =
< compress : bool; enc_major : int; enc_minor : int; host : string;
port : int; proto_major : int; proto_minor : int >
typessl_endpoint =
tcp_endpoint
typeidentity =
< category : string; name : string >
typehtype =
[ `Bool
| `Byte
| `Byteseq
| `Class of string
| `Dictionary of htype * htype
| `Double
| `Enum of string array
| `Float
| `Int
| `Int32
| `Long
| `Proxy of string
| `Sequence of htype
| `Short
| `String
| `Struct of (string * htype) array
| `Void ]
typehexn =
< elements : (string * htype) array; name : string;
super : hexn option >
typehintf =
< elements : hfunction list; name : string;
super : hintf list >
typehfunction =
< in_args : (string * htype) array; in_classes : bool;
mode : op_mode; name : string;
out_args : (string * htype) array; out_classes : bool;
result : htype >
typehclass =
< elements : (string * htype) array; name : string;
super : hclass option >
typesystem =
< 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 >
typeop_mode =
[ `Idempotent | `Nonmutating | `Normal ]
typemsg_type =
[ `Batch_request
| `Close_connection
| `Reply
| `Request
| `Validate_connection ]
typecompression_status =
[ `Compressed | `Compression_unsupported | `Uncompressed ]
typemsg_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 : |
|
encap_pos : |
|
encap_len : |
|
encap_enc_minor : |
typemsg_buffer =
msg_header * encap_buffer list
typemsg =
[ `Batch_request of batch_request_msg list
| `Close_connection
| `Reply of reply_msg
| `Request of request_msg
| `Validate_connection ]
typerequest_msg =
< context : (string * string) array; facet : string option;
id : identity; mode : op_mode; operation :
string; params : encap_buffer; request_id : int32 >
typebatch_request_msg =
< context : (string * string) array; facet : string option;
id : identity; mode : op_mode; operation :
string; params : encap_buffer >
typereply_msg =
< request_id : int32; result : result >
typeresult =
[ `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 ]
Hydro_params
module for creating and modifying these
objectstypecall_params =
< context : (string * string) list option;
destination : Unix.sockaddr option; msg_timeout : float option >
msg_timeout
: If Some tmo
, the number tmo
is the maximum
number of seconds until when a response must have been arrived.
Otherwise the call times out with a
Client_condition `Message_timeout
. If None
, there is no
such timeout condition. (Only used for twoway calls.)destination
: For unconnected UDP sockets, this parameter must
be Some addr
to set the destination of the call. For connected
sockets this parameter must be None
.context
: If Some ctx
, the key/value pairs in ctx
are to
be passed as context. If None
a reasonable default is passed.typeexn_handler =
< handle : exn -> unit >
typeclient_params =
< exception_handler : exn_handler; idle_timeout : float;
max_enc_minor : int option; max_proto_minor : int option;
msg_timeout : float; trans_timeout : float >
trans_timeout
: If non-negative, a timeout on the transport
level is set. This means that connections that block for more
than this number of seconds time out. In this case, the whole
client fails, and all pending calls see a
Client_condition `Transport_timeout
if it happens in the middle
of a connection, or Client_condition `Connect_timeout
if it
happens in the connect phase.msg_timeout
: If non-negative, the number tmo
is the maximum
number of seconds until when a response must have been arrived.
Otherwise the call times out with a
Client_condition `Message_timeout
. This error is non-fatal,
and only the single call times out. (Only used for twoway calls.)idle_timeout
: when the client has been idle for this number of
seconds, it is automatically shut down. "Idle" means that there is
neither something to send nor a message is expected to be received.exception_handler
is invoked for exceptions that cannot be handled
by the client. The handler is never invoked for Unbound_exception
s -
these always fall through to the caller. In any case the client is shut
down for exceptions that cannot be handled by the client.max_proto_minor
and max_enc_minor
are the maximum minor versions
of the server. These values are only used in the datagram case; for
stream connections they can be obtained directly from the server.
If not set, minor numbers of 0 are assumed.typeserver_params =
< trans_timeout : float >
typeserver_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 proxiesshutdown_connection
initiates the shutdown of the connection
for connection-oriented servers (nothing is done for connection-less
servers)abort_connection
closes the connection immediately
for connection-oriented servers (nothing is done for connection-less
servers)event_system
is the Unixqueue the server is usingsystem
is the type systemserver_params
are the server parametersserver_id
identifies the connection for connection-oriented
servers, otherwise just the servertypesession =
< 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 expectedresponse
is Some r
when the response r
is emitted, and
None
otherwiseemit_result r outvars
emits the main result r
and the output
parameters outvars
emit_user_exception sv
emits the user exception contained in sv
emit_unknown_local_exception s
emit the "unknown local exception",
accompanied by the string s
emit_unknown_user_exception s
emit the "unknown user exception",
accompanied by the string s
emit_unknown_exception s
emit the "unknown exception",
accompanied by the string s
request_id
is the request ID sent in the request. Fails if
non applicable (e.g. oneway calls)context
is the list of key/value pairs sent as context in
the request messageserver_ops
allows access to server-specific operationstypeoperation_dispatcher =
< hydro_effective_id : string;
hydro_invoke_operation : string ->
value array ->
session -> unit >
Not_found
after only passing the operation name to
hydro_invoke_operation
the operation does not exist.typefacet_dispatcher =
< invoke_facet : string option -> operation_dispatcher >
typeobject_dispatcher =
< get_identity : operation_dispatcher -> identity;
invoke_object : identity -> facet_dispatcher >
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.typeclient_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
`Message_lost
: The client was shut down before the response
arrived. The reason is unrelated to the RPC call that
sees `Message_lost
(i.e. it is a follow-up error). The argument
says whether the request message was tried to send (true
) or
not (false
).`Message_timeout
: The maximum time for replying the RPC call
has been exceeded.`Transport_timeout
: The transport level (TCP level) blocks for
too long. (This is a fatal error, and the client is shut down.)`Connect_timeout
: The transport level (TCP level) blocks for
too long while connecting to a server, or while doing the
initial handshake. It is ensured that the server has never seen
the RPC call. (This is a fatal error, and the client is shut down.)`Connect_error e
: An error happened while connecting to the
server, or while doing the initial handshake. The exception e
explains the error. It is ensured that the server has never seen
the RPC call. (This is a fatal error, and the client is shut down.)`Client_is_down
: A call is tried with a client that is already
shut down`User_exception sv
: The remote function raises a user-level
exception, i.e. an exception that is declared in the Ice IDL.
The sliced value sv
represents the exception.`Object_does_not_exist(id,facet,op)
: Cannot call the function
op
, optionally in facet
, of the remote object id
because
the object is unknown to the server.`Facet_does_not_exist(id,facet,op)
: Cannot call the function
op
, optionally in facet
, of the remote object id
because
the facet is unknown to the server.`Operation_does_not_exist(id,facet,op)
: Cannot call the function
op
, optionally in facet
, of the remote object id
because
the function is unknown to the server.`Unknown_local_exception s
: While performing the remote operation
the server caught an exception that is declared in the IDL
as local exception (such exception cannot be marshalled at all).
The string s
explains the exception.`Unknown_user_exception s
: While performing the remote operation
the server caught an exception that is declared in the IDL
but not for the operation. The string s
explains the exception.`Unknown_exception s
: While performing the remote operation
the server caught an unknown exception.
The string s
explains the exception.`Error e
: An error happened that is not one of the above.
The exception e
explains the error.
(This is a fatal error, and the client is shut down.)typetransport_protocol_type =
[ `Datagram | `Stream ]
class type descriptor =object
..end
typenetwork_port =
[ `TCP of Unix.inet_addr * int | `UDP of Unix.inet_addr * int ]