NAME

fs::Promises - Promises interface to nonblocking file system operations

SYNOPSIS

use fs::Promises;
use fs::Promises::Utils qw(await);

# Fancy, but not really useful:
my $fh = await +fs::Promises->open_promise($0);
while ( my $line = await +fs::Promises->readline_promise($fh) ) {
    say $line;
}


# Same thing but using the functional interface:
use fs::Promises qw(open_promise readline_promise);
my $fh = await open_promise($0);
while ( my $line = await readline_promise($fh) ) {
    say $line;
}

# Actuall async:
use experimental 'signatures';
use fs::Promises qw(open_promise readline_promise);
use fs::Promises::Utils qw(p_while);
await +open_promise($0)->then(sub ($fh) {
    return p_while { readline_promise($fh) } sub ($line) {
        say $line;
    }
});

# Reading four files in parallel:
use experimental 'signatures';
use AnyEvent::XSPromises qw(collect);
use fs::Promises qw(open_promise readline_promise);
use fs::Promises::Utils qw(await p_while);
my $read_file = sub ($fh) {
    return p_while { readline_promise($fh) } sub ($line) {
        say $line;
    }
};

await +collect(
    open_promise($0)->then($read_file),
    open_promise($0)->then($read_file),
    open_promise($0)->then($read_file),
    open_promise($0)->then($read_file),
);

DESCRIPTION

fs::Promises is a promises layer around AnyEvent::AIO. If your code is using promises, then you can use this module to do fs-based stuff in an asynchronous way.

DEALING WITH ERRORS

In standard Perl land, syscalls like the ones exposed here generally have this interface:

foo() or die "$!"

That is, you invoke the sycall, and it returns false if the underlaying operation failed, setting $ERRNO / $! in the process.

$! doesn't quite cut it for promises, because by the time your callback is invoked, it is entirely possible for something else to have run, which has now wiped $!.

So instead, all the interfaces here follow the same rough pattern:

foo()->then(sub ($success_result) { ... })
     ->catch(sub ($errno)         { ... })

The real example:

stat_promise($file)->then(
    sub ($stat_results) {
        # $stat_results has the same 13-element list as 'stat()'
    },
    sub ($errno) {
        my $e_num = 0 + $errno;
        my $e_str = "$errno";
        warn "stat($file) failed: '$e_str' ($e_num)";
        return;
    }
);