=head1 NAME

UniEvent::FsPoll - monitor a given path for changes



=head1 SYNOPSIS

    my $h = UniEvent::FsPoll->new;
    
    # check every 5.5 seconds
    $h->start('/path/to/file', 5.5, sub {
        my ($handle, $prev_stat, $cur_stat, $error) = @_;
        if (!$error && $cur_stat->[UE::Fs::STAT_MTIME] != $prev_stat->[UE::Fs::STAT_MTIME]) {
            say "The contents of file has been modified";
        }
    });
    
    $h->start_callback(sub {
        my ($handle, $initial_stat, $error) = @_;
        # do something on the initial call with $initial_stat
    });



=head1 DESCRIPTION

FsPoll handles allow the user to monitor a given path for changes.
Unlike L<UniEvent::FsEvent>, fs poll handles use C<stat()> to detect when a file has changed so they can work on file systems where fs event handles can't.

FsPoll periodically polls filesystem for the specified file metadata (i.e. change time, file size etc.) and invoke the
user-specified callback with the current and previous metadata (file stats).

The C<UniEvent::FsPoll> is inherited from L<UniEvent::Handle>.



=head1 METHODS

All methods of L<UniEvent::Handle> also apply.

=head2 create($path, $interval, $callback, [$loop = default])

    my $handle = UniEvent::FsPoll->create("my/file", 1, sub { say "hi" });

Creates and starts an fs poll handle. Alias for C<new($loop)> + C<start($path, $interval, $callback)>.


=head2 new([$loop = default])

Constructs new FsPoll handle and binds it to the specified event loop.


=head2 start($path, [$interval = 1.0], [$callback])

Stars monitoring the specified C<$path> for changes.
Each filesystem poll would occur every C<$interval> second(s).

If C<$callback> is present, it is added as poll_event()->add($cb)


=head2 stop()

Stops monitoring.


=head2 poll_callback($sub)

=head2 poll_event()

Callbacks set via these methods will be invoked periodically, on file change.

Callback signature:

    my ($handle, $prev_stat, $cur_stat, $error) = @_;

Where C<$handle> is the FsPoll handle object itself.

C<$prev_stat> and C<$cur_stat> are arrayrefs with the previous and new file stat data. Format is similar to what perl's C<stat()> returns.
See L<UniEvent::Fs>'s C<stat()> for more details on stat structure.

The C<$err> parameter will be an L<XS::ErrorCode> object if any. If it is present, the contents of C<$prev_stat> and/or C<$cur_stat> may be undefined.

Error is considered part of file state.
File might get deleted or become inaccessible and in this case, callback will be called with defined $prev_stat, with error and with undefined $cur_stat.
And vice-versa, after that file might get created again in which case callback will be called with undefined $prev_stat, without error and with
defined $cur_stat.

See L<UniEvent/"EVENT CALLBACKS">


=head2 start_callback($sub)

=head2 start_event()

Callbacks set via these methods will be invoked once after monitoring starts.

Callback signature:

    my ($handle, $initial_stat, $error) = @_;

Where C<$handle> is the FsPoll handle object itself and C<$initial_stat> is the initial file stat. It may be undefined in case if file does not exist
or is inaccessible (in which case the error will also be set).

The C<$err> parameter will be an L<XS::ErrorCode> object if any. If it is present, the contents of C<$initial_stat> may be undefined.

See L<UniEvent/"EVENT CALLBACKS">


=head2 event_listener($delegate, [$weak])

Methods C<on_fs_poll>, C<on_fs_start> will be called.

See L<UniEvent/"EVENT LISTENER">


=head2 path()

Returns the currently monitored path.

=cut
