<previous | top | next> | Pyro Manual |
Here does the Event Service fit in nicely. It is a third party that controls the flow of information about certain subjects ("events"). A publisher uses the Event Service to publish a message on a specific subject. A subscriber uses the Event Service to subscribe itself on a specific subject. As soon as new information on a subject is produced (an "event" occurs) all subscribers for this subject receive the information. Nobody knows (and cares) about anybody else.
It is important to rembember that all events processed by the ES are transient, which means they are not stored. If there is no listener, all events disappear in the void. The store-and-forward programming model is part of a messaging service, which is not what the ES is meant to do.
It is also important to know that all subscription data is transient. Once the ES is stopped, all subscriptions are lost. The clients that are subscribed
are not notified of this! If no care is taken, they keep on waiting
forever for events to occur, because the ES doesn't know about them anymore!
Lastly, the Event Service is a multithreaded server. Publications are dispatched
to the subscribers in different threads, so they don't block eachother.
The Event Service will not work if your Python installation has no threads support.
Also notice that events may arrive at your listener in multithreaded fashion! Pyro itself
starts another thread in your listener to handle the new event, possibly while the previous
one is still being handled.
If you can't handle this, you have to use some form of thread locking in your client!
(see the threading
module on Semaphore
).
:Pyro.EventService
".
If you want, it is also available as Pyro.EventService.Server.EVENTSERVICE_NAME
.
The subjects are case insensitive. The patterns are matched case insensitive too.
Your clients (subscribers) need to have a Pyro handleRequests
loop, just
like a server, because they receive Pyro calls, namely,
the Event Service callbacks when a relevant event happened!
A base implementation of a Publisher
and a Subscriber
is available in Pyro.EventService.Clients
, to help you get started.
Note that the code below assumes you're talking directly to the Event Service, and that
you have it in a proxy object callled ES
.
publish
method: ES.publish(subjects, message)
where subjects
is a subject name or a sequence of one or more subject names (strings), and message
is the actual message.
The message can be any Python object.
event(self, event)
method.
This method is called by the Event Service. event
is
a Pyro.EventService.Event
object, which has the following properties:
msg | the actual message. Can be any Python object. |
subject | the subject string. |
time | the event's timestamp. |
Your subscriber will receive all events that are published on the relevant subjects. If your subscriber is slow, a backlog will build up. You still get all events (with the original timestamp - so you could skip events that "have expired" to catch up). Currently there is no way around this. In a future version it might be possible to specify maximum backlog length.
The multithreading of the event
method can be controlled using the setThreading(threading)
method. If you pass 0 or None, the threading will be switched off (it is on by default unless
otherwise configured). Your events will then arrive purely sequentially, after processing each event.
To subscribe, call the subscribe
method: ES.subscribe(subjects, subscriber)
where subjects
is a subject name or a sequence of one or more subject names (strings), and subscriber
is a proxy for your subscriber object.
Pattern matching subjects: To subscribe on a pattern
that matches a range of subjects, call the subscribeMatch
method: ES.subscribeMatch(subjectPatterns, subscriber)
, where subjectPatterns
is a subject pattern or a sequence of one or more subject patterns (strings), and subscriber
is a proxy for your subscriber object. The patterns are standard re
-regex expressions. See the standard re
module for more information.
The pattern '^STOCKQUOTE\\.S.*$'
matches STOCKQUOTE.SUN, STOCKQUOTE.SAP but not STOCKQUOTE.IBM, NYSE.STOCKQUOTE.SUN etcetera.
Repeating it once more: the subjects are case insensitive. The patterns are matched case insensitive too.
To unsubscribe, call the unsubscribe
method: ES.unsubscribe(subjects, subscriber)
. This will remove the subscriber from the subscription list and also from
the pattern match list if the subject occurs as a pattern there.
Pyro.EventService.Clients.Publisher
publish(subjects, message)
method of yourself. No Event Service proxy code needed.
Pyro.EventService.Clients.Subscriber
subscribe(subjects)
,
subscribeMatch(subjectPatterns)
and unsubscribe(subjects)
methods of yourself.
No Event Service proxy code needed. This base class also starts a Pyro daemon and by calling listen()
,
your code starts listening on incoming events.
When you want to abort the event loop, you have to call self.abort()
.
es
command from the bin
directory (use es.bat
on windows).
Make sure that a Name Server is already running.
Currently there are no options. The Event Service just starts on the current host.
A new utility is planned that is a more generic service manager. You'll be able to start, stop and configure the various services, including the Name Server.