Léon Brocard > Net-Amazon-SimpleQueue-0.29 > Net::Amazon::SimpleQueue

Download:
Net-Amazon-SimpleQueue-0.29.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.29   Source   Latest Release: Net-Amazon-SimpleQueue-0.30

NAME ^

Net::Amazon::SimpleQueue - Use the Amazon Simple Queue Service

SYNOPSIS ^

  use Net::Amazon::SimpleQueue;
  my $sq = Net::Amazon::SimpleQueue->new($subscription_id);

  my @queues = $sq->list_my_queues();

  my $queue_id = $sq->create_queue(name => $queue_name);

  $sq->configure_queue(
    name => $queue_name,
    read_lock_timeout => 65,
  );

  $sq->enqueue(
    name => $queue_name,
    body => "here is the actual data",
  );

  my $entry = $sq->read(name => $queue_name);
  $sq->dequeue(name => $queue_name, entry_id => $entry->{id});

  my @entries = $sq->read(name => $queue_name, count => 25);

  $sq->delete_queue(name => $queue_name);

DESCRIPTION ^

The Net::Amazon::SimpleQueue module allows you to use the Amazon Simple Queue Service.

The Amazon Simple Queue Service provides a means for web service applications to quickly and reliably queue resources generated by a component to be consumed by another component. A queue can serve as a buffer for data flowing from one component to another, even when the producer is generating output faster than the consumer is retrieving it. A single queue can be used simultaneously by many distributed application components, with no need for those components to coordinate with each other to share the queue.

In order to access the Simple Queue Service, you will need an Amazon Web Services Subscription ID. See http://www.amazon.com/gp/aws/landing.html

Registered developers have free access to the Simple Queue Service during its Beta period, but storage is limited to 4,000 queue entries per developer.

There are some limitations, so be sure to read the The Amazon Simple Queue Service FAQ.

INTERFACE ^

The interface follows. Most of this documentation was copied from the API reference. Upon errors, an exception is thrown.

new

The constructor method creates a new Net::Amazon::SimpleQueue object. You must pass in an Amazon Web Services Subscription ID. See http://www.amazon.com/gp/aws/landing.html:

  my $sq = Net::Amazon::SimpleQueue->new($subscription_id);

create_queue

The create_queue method creates a new queue. An optional queue name may be provided to associate with the queue for future reference. All queues are assigned a queue ID, which may be used to refer to the queue:

  my $queue_id  = $sq->create_queue();
  my $queue_id2 = $sq->create_queue(name => $queue_name);

list_my_queues

The list_my_queues method returns information about queues for the given subscription ID. If called with a queue name prefix, only information about queues whose name begins with the prefix will be returned. The operation returns the queue ID, the queue name (if any), and the queue's current configuration (such as the read lock timeout), for each queue as a list of hash references.

This operation returns a maximum of 10,000 queues. If you have more than 10,000 queues, use the queue name prefix to narrow your search:

  my @queues = $sq->list_my_queues();
  foreach my $queue (@queues) {
    print $queue->{id} . ": " . $queue->{name} . "\n";
  }

  my @queues2 = $sq->list_my_queues(prefix = "/Ninjas/");

delete_queue

The delete_queue method deletes an empty queue from the system. If the queue being deleted still contains data, the operation will fail. All entries must be dequeued before the queue can be deleted. It may take some time, upwards to 60 seconds, until you can successfully delete a queue after removing all of the entries from a queue:

  $sq->delete_queue(id => $queue_id);

  $sq->delete_queue(name => $queue_name);

configure_queue

The configure_queue method adjusts the configuration of an existing queue. A queue can be configured to use the specified number of seconds as its read lock timeout:

  $sq->configure_queue(
    id => $queue_id,
    read_lock_timeout => 65,
  );

  $sq->configure_queue(
    name => $queue_name,
    read_lock_timeout => 30,
  );

enqueue

The enqueue method puts an entry into a queue. A successfully added value is subsequently available to consumers using the read method. Queue entries contain up to 4KB of text:

  $sq->enqueue(
    name => $queue_name,
    body => "here is the actual data",
  );

  $sq->enqueue(
    id   => $queue_id,
    body => "and some more",
  );

read

The read method returns a queue entry from a queue.

Applications should be prepared for the event where the same message is read more than once from the queue. A message may be returned by the read method even though it has already been dequeued, and concurrent read calls may return the same message to multiple readers. This behavior is a result of prioritizing reliable data storage (even in the face of hardware failures), and we expect such events to occur very infrequently. One way applications can cope with these occasional duplicates is by making the messages stored in the queue idempotent, that is, by ensuring that the effect of repeated receipt of a message is the same as that of receiving it once.

A read lock feature is included to lower the incidence of duplicate messages when multiple applications are concurrently reading from the same queue. After a successful read, the queue element is locked for a timeout period (60 seconds by default, or configurable using the create_queue or configure_queue operations). While locked, the queue entry will not be returned by another call to read(). This gives the consumer application the opportunity to process the value and remove it (with the dequeue method). If the application is unable to process and remove the value, the read lock expires and the value is made available on a future read attempt.

The read method tries to return queue entries that were added earlier before returning entries added later. However, read may return entries in a different order that they were added.

If specified, the read method will attempt to return as many entries as is specified by the count parameter. Fewer entries may be returned if there are fewer entries available or if not all of the entries are available. In the later case, you may want to call the read method again. Up to 25 entries may be read with one call to the read method.

Note that the webservice will throw an AWS.SimpleQueueService.NoData exception if the queue is empty. In an attempt to be more Perlish, instead of throwing this exception, the module returns undef or ().

  my $entry      = $sq->read(name => $queue_name);
  die "Nothing to read!" unless $entry;
  my $entry_id   = $entry->{id};
  my $entry_body = $entry->{body};

  my $entry2 = $sq->read(name => $queue_id);

  my @entries = $sq->read(name => $queue_name, count => 25);

dequeue

The dequeue method removes entries from a queue. An entry is identified by its queue entry ID, which is returned with the data from the read method.

In rare cases, the same queue entry may be returned by multiple read calls, even for data that has already been dequeued. This behavior is a result of prioritizing reliable data storage even in the face of network or hardware failures. If your application sees queue data that was previously removed, it should call the dequeue operation again.

  $sq->dequeue(name => $queue_name, entry_id => $entry->{id});

BUGS AND LIMITATIONS ^

No bugs have been reported.

Please report any bugs or feature requests to bug-<Net-Amazon-SimpleQueue@rt.cpan.org>, or through the web interface at http://rt.cpan.org.

AUTHOR ^

Leon Brocard acme@astray.com

LICENCE AND COPYRIGHT ^

Copyright (c) 2005, Leon Brocard acme@astray.com. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER OF WARRANTY ^

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

syntax highlighting: