########
Overview
########

Why yet another RPC library?
============================

There are few RPC_ libraries for python, but they do not fit some our
requirements.

Other libraries for python
--------------------------

XML-RPC_
^^^^^^^^

Monster. Very slow. Only blocking calls.

Pyro or any other python-specific library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Quite fast, but available only in python. You cant connect with Pyro client to
anything except Pyro itself. Also Pyro has some weird glitches. For example,
after client connects to server, server will issue handshake! This is weird,
because if you accidentially connect to any other service (e.g. http server)
you will need to wait for handshake from server untill timeout occurs. Same
happens if pyro server freezes for some reason.

JSON-RPC_
^^^^^^^^^

Good enough, but dont allows streaming due to JSON_ nature.

MessagePackRPC_
^^^^^^^^^^^^^^^

There are few available libraries for python currently. But they dont allow
streaming, yielding and easy integration into already existing event loops.

Why based on MessagePackRPC_?
-----------------------------

MessagePack_ itself is a masterpiece. It has very low footprint, very fast by
design and allows streaming. There are already a lot of MessagePackRPC_
libraries made already. You can run MessagePackRPC_ server in Java_ and it
would be great if we will be able to connect it with our client. And it would
be perfect if you will be able to connect to :ref:`joint-server` from other
languages using already existing MessagePackRPC_ libraries.

Thats why we made joint_ based on MessagePackRPC_. It fully implements stock
`MessagePackRPC specification`_, but if you connect to :ref:`joint-server`
from `joint-client`, you are able to use extended version of
:ref:`joint-protocol`.

.. _Java: http://java.com/en/
.. _JSON: http://json.org/
.. _JSON-RPC: http://www.jsonrpc.org/
.. _MessagePack: http://msgpack.org/
.. _MessagePackRPC: http://wiki.msgpack.org/display/MSGPACK/Design+of+RPC
.. _MessagePackRPC specification:
   http://wiki.msgpack.org/display/MSGPACK/RPC+specification
.. _RPC: http://en.wikipedia.org/wiki/Remote_procedure_call
.. _XML-RPC: http://en.wikipedia.org/wiki/XML-RPC