IO::Lambda::Poll(3)

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>.