<previous | top | next> Pyro Manual

10. Pyro Services

This chapter describes the various services that Pyro offers.

Naming Service

The naming service is such an important service that it is documented in a separate chapter.

Event Service

In various situations it is needed that the servers and the clients are decoupled. In abstract terms this means that information producers do not know nor care about the parties that are interested in the information, and the information consumers do not know nor care about the source or sources of the information. All they know is that they produce or consume information on a certain subject.

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!

Using the Event Service

The Event Service is a regular Pyro object. Its name is ":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.

Publishing information
Just call the 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.

Subscribing to receive information
Create a subscriber object, which must be a Pyro object (or use delegation). The object should have a event(self, event) method. This method is called by the Event Service. event is a Pyro.EventService.Event object, which has the following properties:
msgthe actual message. Can be any Python object.
subjectthe subject string.
timethe event's timestamp.

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.

Starting the Event Service

The Event Service is started using the 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.

Example

To see how you use the Event Service, have a look at the "stockquotes" example.