NAME

Stem::Route - Manages the Message Routing Tables and Cell Registry

SYNPOSIS

use Stem::Route qw( :all );

# $target is optional register_cell( $object, $name, $target ) ; unregister_cell($object); # or alternately... # again $target is optional unregister_by_name($name, $target);

DESCRIPTION

The Stem::Route class manages the registry of Stem Cells and their names for a given Stem Hub (process). Any object which has selected methods which take Stem::Msg objects as arguments can be a registered cell. There are only 4 class methods in this module which work with the cell registry. They can be exported into a module individually or you can use the export tag :all to get them all.

register_cell( $object, $name )
register_cell( $object, $name, $target )

This class method takes the object to be registered and its
cell name and an optional target name. The object is
registered as the cell in this hub with this name/target
address. The cell address must be free to use - if it is in
used an error string is logged and returned. This address will be the
primary one for this cell. undef or () is returned upon
success.

alias_cell( $object, $alias )
alias_cell( $object, $alias, $target )

This class method takes the object and a cell alias for it and
an optional target name. The object will be registered as the
cell in this hub with this alias/target address. The object
must already be registered cell or an error string is logged
and returned.  undef or () is returned upon a success.

lookup_cell( $name, $target )

This class method takes a cell name and an optional target and
it looks up the cell registered under that address pair. It
returns the object if found or undef or () upon failure.

unregister_cell( $object )

This class method takes a object and deletes it and all of its
names and aliases from the cell registry. If the object is not
registered an error string is logged and returned.

AUTHOR

Originally started by Uri, current breakout by a-mused.

STATUS

Actively being developed.

LAST-CHANGE

Mon Jan 22 14:15:52 EST 2001

NOTES

newest at the bottom

23 Jan 01
[01:09:34] <uri> here is a registry issue: i want to interpose cell in a
         message stream. how do i do that without redoing all the configs?
[01:09:50] <uri> sorta like invisible renaming on the fly
[01:09:56] <amused> hrmm
[01:10:11] <uri> think about it. that will be big one day
[01:11:01] <uri> just like sysv streams. we push stuff onto the registry address. then messages get sent down
         the list of pushed cells before being delivered to the real destination.
[01:11:29] <uri> so we need a way of moving messages from cell to cell without registering them globally but in
         some sort of pipeline
[01:13:39] <amused> doesn't that violate a whole bunch of models and break distributed (multi-target) stuff?
[01:13:45] <uri> so instead of deliver, they RETURN a message. like status_cmd returns a status string
[01:14:12] <uri> no, only certain cells do that and only when they get
         messages delivered that way.
[01:14:31] <uri> like stream_msg_in is called and it will return a message.
[01:14:44] <uri> insteead of msg_in or status_cmd.
[01:14:51] <amused> gotcha
[01:14:58] <uri> special input/output.
[01:15:00] <uri> same cell
[01:16:18] <uri> i like that. A LOT! very easy to do cell wise. and not much
         work on the delivery side. some way to make the registry store a
         stack of these under the name. make it a simple structure instead
         of a cell you find with lookup.
[13:14:51] <uri> you push filter cells onto the destination cell (indexed by
         its object ref). then any alias to it will have the same stack of
         filters.
[13:15:52] <uri> when we deliver a message (the stuf you are touching), we
         lookup the cell and then lookup via its ref) any filters. we then
         loop over the filters passing in the message and getting one in
         return and passint it to the next filter.
[13:16:02] <uri> just like sysV streams but unidirectional.
[13:16:38] <uri> we can interpose ANY set of filters before any named cell
         transparently
[13:16:39] <uri> this is VERY cool.
[13:16:53] <uri> but not critical now. i just want to write up some notes on
         it.