Add README and changes file for events mechanism.
[leap_pycommon.git] / src / leap / common / events / README
1 Events mechanism
2 ================
3
4 The events mechanism allows for "components" to send signal events to each
5 other by means of a centralized server. Components can register with the
6 server to receive signals of certain types, and they can also send signals to
7 the server that will then redistribute these signals to registered components.
8
9
10 Listening daemons
11 -----------------
12
13 Both components and the server listen for incoming messages by using a
14 listening daemon that runs in its own thread. The server daemon has to be
15 started explicitly, while components daemon will be started whenever a
16 component registers with the server to receive messages.
17
18
19 How to use it
20 -------------
21
22 To start the events server:
23
24 >>> from leap.common.events import server
25 >>> server.ensure_server(port=8090)
26
27 To register a callback to be called when a given signal is raised:
28
29 >>> from leap.common.events import (
30 >>>     register,
31 >>>     events_pb2 as proto,
32 >>> )
33 >>>
34 >>> def mycallback(sigreq):
35 >>>     print str(sigreq)
36 >>>
37 >>> events.register(signal=proto.CLIENT_UID, callback=mycallback)
38
39 To signal an event:
40
41 >>> from leap.common.events import (
42 >>>     signal,
43 >>>     events_pb2 as proto,
44 >>> )
45 >>> signal(proto.CLIENT_UID)