From 9b5a6961a5662edf11ecee36caa5accbbda0281d Mon Sep 17 00:00:00 2001
From: drebs <drebs@leap.se>
Date: Mon, 1 Apr 2013 17:16:23 -0300
Subject: Add README and changes file for events mechanism.

---
 src/leap/common/events/README | 45 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 src/leap/common/events/README

(limited to 'src/leap/common/events')

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)
-- 
cgit v1.2.3