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:

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:

Advanced language mapping

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.