YAML-RPC README

Ilya V. Portnov portnov84@rambler.ru

The yaml-rpc package contains a small library to organize remote procedure call (RPC) over TCP/IP network, using YAML as data serialization format.

RPC server should supply a set of "RPC methods", which are simply functions :: a -> IO b, a' and 'b' should be of class IsYamlObject. This class guarantees that values of given type can be serialized to YAML and de-serialized. Network.YAML.Instances module provides some instances declaration for this typeclass. Moreover, Network.YAML.Derive module contains (TemplateHaskell) function deriveIsYamlObject, which will help you to declare instance IsYamlObject ...' for almost any ADT.

RPC-client calls RPC-methods usually using one of two ways. First is to use call' (or callDynamic') function from Network.YAML.Caller module. One need to give method name as it's parameter. Second way is to use (TemplateHaskell-) function `remote' from Network.YAML.WrapMethods module to declare wrapper functions for RPC-methods. These wrappers will have same names as source functions, and almost same behaivour. Single difference is that wrappers require pair: (RPC-server host name, port number) as their first argument.

Two modes of communication are supported. In first mode, client and server act as following:

Client: - opens socket to server - writes query to socket - waits for answer and reads it - closes socket - for next query, opens socket again etc. Server: - listens on socket - on connection (in the separate thread): - reads a query - computes answer - writes answer to socket - closes socket.

So, first mode is `one connection per query' mode. It's designed for situations when network connection between clients and servers is pretty good, and many machines runs same server code. So, this mode of RPC can be used in parallel load-balancing clusters.

In second mode, client and server act as following:

Client: - opens socket to server - writers query to socket - waits for answer and reads it - writes next query - reads next answer - etc - closes socket Server: - listens on socket - on connection (in separate thread): - reads a query - writes answer to socket - reads next query - etc

So, second mode is `one connection for series of queries', or 'persistent connection' mode. It's designed for situations when opening a socket takes much time — for example, when connection between client and server is not so good.

You can see examples of usage in files Test.hs and TestCall.hs. Haddock documentation is here: http://iportnov.ru/files/yaml-rpc/html/index.html.

Depends: ghc >= 6.10, network, data-object, data-object-yaml, yaml, data-default.