NAME

POE::Component::SubWrapper - event based wrapper for subs

SYNOPSIS

  use POE::Component::SubWrapper;
  POE::Component::SubWrapper->spawn('main');
  $kernel->post('main', 'my_sub', [ $arg1, $arg2, $arg3 ], 'callback_state');

DESCRIPTION

This is a module which provides an event based wrapper for subroutines.

SubWrapper components are not normal objects, but are instead 'spawned' as separate sessions. This is done with with PoCo::SubWrapper's 'spawn' method, which takes one required and one optional argument. The first argument is the package name to wrap. This is required. The second argument is optional and contains an alias to give to the session created. If no alias is supplied, the package name is used as an alias.

Another way to create SubWrapper components is to use the poeize method, which is included in the default export list of the package. You can simply do:

  poeize Data::Dumper;

and Data::Dumper will be wrapped into a session with the alias 'Data::Dumper'.

When a SubWrapper component is created, it scans the package named for subroutines, and creates one state in the session created with the same name of the subroutine.

The states each accept 3 arguments:

• An arrayref to a list of arguments to give the subroutine.

• A state to callback with the results.

• A string, either 'SCALAR', or 'ARRAY', allowing you to decide which context the function handled by this state will be called in.

The states all call the function with the name matching the state, and give it the supplied arguments. They then postback the results to the named callback state. The results are contained in ARG0 and are either a scalar if the function was called in scalar context, or an arrayref of results if the function was called in list context.

EXAMPLES

The test scripts are the best place to look for examples of POE::Component::Subwrapper usage. A short example is given here:

  use Data::Dumper;
  poeize Data::Dumper;
  $kernel->post('Data::Dumper', 'Dumper', [ { a => 1, b => 2 } ], 'callback_state', 'SCALAR');

  sub callback_handler {
    my $result = @_[ARG0];
    # do something with the string returned by Dumper({ a => 1, b => 2})
  }

Data::Dumper is the wrapped module, Dumper is the function called, {a => 1, b => 2} is the data structure that is dumped, and $result is the resulting string form.

EXPORT

The module exports the following functions by default:

poeize

A function called with a single bareword argument specifying the package to be wrapped.

AUTHOR

sungo - eek+cpan@eekeek.org

Michael Stevens - michael@etla.org.

SEE ALSO

perl(1).