View on
MetaCPAN
David Snopek > POE-Component-MessageQueue-0.1.8 > POE::Component::MessageQueue

Download:
POE-Component-MessageQueue-0.1.8.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  4
Open  2
View/Report Bugs
Module Version: 0.1.8   Source   Latest Release: POE-Component-MessageQueue-0.3004

NAME ^

POE::Component::MessageQueue - A POE message queue that uses STOMP for the communication protocol

SYNOPSIS ^

  use POE;
  use POE::Component::Logger;
  use POE::Component::MessageQueue;
  use POE::Component::MessageQueue::Storage::Default;
  use strict;

  my $DATA_DIR = '/tmp/perl_mq';

  # we create a logger, because a production message queue would
  # really need one.
  POE::Component::Logger->spawn(
    ConfigFile => 'log.conf',
    Alias      => 'mq_logger'
  );

  POE::Component::MessageQueue->new({
    port     => 61613,            # Optional.
    address  => '127.0.0.1',      # Optional.
    hostname => 'localhost',      # Optional.
    domain   => AF_INET,          # Optional.
    
    logger_alias => 'mq_logger',  # Optional.

    # Required!!
    storage => POE::Component::MessageQueue::Storage::Default->new({
      data_dir     => $DATA_DIR,
      timeout      => 2,
      throttle_max => 2
    })
  });

  POE::Kernel->run();
  exit;

COMMAND LINE ^

