NAME

Tibco::Rv::IO - Tibco IO event object

SYNOPSIS

   my ( $io );
   $io = $rv->createIO( socketId => fileno( IN ),
      ioType => Tibco::Rv::IO::READ, callback => sub
   {
      my ( $data ) = scalar( <IN> );
      print "I got data: $data\n";
      $io->DESTROY;
   }

DESCRIPTION

A Tibco::Rv::IO fires an event when a file handle (or socket) becomes ready for reading, writing, or has an exceptional condition occur. It is a subclass of Tibco::Rv::Event, so Event methods are available to IO objects (documentation on Event methods are reproduced here for convenience).

CONSTRUCTOR

$io = new Tibco::Rv::IO( %args )

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

Creates a Tibco::Rv::IO. If not specified, queue defaults to the Default Queue, socketId defaults to 1, ioType defaults to Tibco::Rv::IO::READ, and callback defaults to:

   sub { print "IO event occurred\n" }

Create an IO object to cause an event to fire when $socketId is ready for reading, writing, or has an exceptional condition (the ioType parameter must be one of the ioType constants below). To extract the socketId from a Perl filehandle, use the builtin fileno( ) function. When $queue dispatches such an event, it triggers the given callback.

METHODS

$socketId = $io->socketId

Returns the socketId being monitiored.

$ioType = $io->ioType

Returns the ioType constant representing what $io is monitoring for -- reading, writing, or a conditional exception.

$queue = $io->queue

Returns the queue on which this IO's events will be dispatched.

$callback = $io->callback

Returns the callback code reference.

$io->onEvent

Trigger an event directly. The event will be processed as if it was triggered via the event queue.

$io->DESTROY

Cancels the IO monitoring. Called automatically when $io goes out of scope. Calling DESTROY more than once has no effect.

IOTYPE CONSTANTS

Tibco::Rv::IO::READ => 1

Tibco::Rv::IO::WRITE => 2

Tibco::Rv::IO::EXCEPTION => 4

OVERRIDING EVENT CALLBACK

As an alternative to passing in a callback function to the constructor, there is another way to handle events. You can subclass Tibco::Rv::IO and override the onEvent method, as follows:

   package MyIO;
   use base qw/ Tibco::Rv::IO /;

   sub new
   {
      my ( $proto, %args ) = @_;
      my ( $self ) = $proto->SUPER::new( %args );
      # your initialization code
      return $self;
   }

   sub onEvent
   {
      my ( $self ) = @_;
      # process event here
      # $self->queue, $self->socketId, $self->ioType are available
   }

   # any other implementation code for your class

   1;

The Tibco::Rv::Event onEvent method simply calls the callback, so overriding onEvent allows you to process the event however you want, and you can just not use the callback.

The advantages of this method of handling events are: it is more object-oriented; you have access to the queue, socketId, and ioType via the $self accessor methods; and, you can have more elaborate processing of IO events without having to shove it all into one callback.

You can use your subclassed IO as follows:

   use Tibco::Rv;
   use MyIO;

   my ( $rv ) = new Tibco::Rv;
   my ( $myIo ) =
      new MyIO( ioType => Tibco::Rv::IO::READ, socketId => fileno( IN ) );
   $rv->start;

AUTHOR

Paul Sturm <sturm@branewave.com>