/ 
Tibco-Rv-1.00
River stage zero No dependents
/ Tibco::Rv

NAME

Tibco::Rv - Perl bindings and Object-Oriented library for TIBCO's TIB/Rendezvous

SYNOPSIS

use Tibco::Rv;

my ( $rv ) = new Tibco::Rv;

my ( $listener ) =
   $rv->createListener( subject => 'ABC', callback => sub
{
   my ( $msg ) = @_;
   print "Listener got a message: $msg\n";
} );

my ( $timer ) = $rv->createTimer( timeout => 2, callback => sub
{
   my ( $msg ) = $rv->createMsg;
   $msg->addString( field1 => 'myvalue' );
   $msg->addString( field2 => 'myothervalue' );
   $msg->sendSubject( 'ABC' );
   print "Timer kicking out a message: $msg\n";
   $rv->send( $msg );
} );

my ( $killTimer ) =
   $rv->createTimer( timeout => 7, callback => sub { $rv->stop } );

$rv->start;
print "finished\n"

DESCRIPTION

Tibco::Rv provides bindings and Object-Oriented classes for TIBCO's TIB/Rendezvous message passing C API.

All methods die with a Tibco::Rv::Status message if there are any TIB/Rendezvous errors.

CONSTRUCTOR

$rv = new Tibco::Rv( %args )
%args:
   service => $service,
   network => $network,
   daemon => $daemon

Creates a Tibco::Rv, which is the top-level object that manages all your TIB/Rendezvous needs. There should only ever be one of these created. Calling this method does the following: opens up the internal Rendezvous machinery; creates objects for the Intra-Process Transport and the Default Queue; creates a default QueueGroup and adds the Default Queue to it; and, creates the Default Transport using the supplied service/network/daemon arguments. Supply undef (or supply nothing) as the arguments to create a Default Transport connection to a Rendezvous daemon running under the default service/network/daemon settings.

See Tibco::Rv::Transport for information on the Intra-Process Transport.

See Tibco::Rv::Queue for information on the Default Queue.

See Tibco::Rv::QueueGroup for information on QueueGroups.

See your TIB/Rendezvous documentation for information on service/network/daemon arguments and connecting to Rendezvous daemons, and all other TIB/Rendezvous concepts.

METHODS

Tibco::Rv::die( $status )

Dies (raises an exception) with the given $status. $status can either be a Status object, or one of the Status Constants (below). The exception is of the form:

%d: %s

... where '%d' is the status number, and '%s' is a description of the error.

All Tibco::Rv methods use this method to raise an exception when they encounter a TIB/Rendezvous error. Use an eval { .. }; if ( $@ ) block around all Tibco::Rv code if you care about that sort of thing.

$ver = Tibco::Rv->version (or $ver = $rv->version)

Returns a string of the form:

tibrv x.x.xx; Tibco::Rv y.yy

where x.x.xx is the version of TIB/Rendezvous being used, and y.yy is the version of this module being used.

$transport = $rv->processTransport

Returns the Intra-Process Transport.

$transport = $rv->transport

Returns the Default Transport.

$queue = $rv->defaultQueue

Returns the Default Queue.

$queueGroup = $rv->defaultQueueGroup

Returns the Default QueueGroup. The Default QueueGroup originally contains only the Default Queue.

$rv->start

Begin processing events on the Default QueueGroup. This call remains in its own process loop until stop is called. Also, this call sets up a signal handler for TERM and KILL signals, which calls stop when either of those signals are received. It may also be useful to create a Listener which listens to a special subject, which, when triggered, calls stop.

$rv->stop

Stops the process loop started by start. If the process loop is not happening, this call does nothing.

$msg = $rv->createMsg

Returns a new Msg object.

$queueGroup = $rv->createQueueGroup

Returns a new QueueGroup object.

$transport = $rv->createTransport( %args )
%args:
   service => $service,
   network => $network,
   daemon => $daemon

Returns a new Transport object, using the given service/network/daemon arguments. These arguments can be undef or not specified to use the default arguments.

$dispatcher = $rv->createDispatcher( %args )
%args:
   idleTimeout => $idleTimeout

Returns a new Dispatcher object to dispatch on the Default QueueGroup, with the given idleTimeout argument (idleTimeout defaults to Tibco::Rv::WAIT_FOREVER if it is undef or not specified).

$queue = $rv->createQueue

Returns a new Queue object, added to the Default QueueGroup.

$rv->add( $queue )

Add $queue to the Default QueueGroup.

$rv->remove( $queue )

Remove $queue from the Default QueueGroup.

$timer = $rv->createTimer( %args )
%args:
   interval => $interval,
   callback => sub { ... }

Returns a new Timer object with the Default Queue and given interval, callback arguments.

$io = $rv->createIO( %args )
%args:
   socketId => $socketId,
   ioType => $ioType,
   callback => sub { ... }

Returns a new IO object with the Default Queue and given socketId, ioType, callback arguments.

$listener = $rv->createListener( %args )
%args:
   subject => $subject,
   callback => sub { ... }

Returns a new Listener object with the Default Queue, the Default Transport, and the given subject, callback arguments.

$rv->send( $msg )

Sends $msg via the Default Transport.

$rv->sendReply( $reply, $request )

Sends the given $reply message in response to the given $request message via the Default Transport.

