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.