messagequeue

This module stores and manages the messages.

The fundamental class is MessageQueueManager. When an instance is created, a dictionary is defined to map the name of the topic to the instance of the topic object.

The protocols connected to the MQM should not access the topics directly, but should use the reference methods. The various reference methods enforce the security specifications defined in the security module.

Currently, there are four types of message queues:

• "topics"
• "queues"
• "pubsub"
• "command"

A "topic" is a transient queue. It only exists as long as there is at least one client connected to it. When a message is received, it's sent to all attached protocols.

One sample use of this type queue would be as the server in a chat application.

A "queue" will store messages until there is at least one protocol instance subscribed to it.

If multiple protocol instances are attached, messages are distributed to them in a round-robin order.
There is no way to determine in advance which protocol instance will receive a specific message.
If no instances are subscribed, messages will be held until an instance subscribes.
The first instance that subscribes will receive all messages held in the queue.
A sample use is for messages that need to be processed, even if there's no protocol currently subscribed.

A "pubsub" queue replicates incoming messages to a set of "child" queues.

The child queues distribute their messages according to their rules.
Clients may not subscribe to pubsub queues.
If a client is to receive messages, it must connect to one of the child queues.
Child queues may be added any time after the pubsub queue has been created, and applies to all subsequent messages.

The original intended use for a pubsub is to allow messages to be sent to multiple destinations and to allow for all messages to be processed by all recipients, even if they're not currently connected.

The "command" queues (not yet implemented) are intended to provide connections to other objects running within the same instance of twisted. The idea is to provide a programmatic interface to the internals of the MQM.

Some of the functionality intended for a command queue is the ability to create queues, empty "queues", associate queues with "pubsub" queues, disconnect clients, receive event notifications, etc. It is intended that security modules be defined to prevent clients from accessing these queues directly.

By default, queues starting with "/queue/", "/pubsub/", or "/command/" will be created as a "queue", "pubsub", or "command" queue respectively. Everything else will be created as a "topic". (There are plans to allow regular expressions in the configuration file to define what type of queue to create for a given name.)

The objects other than the MQM are not intended for use by other modules. If you want to implement your own queuing environment, create an instance of the MQM and let it create the other objects as needed.

The only method in MQM not intended for external use is "test_queue_rights". All others are supposed to be used externally.