NAME

IO::Lambda::Poll - emulate asynchronous behavior by polling

DESCRIPTION

The module wraps functions, that can only be used in the polling mode, and provides a layer between them and the lambda framework.

SYNOPSIS

    use IO::Lambda qw(:lambda);
    use IO::Lambda::Poll qw(poller);

    lambda {
       context 
          poller { check_if_ready }, 
	  timeout   => 5,
	  frequency => 0.1;
    tail {
       print shift() ? "ok\n" : "timeout\n";
    }}

API

poller (polling_function :: (%opt -> @list))) :: (%opt) -> @list

Accepts a code reference, that returns a list of results, where the first scalar is a boolean value that indicates whether a single-shot polling succeeded or not. Returns a new lambda, that accepts 'timeout', 'deadline', and 'frequency' options ( see poll_event below for the options description). The lambda returns @list if polling succeeds within a given time span, or empty list otherwise. The options passed to the lambda are also passed to the polling function.

poll_event $callback, $method, $poller, $deadline, $frequency, @param

Registers a polling event on the current lambda. $poller will be called with first parameter as the expiration flag, so it will be up to the programmer how to respond if both polling succeeded and timeout occured. $poller must return first parameter the success flag, which means, if true, that the event must not be watched anymore, and the associated lambda must be notified of the event. Other parameters are passed to $callback, in free form, according to the API that the caller of poll_event implements.

$frequency sets up the polling frequency. If undef, then polling occurs during the idle time, when other events are passing.

Returns the newly created event record.

Example of use:

    use IO::Lambda qw(:all :dev);
    use IO::Lambda::Poll qw(poll_event);

    sub check_status(&)
    {
        return this-> override_handler('check_status', \&check_status, shift)
            if this-> {override}->{check_status};
        
        my $cb = _subname check_status => shift;
        my ($status_entity, $deadline, @some_params) = context;
        
        poll_event( $cb, \&check_status, \&poll_status, $deadline, $status_entity, @some_params);
    }

    sub poll_status
    {
        my ( $expired, $status_entity, @some_params) = @_;

	# poll, and return more info (in free form) to the callback on success
	return 1, MyLibrary::some_status if MyLibrary::check($status_entity);

	# return timeout flag to the callback (again, in free form)
	return 1, undef if $expired;             

	# nothing happened yet
	return 0;
    }

poll_cancel $rec

Brutally removes the polling record from the watching queue. Not for direct use. For the graceful event removal use one of the following:

$lambda-> cancel_event( $rec-> {bind} )

or

$lambda-> cancel_all_events;

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.