If you are only interested in running with the recommended storage backend and some predetermined defaults, you can use the included command line script.

  POE::Component::MessageQueue version 0.1.8
  Copyright 2007, 2008 David Snopek (http://www.hackyourlife.org)
  Copyright 2007, 2008 Paul Driver <frodwith@gmail.com>
  Copyright 2007 Daisuke Maki <daisuke@endeworks.jp>
  
  mq.pl [--port|-p <num>] [--hostname|-h <host>]
        [--front-store <str>] [--nouuids]
        [--timeout|-i <seconds>]   [--throttle|-T <count>]
        [--data-dir <path_to_dir>] [--log-conf <path_to_file>]
        [--stats] [--stats-interval|-i <seconds>]
        [--background|-b] [--pidfile|-p <path_to_file>]
        [--crash-cmd <path_to_script>]
        [--debug-shell] [--version|-v] [--help|-h]
  
  SERVER OPTIONS:
    --port     -p <num>     The port number to listen on (Default: 61613)
    --hostname -h <host>    The hostname of the interface to listen on 
                            (Default: localhost)
  
  STORAGE OPTIONS:
    --front-store -f <str>  Specify which in-memory storage engine to use for
                            the front-store (can be memory or bigmemory).
    --timeout  -i <secs>    The number of seconds to keep messages in the 
                            front-store (Default: 4)
    --[no]uuids             Use (or do not use) UUIDs instead of incrementing
                            integers for message IDs.  Default: uuids 
    --throttle -T <count>   The number of messages that can be stored at once 
                            before throttling (Default: 2)
    --data-dir <path>       The path to the directory to store data 
                            (Default: /var/lib/perl_mq)
    --log-conf <path>       The path to the log configuration file 
                            (Default: /etc/perl_mq/log.conf
  
  STATISTICS OPTIONS:
    --stats                 If specified the, statistics information will be 
                            written to $DATA_DIR/stats.yml
    --stats-interval <secs> Specifies the number of seconds to wait before 
                            dumping statistics (Default: 10)
  
  DAEMON OPTIONS:
    --background -b         If specified the script will daemonize and run in the
                            background
    --pidfile    -p <path>  The path to a file to store the PID of the process
  
    --crash-cmd  <path>     The path to a script to call when crashing.
                            A stacktrace will be printed to the script's STDIN.
                            (ex. 'mail root@localhost')
  
  OTHER OPTIONS:
    --debug-shell           Run with POE::Component::DebugShell
    --version    -v         Show the current version.
    --help       -h         Show this usage message

DESCRIPTION ^

This module implements a message queue [1] on top of POE that communicates via the STOMP protocol [2].

There exist a few good Open Source message queues, most notably ActiveMQ [3] which is written in Java. It provides more features and flexibility than this one (while still implementing the STOMP protocol), however, it was (at the time I last used it) very unstable. With every version there was a different mix of memory leaks, persistence problems, STOMP bugs, and file descriptor leaks. Due to its complexity I was unable to be very helpful in fixing any of these problems, so I wrote this module!

This component distinguishes itself in a number of ways:

STORAGE ^

When creating an instance of this component you must pass in a storage object so that the message queue knows how to store its messages. There are some storage backends provided with this distribution. See their individual documentation for usage information. Here is a quick break down:

CONSTRUCTOR PARAMETERS ^

storage => SCALAR

The only required parameter. Sets the object that the message queue should use for message storage. This must be an object that follows the interface of POE::Component::MessageQueue::Storage but doesn't necessarily need to be a child of that class.

alias => SCALAR

The session alias to use.

port => SCALAR

The optional port to listen on. If none is given, we use 61613 by default.

address => SCALAR

The option interface address to bind to. It defaults to INADDR_ANY or INADDR6_ANY when using IPv4 or IPv6, respectively.

hostname => SCALAR

The optional name of the interface to bind to. This will be converted to the IP and used as if you set address instead. If you set both hostname and address, address will override this value.

domain => SCALAR

Optionally specifies the domain within which communication will take place. Defaults to AF_INET.

logger_alias => SCALAR

Opitionally set the alias of the POE::Component::Logger object that you want the message queue to log to. If no value is given, log information is simply printed to STDERR.

observers => ARRAYREF

Optionally pass in a number of objects that will receive information about events inside of the message queue.

Currently, only one observer is provided with the PoCo::MQ distribution: POE::Component::MessageQueue::Statistics. Please see its documentation for more information.

REFERENCES ^

[1]

http://en.wikipedia.org/Message_Queue -- General information about message queues

[2]

http://stomp.codehaus.org/Protocol -- The informal "spec" for the STOMP protocol

[3]

http://www.activemq.org/ -- ActiveMQ is a popular Java-based message queue

UPGRADING FROM OLDER VERSIONS ^

If you used any of the following storage engines with PoCo::MQ 0.1.7 or older:

The database format has changed.

Note: When using POE::Component::MessageQueue::Storage::Default (meaning mq.pl) the database will be automatically updated in place, so you don't need to worry about this.

Included in the distribution, is a schema/ directory with a few SQL scripts for upgrading:

CONTACT ^

Please check out the Google Group at:

http://groups.google.com/group/pocomq

Or just send an e-mail to: pocomq@googlegroups.com

DEVELOPMENT ^

If you find any bugs, have feature requests, or wish to contribute, please contact us at our Google Group mentioned above. We'll do our best to help you out!

Development is coordinated via Bazaar (See http://bazaar-vcs.org). The main Bazaar branch can be found here:

http://code.hackyourlife.org/bzr/dsnopek/perl_mq

We prefer that contributions come in the form of a published Bazaar branch with the changes. This helps facilitate the back-and-forth in the review process to get any new code merged into the main branch.

FUTURE ^

The goal of this module is not to support every possible feature but rather to be small, simple, efficient and robust. So, for the most part expect only incremental changes to address those areas. Other than that, here are some things I would like to implement someday in the future:

SEE ALSO ^

External modules:

POE, POE::Component::Server::Stomp, Net::Stomp, POE::Component::Logger, DBD::SQLite, POE::Component::Generic, POE::Filter::Stomp

Storage modules:

POE::Component::MessageQueue::Storage, POE::Component::MessageQueue::Storage::Memory, POE::Component::MessageQueue::Storage::BigMemory, POE::Component::MessageQueue::Storage::DBI, POE::Component::MessageQueue::Storage::FileSystem, POE::Component::MessageQueue::Storage::Generic, POE::Component::MessageQueue::Storage::Generic::DBI, POE::Component::MessageQueue::Storage::Throttled, POE::Component::MessageQueue::Storage::Complex, POE::Component::MessageQueue::Storage::Default

Statistics modules:

POE::Component::MessageQueue::Statistics, POE::Component::MessageQueue::Statistics::Publish, POE::Component::MessageQueue::Statistics::Publish::YAML

BUGS ^

We are serious about squashing bugs! Currently, there are no known bugs, but some probably do exist. If you find any, please let us know at the Google group.

That said, we are using this in production in a commercial application for thousands of large messages daily and we experience very few issues.

AUTHORS ^

Copyright 2007, 2008 David Snopek (http://www.hackyourlife.org)

Copyright 2007, 2008 Paul Driver <frodwith@gmail.com>

Copyright 2007 Daisuke Maki <daisuke@endeworks.jp>

LICENSE ^

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

syntax highlighting: