view release on metacpan or  search on metacpan

lib/AnyEvent/Filesys/Watcher.pod  view on Meta::CPAN

Allows you to subscribe to the raw events returned by the os-specific backend.
The B<CALLBACK> gets invoked with a list of these backend-specific options and
should return a list of backend-specific options. Did you read this? You have
to return a list of events.

You can use this option if you are interested in the original events from your
backend or if you want to filter these events before being processed.

You can use both the option "callback" and "raw_events" but the filter
specified with the "filter" option is, of course, not applied to the raw
events because their exact structure is backend-specific.

Optional. Note that the option "callback" is still mandatory, even if you have
passed a callback to "raw_options".  Some backends require post-processing
of events and they have to be instances of L<AnyEvent::Filesys::Watcher::Event>.

=item B<backend BACKEND>

Force the use of the specified backend. The backend is assumed to
have the "AnyEvent::Filesys::Watcher" prefix, but you can force
a fully qualified name by prefixing it with a plus.

Optional. The default is os-dependent: For Linux it is
L<AnyEvent::Filesys::Watcher::Inotify2>, for Mac OS it is
L<AnyEvent::Filesys::Watcher::FSEvents>, for BSD systems it is
L<AnyEvent::Filesys::Watcher::KQueue>, for MS-DOS it is
L<AnyEvent::Filesys::Watcher::ReadDirectoryChhanges> and for all other systems
it is L<AnyEvent::Filesys::Watcher::Fallback>.

=back

=back

=head1 METHODS

The public API consists of the following methods:

=over 4

=item B<directories>

Getter for the array reference of directories that get monitored.

=item B<callback [CALLBACK]>

Getter/setter for the callback.

=item B<interval>

Getter for the interval between polls.

=item B<filter [FILTER]>

Getter/setter for the filter.

=back

=head1 INSTALLATION

You should install one of the helper module that provides
the binding for the operating system's filesystem watch functionality:

=head2 Linux

Install L<Linux::Inotify2>:

    $ cpanm Linux::Inotify2

=head2 Mac OS

Install L<Mac::FSEvents>:

    $ cpanm Mac::FSEvents

Versions before 0.20 do not build on recent macOS instances.

=head2 BSD and macOS

Install L<IO::KQueue> and L<BSD::Resource>

    $ cpanm IO::KQueue BSD::Resource

This would also work for Mac OS but you have little reason to prefer
L<IO::KQueue> over L<Mac::FSEvents> unless you are a developer or just
curious.

=head2 MS-DOS ("Windows")

Install L<Filesys::Notify::Win32::ReadDirectoryChanges>.

This backend causes spurious errors. If that happens, please use the
fallback backend.

=head1 USAGE RECOMMENDATIONS

Different platforms have different notions about file system changes and how
to report them.  This module tries to remove these differences and always
report the same events for a certain file type change.  The test suite
tests this behaviour but still you should not rely on it.

A robust implementation using this module should follow two rules:

=over 4

=item Do not expect events to come in a certain order.

=item Treat the events "modified" and "created" equally as "existing file has changed"

=back

=head1 DIFFERENCES TO AnyEvent::Filesys::Notify

=over 4

=item If you specify a subroutine as a filter, that subroutine receives events as arguments, not paths.

=item The constructor argument "no_external" is ignored.

=item There is no method "no_external()".

=item Methods and named arguments are "directories" and not "dirs".