Hydrodoc_intro

Introduction to Hydro

Introduction to Hydro

Hydro is an implementation of the ICE protocol for Objective Caml. Hydro consists of a runtime that manages connections, that implements the protocol details, and that defines the basic object architecture. Furthermore, Hydro includes a compiler hydrogen that reads the ICE interface definition language "Slice" and outputs O'Caml code for the language mapping.

ICE has been invented by the company ZeroC. This company offers bindings for C++, C#, Java, Python, Ruby, and PHP. There are also product extensions like IceGrid. While Hydro is compatible with ICE on the Slice and binary protocol level, its implementors have nothing to do with ZeroC, and have also gone their own ways in designing the runtime and the language mapping. Actually, Hydro is a clean-room implementation on the basis of the ICE User Manual.

We cannot explain the ICE architecture here. You can find an excellent description in the ICE User Manual.

The hydrogen compiler

hydrogen generates the language mapping code for a Slice file. The usage is quite simple:

 hydrogen file.ice 

This outputs an O'Caml module interface as file.mli and an implementation as file.ml. It is allowed to use the C preprocessor in the Slice file, so you can refer to other files. Hydro does not support, however, separate compilation of Slice modules, e.g. if file.ice contains Slice modules like

 module M1 {
     ...
   };

   module M2 {
     ...
   };

the generated mapping code is not structured by O'Caml modules M1 and M2, and you cannot O'Caml-compile M1 and M2 separately and link them later. hydrogen always produces a single O'Caml output module that is named after the single Slice input file. The Slice modules M1 and M2 only appear as part of the generated identifiers. (The reason for this is that Slice modules have C++ namespace semantics, that means it is possible to open them at any time and to add further definitions to them. It is also allowed to use forward declarations across Slice modules. Both is not supported by O'Caml modules.)

Option: Direct Mapping

The -dm switch of hydrogen enables the generation of faster language-mapping code. However, more code is generated in total.

The Hydro runtime

Programs can use the runtime by including -package hydro in the ocamlfind invocation.

The following modules are important for using Hydro:

• Hydro_types: Contains the basic type definitions of the runtime. Many of these types are only internally used. Especially the exception definitions are relevant for the user, however.
• Hydro_lm: Contains basic definitions for the language mapping. These definitions are referred to by the code generated by hydrogen.
• Hydro_proxy: A proxy is a handle on the client side for accessing a remote object that lives on the server side. This module defines the core proxy functionality, like name resolution, connection management, and method invocation. The code generated by hydrogen extends these functions by defining proxy objects for every callable remote object. The proxy objects are the language-mapped counterparts of proxy_t.
• Hydro_locator: Handles advanced proxy name resolution ("indirect proxies").

The Hydro runtime is generally written in an asynchronous way. This means that the runtime can handle input and output in parallel, and this for any number of connections. It is nevertheless single-threaded, so for many uses it is not necessary to deal with the complexity of multi-threading. For example, you can invoke methods of several remote objects in parallel by first submitting all method calls, and by then waiting until all responses have arrived. Technically, this is achieved by using the Equeue infrastructure of Ocamlnet: The user provides a Unixqueue.event_system to Hydro, and this event system coordinates all activities. Of course, the user can also decide to do only synchronous method calls (one call after the other). In order to get a Unixqueue.event_system, simply call

 let esys = Unixqueue.create_unix_event_system() 

once in your program and use this single esys for all your Hydro invocations. (Ocamlnet users know this.)

The runtime needs an in-memory representation of the Slice definition. This representation is called system, and it can also enriched by custom object constructors. Of course, hydrogen makes it simple to create a system, just do

 let sys = Hydro_lm.create_system() in
   M.fill_system sys;
   (* ...further sys modifications if necessary... *)
 

where M is the name of the hydro-generated O'Caml module.

Basic language mapping

The mapping for most types is straight-forward:

• Slice byte is mapped to O'Caml char
• Slice bool is mapped to O'Caml bool
• Slice short is mapped to O'Caml int
• Slice int is mapped to O'Caml int32
• Slice long is mapped to O'Caml int64
• Slice float and double are mapped to O'Caml float (which is double-precision)
• Slice string is mapped to O'Caml string. Note that ICE defines that strings are UTF-8-encoded. This is not enforced by Hydro.
• Slice sequences are mapped to O'Caml arrays. There is one exception, however: sequences of byte are mapped to O'Caml string.
• Slice dictionaries are mapped to O'Caml associative lists
• Slice structs are mapped to O'Caml records (some special magic has been added to generate unique component names)
• Slice enumerations are mapped to O'Caml polyvariants

Advanced language mapping

• For every interface and every class, a proxy is generated. See Hydrodoc_proxies.
• For every class, a mapping to a few O'Caml object types is generated. See Hydrodoc_classes.
• The exception handling is described in Hydrodoc_exceptions.

Customizing the language mapping

The hydrogen generator has a built-in default for how to map certain constructs. There are, however, some ways of modifying the default by attaching annotations to the definitions in the Slice file. See Hydrodoc_meta for more.

Developing clients

The page Hydrodoc_proxies gives an introduction into the development of clients.

Developing servers

The page Hydrodoc_servers shows how to develop servers.

This web site is published by Informatikbüro Gerd Stolpmann