NAME

POE::Session::YieldCC - POE::Session extension for using continuations

SYNOPSIS

  use POE::Session::YieldCC;

  POE::Session::YieldCC->create(
    inline_states => {
      handler => sub {
	print "before\n";
	my $val = $_[SESSION]->yieldCC('do_async', 123);
	print "after: $val\n";
      },
      do_async => sub {
        my ($cont, $args) = @_[ARG0, ARG1];
        # do something synchronously, passing $cont about
        # when we're ready:
	$cont->("value");
      },
      demo_sleep => sub {
	print "I feel rather tired now\n";
	$_[SESSION]->sleep(60);
	print "That was a short nap!\n";
      },
      demo_wait = sub {
        print "I want to wait right now\n";
        $_[SESSION]->wait('demo_wait_event');
        print "Great!\n";
      },
      demo_wait_trigger = sub {
        $_[KERNEL]->yield('demo_wait_event');
      },
    },
  );
  $poe_kernel->run();

DESCRIPTION

POE::Session::YieldCC extends POE::Session to allow "continuations". A new method on the session object, yieldCC is introduced.

yieldCC takes as arguments a state name (in the current session) and a list of arguments. Control is yield to that state (via POE::Session->yield) passing a "continuation" as ARG0 and the arguments as an array reference in ARG1. yieldCC does not return immediately.

The "continuation" is a anonymous subroutine that when invoked passes control back to where yieldCC was called returning any arguments to the continuation from the yieldCC. Once the original state that called yieldCC finishes control returns to where the continuation was invoked.

In fact the "continuation" is also an object with several useful methods that are listed below.

Examples can be found in the examples/ directory of the distribution.

THIS MODULE IS EXPERIMENTAL. And while I'm pretty sure I've squashed all the memory leaks there may still be some.

METHODS

sleep SECONDS

Takes a number of seconds to sleep for (possibly fraction in the same way that POE::Kernel::delay can take fractional seconds) suspending the current event and only returning after the time has expired. POE events continue to be processed while you're sleeping.

wait EVENT_NAME [, TIMEOUT [, POST_TIMEOUT_HANDLER... ]]

Takes an event to wait for, suspending the current event. When the wake-up event is dispatched, control passes back and wait returns true, followed by any arguments passed in with the event. As with sleep, POE events continue to be processed while you're waiting.

If a timeout is provided, will optionally return after that number of seconds. In the case of a timeout, false is returned.

When a timeout is involved, it is possible that some code may try to dispatch the wakeup-event after wait has already returned. By default the event will no longer be registered any more, so _default will be delivered. However, if you so wish you can keep the event registered by providing your own event handler to take over after a timeout occurs. Anything that $kernel-state> understands is acceptable here.

CONTINUATION METHODS

invoke ARGS

The same as treating the continuation as a subroutine reference: it invokes the continuation passing the arguments as the return value of the yieldCC that created it. It returns when the original handler next gives up control either at its end or at another yieldCC call. It has no meaningful return value at the current time.

make_state

Returns the name of a state of the session which when posted to invokes the continuation with the event's arguments.

SEE ALSO

POE, POE::Session, Coro::State

AUTHOR

Benjamin Smith <bsmith@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Benjamin Smith

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.