Add README and changes file for events mechanism.

1 files changed, 45 insertions, 0 deletions

diff --git a/src/leap/common/events/README b/src/leap/common/events/README
new file mode 100644
index 0000000..61b320d
--- /dev/null
+++ b/src/leap/common/events/README
@@ -0,0 +1,45 @@
+Events mechanism
+================
+
+The events mechanism allows for "components" to send signal events to each
+other by means of a centralized server. Components can register with the
+server to receive signals of certain types, and they can also send signals to
+the server that will then redistribute these signals to registered components.
+
+
+Listening daemons
+-----------------
+
+Both components and the server listen for incoming messages by using a
+listening daemon that runs in its own thread. The server daemon has to be
+started explicitly, while components daemon will be started whenever a
+component registers with the server to receive messages.
+
+
+How to use it
+-------------
+
+To start the events server:
+
+>>> from leap.common.events import server
+>>> server.ensure_server(port=8090)
+
+To register a callback to be called when a given signal is raised:
+
+>>> from leap.common.events import (
+>>>     register,
+>>>     events_pb2 as proto,
+>>> )
+>>>
+>>> def mycallback(sigreq):
+>>>     print str(sigreq)
+>>>
+>>> events.register(signal=proto.CLIENT_UID, callback=mycallback)
+
+To signal an event:
+
+>>> from leap.common.events import (
+>>>     signal,
+>>>     events_pb2 as proto,
+>>> )
+>>> signal(proto.CLIENT_UID)