<previous | contents | 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 to specific subjects, or to a pattern that matches certain subjects. 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!
Usually your subscribers will receive the events in the order they are published. However, this is not guaranteed. If you rely on the exact order of receiving events, you must add some logic to check this (possibly by examining the event's timestamps). The chance of events not arriving in the order they were published is very, very small in a high-performance LAN. Only on very high server load, high network traffic, or a high-latency (WAN?) connection it is likely to occur.
Another thing to pay attention to is that the ES does not guarantee delivery of events. As mentioned above, the ES does not have a store-and-forward mechanism, but even if everything is up and running, the ES does not enhance Pyro's way of transporting messages. This means that it's still possible (perhaps due to a network error) that an event gets lost. For reliable, guaranteed, asynchronous message delivery you'll have to look somewhere else, sorry ;-)
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.constants.EVENTSERVER_NAME
.
The subjects are case insensitive. The patterns are matched case insensitive too.
Your clients (subscribers) need to call the Pyro daemon's handleRequests
or
requestLoop
(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).
You can specify the following arguments:
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.
<previous | contents | next> | Pyro Manual |