[tests] adapt events tests to recent changes
[leap_pycommon.git] / src / leap / common / events / README.rst
1 Events mechanism
2 ================
3
4 The events mechanism allows for clients to send events to each other by means
5 of a centralized server. Clients can register with the server to receive
6 events of certain types, and they can also send events to the server that will
7 then redistribute these events to registered clients.
8
9
10 ZMQ connections and events redistribution
11 -----------------------------------------
12
13 Clients and server use ZMQ connection patterns to communicate. Clients can
14 push events to the server, and may subscribe to events published by the
15 server. The server in turn pulls events from clients and publishes them to
16 subscribed clients.
17
18 Clients connect to the server's zmq pub socket, and register to specific
19 events indicating which callbacks should be executed when that event is
20 received:
21
22
23                                EventsServer
24                               .------------.
25                               |PULL     PUB|
26                               '------------'
27                                          ^^
28                                          ||
29                             reg(1, cbk1) |'--------------. reg(2, cbk2)
30                                          |               |
31                                          |               |
32             .------------.    .------------.   .------------.
33             |PUSH     SUB|    |PUSH     SUB|   |PUSH     SUB|
34             '------------'    '------------'   '------------'
35              EventsClient      EventsClient     EventsClient
36
37
38 A client that wants to send an event connects to the server's zmq pull socket
39 and pushes the event to the server. The server then redistributes it to all
40 clients subscribed to that event.
41
42
43                                EventsServer
44                               .------------.
45                               |PULL---->PUB|
46                               '------------'
47                                ^         |.
48                                |         |.
49 sig(1, 'foo') .----------------'         |'...............
50               |                          |               .
51               |                          v               .
52             .------------.    .------------.   .------------.
53             |PUSH     SUB|    |PUSH     SUB|   |PUSH     SUB|
54             '------------'    '------------'   '------------'
55              EventsClient      EventsClient     EventsClient
56                                     |
57                                     v
58                               cbk1(1, 'foo')
59
60
61 Any client may emit or subscribe to an event. ZMQ will manage sockets and
62 reuse the connection whenever it can.
63
64
65                                EventsServer
66                               .------------.
67                               |PULL---->PUB|
68                               '------------'
69                                 ^        .|
70                                 |        .|
71 sig(2, 'bar') .-----------------'        .'--------------.
72               |                          .               |
73               |                          .               v
74             .------------.    .------------.   .------------.
75             |PUSH     SUB|    |PUSH     SUB|   |PUSH     SUB|
76             '------------'    '------------'   '------------'
77              EventsClient      EventsClient     EventsClient
78                                                      |
79                                                      v
80                                                cbk2(2, 'bar')
81
82
83 How to use it
84 -------------
85
86 To start the events server:
87
88 >>> from leap.common.events import server
89 >>> server.ensure_server(
90         emit_addr="tcp://127.0.0.1:9000",
91         reg_addr="tcp://127.0.0.1:9001")
92
93 To register a callback to be called when a given event is raised:
94
95 >>> from leap.common.events import register
96 >>> from leap.common.events import catalog
97 >>>
98 >>> def mycbk(event, *content):
99 >>>     print "%s, %s" (str(event),  str(content))
100 >>>
101 >>> register(catalog.CLIENT_UID, callback=mycbk)
102
103 To emit an event:
104
105 >>> from leap.common.events import emit
106 >>> from leap.common.events import catalog
107 >>> emit(catalog.CLIENT_UID)
108
109 Adding events
110 -------------
111
112 To add a new event, just add it to ``catalog.py``.