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``.