NAME

Spread::Queue::Worker - accept Spread::Queue message assignments

SYNOPSIS

  use Spread::Queue::Worker;

  my $worker = new Spread::Queue::Worker(QUEUE => "myqueue",
                                         CALLBACK => \&mycallback,
                                        );
  $worker->run;

  sub mycallback {
    my ($worker, $originator, $input) = @_;

    my $result = {
		  response => "I heard you!",
		 };
    $worker->respond($originator, $result);
  }

DESCRIPTION

A process that declares itself to be a Spread::Queue::Worker will be assigned messages in FIFO fashion by the sqm queue manager.

Messages as supported by Spread::Queue are serialized Perl hashes. Spread::Queue does not enforce structure on message contents.

A running sqm for the queue is required before any messages will be routed to the worker. Worker will not terminate if sqm is not running, or if it goes away. If the sqm terminates and restarts, it will reacquire any running workers (via heartbeat status signals).

METHODS

new

my $worker = new Spread::Queue::Worker("myqueue");

Establish link to Spread messaging environment, and prepare to receive messages on specific queue. Queue name will be obtained from SPREAD_QUEUE environment variable if not provided here.

run

$worker->run;

Main loop for queue processing. Each incoming message will trigger a call to the user-specified callback function.

The loop will exit when $worker->terminate is called.

setup_Event

use Event;
$worker->setup_Event;
Event::loop;

Configure Event.pm callback for processing incoming messages. $worker->terminate is still recommended in this configuration, to advise the queue manager to no longer assign tasks to this worker.

respond

$worker->respond($originator, $result);

If the worker wants to send a reply back to the originator of the request (e.g. in a request-reply environment). $originator is the Spread private mailbox address sent to the callback function. $result is a reference to a Perl hash.

terminate

$worker->terminate;

Advises the queue manager that this worker is no longer available for task assignment. This will cause the runloop to exit.

Note that this is not automatically called on process termination. This means that the sqm might not realize that the worker is gone until its next automatic internal review cycle in a few seconds. For best messaging performance, it is important to notify the sqm as quickly as possible when a worker aborts.

AUTHOR

Jason W. May <jmay@pobox.com>

COPYRIGHT

Copyright (C) 2002 Jason W. May. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The license for the Spread software can be found at http://www.spread.org/license

SEE ALSO

L<Spread::Queue>
L<Data::Serializer>
L<Event>