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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
Events mechanism
================
The events mechanism allows for clients to send events to each other by means
of a centralized server. Clients can register with the server to receive
events of certain types, and they can also send events to the server that will
then redistribute these events to registered clients.
ZMQ connections and events redistribution
-----------------------------------------
Clients and server use ZMQ connection patterns to communicate. Clients can
push events to the server, and may subscribe to events published by the
server. The server in turn pulls events from clients and publishes them to
subscribed clients.
Clients connect to the server's zmq pub socket, and register to specific
events indicating which callbacks should be executed when that event is
received:
EventsServer
.------------.
|PULL PUB|
'------------'
^^
||
reg(1, cbk1) |'--------------. reg(2, cbk2)
| |
| |
.------------. .------------. .------------.
|PUSH SUB| |PUSH SUB| |PUSH SUB|
'------------' '------------' '------------'
EventsClient EventsClient EventsClient
A client that wants to send an event connects to the server's zmq pull socket
and pushes the event to the server. The server then redistributes it to all
clients subscribed to that event.
EventsServer
.------------.
|PULL---->PUB|
'------------'
^ |.
| |.
sig(1, 'foo') .----------------' |'...............
| | .
| v .
.------------. .------------. .------------.
|PUSH SUB| |PUSH SUB| |PUSH SUB|
'------------' '------------' '------------'
EventsClient EventsClient EventsClient
|
v
cbk1(1, 'foo')
Any client may emit or subscribe to an event. ZMQ will manage sockets and
reuse the connection whenever it can.
EventsServer
.------------.
|PULL---->PUB|
'------------'
^ .|
| .|
sig(2, 'bar') .-----------------' .'--------------.
| . |
| . v
.------------. .------------. .------------.
|PUSH SUB| |PUSH SUB| |PUSH SUB|
'------------' '------------' '------------'
EventsClient EventsClient EventsClient
|
v
cbk2(2, 'bar')
How to use it
-------------
To start the events server:
>>> from leap.common.events import server
>>> server.ensure_server(
emit_addr="tcp://127.0.0.1:9000",
reg_addr="tcp://127.0.0.1:9001")
To register a callback to be called when a given event is raised:
>>> from leap.common.events import register
>>> from leap.common.events import catalog
>>>
>>> def mycbk(event, *content):
>>> print "%s, %s" (str(event), str(content))
>>>
>>> register(catalog.CLIENT_UID, callback=mycbk)
To emit an event:
>>> from leap.common.events import emit
>>> from leap.common.events import catalog
>>> emit(catalog.CLIENT_UID)
Adding events
-------------
To add a new event, just add it to ``catalog.py``.
|