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.