$reply = $rv->sendRequest( $request, $timeout )

Sends the given $request message via the Default Transport, using the given $timeout. $timeout defaults to Tibco::Rv::WAIT_FOREVER if given as undef or not specified. Returns the $reply message, or undef if the timeout is reached before receiving a reply.

$inbox = $rv->createInbox

Returns a new $inbox subject.

$rv->DESTROY

Closes the TIB/Rendezvous machinery. DESTROY is called automatically when $rv goes out of scope, but you may also call it explicitly. All Tibco objects that you have created are invalidated (except for Tibco::Rv::Msg objects). Nothing will happen if DESTROY is called on an already-destroyed $rv.

STATUS CONSTANTS

Tibco::Rv::OK => 0
Tibco::Rv::INIT_FAILURE => 1
Tibco::Rv::INVALID_TRANSPORT => 2
Tibco::Rv::INVALID_ARG => 3
Tibco::Rv::NOT_INITIALIZED => 4
Tibco::Rv::ARG_CONFLICT => 5
Tibco::Rv::SERVICE_NOT_FOUND => 16
Tibco::Rv::NETWORK_NOT_FOUND => 17
Tibco::Rv::DAEMON_NOT_FOUND => 18
Tibco::Rv::NO_MEMORY => 19
Tibco::Rv::INVALID_SUBJECT => 20
Tibco::Rv::DAEMON_NOT_CONNECTED => 21
Tibco::Rv::VERSION_MISMATCH => 22
Tibco::Rv::SUBJECT_COLLISION => 23
Tibco::Rv::VC_NOT_CONNECTED => 24
Tibco::Rv::NOT_PERMITTED => 27
Tibco::Rv::INVALID_NAME => 30
Tibco::Rv::INVALID_TYPE => 31
Tibco::Rv::INVALID_SIZE => 32
Tibco::Rv::INVALID_COUNT => 33
Tibco::Rv::NOT_FOUND => 35
Tibco::Rv::ID_IN_USE => 36
Tibco::Rv::ID_CONFLICT => 37
Tibco::Rv::CONVERSION_FAILED => 38
Tibco::Rv::RESERVED_HANDLER => 39
Tibco::Rv::ENCODER_FAILED => 40
Tibco::Rv::DECODER_FAILED => 41
Tibco::Rv::INVALID_MSG => 42
Tibco::Rv::INVALID_FIELD => 43
Tibco::Rv::INVALID_INSTANCE => 44
Tibco::Rv::CORRUPT_MSG => 45
Tibco::Rv::TIMEOUT => 50
Tibco::Rv::INTR => 51
Tibco::Rv::INVALID_DISPATCHABLE => 52
Tibco::Rv::INVALID_DISPATCHER => 53
Tibco::Rv::INVALID_EVENT => 60
Tibco::Rv::INVALID_CALLBACK => 61
Tibco::Rv::INVALID_QUEUE => 62
Tibco::Rv::INVALID_QUEUE_GROUP => 63
Tibco::Rv::INVALID_TIME_INTERVAL => 64
Tibco::Rv::INVALID_IO_SOURCE => 65
Tibco::Rv::INVALID_IO_CONDITION => 66
Tibco::Rv::SOCKET_LIMIT => 67
Tibco::Rv::OS_ERROR => 68
Tibco::Rv::INSUFFICIENT_BUFFER => 70
Tibco::Rv::EOF => 71
Tibco::Rv::INVALID_FILE => 72
Tibco::Rv::FILE_NOT_FOUND => 73
Tibco::Rv::IO_FAILED => 74
Tibco::Rv::NOT_FILE_OWNER => 80
Tibco::Rv::TOO_MANY_NEIGHBORS => 90
Tibco::Rv::ALREADY_EXISTS => 91
Tibco::Rv::PORT_BUSY => 100

OTHER CONSTANTS

Tibco::Rv::SUBJECT_MAX => 255

Maximum length of a subject

Tibco::Rv::SUBJECT_TOKEN_MAX => 127

Maximum number of tokens a subject can contain

Tibco::Rv::FALSE => 0

Boolean true

Tibco::Rv::TRUE => 1

Boolean false

Tibco::Rv::WAIT_FOREVER => -1.0

Blocking wait on event dispatch calls (waits until an event occurs)

Tibco::Rv::NO_WAIT => 0.0

Non-blocking wait on event dispatch calls (returns immediately)

SEE ALSO

Tibco::Rv::Status
Tibco::Rv::Event
Tibco::Rv::QueueGroup
Tibco::Rv::Queue
Tibco::Rv::Dispatcher
Tibco::Rv::Transport

AUTHOR

Paul Sturm <sturm@branewave.com>

COPYRIGHT

Copyright (c) 2003 Paul Sturm. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Tibco::Rv will not operate without TIB/Rendezvous, which is not included in this distribution. You must obtain TIB/Rendezvous (and a license to use it) from TIBCO, Inc. (http://www.tibco.com).

TIBCO and TIB/Rendezvous are trademarks of TIBCO, Inc.

TIB/Rendezvous copyright notice:

/* * Copyright (c) 1998-2000 TIBCO Software Inc. * All rights reserved. * TIB/Rendezvous is protected under US Patent No. 5,187,787. * For more information, please contact: * TIBCO Software Inc., Palo Alto, California, USA * * @(#)tibrv.h 2.9 */