NAME

Tibco::Rv::Queue - Tibco Queue event-managing object

SYNOPSIS

   $queue = new Tibco::Rv::Queue;

   $queue->name( 'myQueue' );

   $queue->createListener( subject => 'ABC', callback => sub { } );

   while ( 1 ) { $queue->dispatch }

DESCRIPTION

A Tibco::Rv::Queue manages events waiting to be dispatched.

CONSTRUCTOR

$queue = new Tibco::Rv::Queue( %args )

   %args:
      policy => $policy,
      maxEvents => $maxEvents,
      discardAmount => $discardAmount,
      name => $name,
      priority => $priority,
      hook => undef

Creates a Tibco::Rv::Queue. If not specified, policy defaults to Tibco::Rv::Queue::DEFAULT_POLICY (discard none), maxEvents defaults to 0 (unlimited), discardAmount defaults to 0, name defaults to 'tibrvQueue', priority defaults to Tibco::Rv::Queue::DEFAULT_PRIORITY (1), and hook defaults to undef (no hook).

The settings policy, maxEvents, and discardAmount are described under the limitPolicy method. The name setting is described under the name method, priority is described under the priority method, and hook is described under the hook method.

METHODS

$listener = $queue->createListener( %args )

   %args:
      transport => $transport,
      subject => $subject,
      callback => sub { ... }

Creates a Tibco::Rv::Listener with this $queue as the queue. See the Listener constructor for more details.

$timer = $queue->createTimer( %args )

   %args:
      interval => $interval,
      callbcak => sub { ... }

Creates a Tibco::Rv::Timer with this $queue as the queue. See the Timer constructor for more details.

$io = $queue->createIO( %args )

   %args:
      socketId => $socketId,
      ioType => $ioType,
      callback => sub { ... }

Creates a Tibco::Rv::IO with this $queue as the queue. See the IO constructor for more details.

$dispatcher = $queue->createDispatcher( %args )

   %args:
      name => $name,
      idleTimeout => $idleTimeout

Creates a Tibco::Rv::Dispatcher with this $queue as the dispatchable. See the Dispatcher constructor for more details.

$queue->dispatch

Dispatch a single event. If there are no events currently on the queue, then this method blocks until an event arrives.

$status = $queue->poll

Dispatch a single event if there is at least one event waiting on the queue. If there are no events on the queue, then this call returns immediately. Returns a Tibco::Rv::OK Status object if an event was dispatched, or Tibco::Rv::TIMEOUT if there were no events on the queue.

$status = $queue->timedDispatch( $timeout )

Dispatches a single event if there is at least one event waiting on the queue, or if an event arrives before $timeout seconds have passed. In either case, returns Tibco::Rv::OK. If $timeout is reached before dispatching an event, returns Tibco::Rv::TIMEOUT. If Tibco::Rv::WAIT_FOREVER is passed as $timeout, behaves the same as dispatch. If Tibco::Rv::NO_WAIT is passed as $timeout, behaves the same as poll.

$count = $queue->count

Returns the number of events waiting on the queue.

( $policy, $maxEvents, $discardAmount ) = $queue->limitPolicy

$queue->limitPolicy( $policy, $maxEvents, $discardAmount )

Returns or sets the three limitPolicy parameters. $policy is described in the Constants section below. $maxEvents is the maximum number of events allowed in the queue. 0 represents unlimited events. If $maxEvents is greater than 0, then events are discarded according to the other two limitPolicy parameters. $discardAmount is the number of events to discard when $queue reaches its $maxEvents limit.

$name = $queue->name

Returns the name of $queue.

$queue->name( $name )

Sets $queue's name to $name. The queue's name appears in advisory messages concerning queues, so it should be set to a unique value in order to assist troubleshooting. If $name is undef, sets name to ''.

$priority = $queue->priority

Returns the $queue's priority.

$queue->priority( $priority )

Sets the $queue's priority. Within a queue group, queues with higher priorities have their events dispatched before queues with lower priorities. The default setting is 1. 0 is the lowest possible priority.

$hook = $queue->hook

Returns the $queue's event arrival hook.

$queue->hook( sub { ... } )

Set the $queue's event arrival hook to the given sub reference. This hook is called every time an event is added to the queue.

$queue->DESTROY( $callback )

Destroys this queue and discards all events left on the queue. If the optional $callback is specified, then it (which should be a sub reference) will be called after all event callbacks currently being dispatched from this queue finish. Called automatically when $queue goes out of scope. Calling DESTROY more than once has no effect.

CONSTANTS

Tibco::Rv::Queue::DISCARD_NONE => 0

Tibco::Rv::Queue::DISCARD_NEW => 1

Tibco::Rv::Queue::DISCARD_FIRST => 2

Tibco::Rv::Queue::DISCARD_LAST => 3

Tibco::Rv::Queue::DEFAULT_POLICY => 0

Tibco::Rv::Queue::DEFAULT_PRIORITY => 1

These constants control the queue's behaviour when it overflows and in how different queues are dispatched relative to each other.

The DISCARD_* policies determine which events will be discarded when the queue reaches its maxEvents limit (set by limitPolicy). DISCARD_NONE should be used when the queue has no limit. DISCARD_NEW causes the event that would otherwise cause the queue to overflow its limit to be discarded. DISCARD_FIRST causes the oldest event (the one that would otherwise be dispatched next) to be discarded. DISCARD_LAST casues the youngest event to be discarded.

DEFAULT_PRIORITY is the default priority given to queues when they are created. Queues with higher priorities are dispatched before queues with lower priorities, when multiple priorities are in the same queue group.

DEFAULT QUEUE

The Default Queue is a queue that is automatically created when a new Tibco::Rv object is created. It is available as $Tibco::Rv::Queue::DEFAULT. It never discards events and has a priority of 1. Advisories pertaining to queue overflow are placed on this queue.

AUTHOR

Paul Sturm <sturm@branewave.com>