Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
Fundamentals
============
sjRpc is a RPC (Remote Procedure Call) library written with Python. It was
originally created for the needs of CloudControl project but can be reused
in other projects.
Features
--------
* **Bidirectional:** remote function can be call by both side of the,
connection, so a client can connect to a server and export functions to it.
* **Use Gevent:** the server mode can use Gevent to take profits of
asynchronous io, but a threaded mode is also provided. The client mode can
be used without Gevent or Threading.
* **Multiplexed:** sjRpc can run many "protocols" on the same connection,
read more about protocols in `Multiplexing & protocols`_ section.
Multiplexing & protocols
------------------------
Protocol of sjRpc use channels to multiplexe many protocols on the
same connection. Each channel is binded to a protocol handler on each side, and
each channel have a label which identify it on the wire. Actually, the sjRpc
protocol look like this::
+------------+------------------------+---------------------------------+
| Label (2) | Payload size (4) | Payload (variable) |
+------------+------------------------+---------------------------------+
For the moment, two types of protocols are implemented:
* **Rpc:** protocol which allow to make remote function call easily.
* **Tunnel:** protocol which allow to tunnel a socket through the sjRpc
connection.
.. note::
A Rpc protocol is automatically created and binded to label 0 when a
:class:`RpcConnection` class is instantiated. This can't be changed or
removed.
Default rpc, aka Rpc0
---------------------
Rpc0 is an RpcProtocol binded by default with the "0" label. You can't
unregister this protocol, and you can't disable this feature. Rpc0 is used
internally by sjRpc to share special messages, and for compatibility with
olders sjRpc (see `Fallback mode`_ below).
However, you can use this rpc like any other, with your own rpc handler.
Fallback mode
-------------
The fallback mode makes the *sjrpc >= 14* compatible with olders version where
channels and protocols doesn't exists. Old and new protocols are very similar,
the new one just add a label field on each frame which allow multiplexing, but
the rpc protocol itself has not changed, and is always using json messaging.
The fallback mode is enabled by default when a connection is established (you
can disable this behavior with the `disable_fallback` parameter of the
:class:`RpcConnection` class constructor) and is automatically disabled when
a special rpc message "capabilities" is received.
.. note::
When the fallback mode is enabled, you can't use another protocols than the
default rpc. All calls to :meth:`RpcConnection.register_protocol`,
:meth:`RpcConnection.unregister_protocol`, :meth:`RpcConnection.create_rpc`
and :meth:`RpcConnection.create_tunnel`, will fail with a
:exc:`FallbackModeEnabledError`.