view release on metacpan or  search on metacpan

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

=head1 NAME

AnyEvent::Filesys::Watcher::KQueue - BSD file system watcher

=head1 SYNOPSIS

    $watcher = AnyEvent::Filesys::Watcher::KQueue->new(
        directories => ['lib', 't'],
        callback => sub { warn "you're working too much"},
    );

    # This has the same effect as:

    $watcher = AnyEvent::Filesys::Watcher->new(
        backend => 'KQueue',
        directories => ['lib', 't'],
        callback => sub { warn "you're working too much"},
    );

=head1 DESCRIPTION

This is the BSD backend for L<AnyEvent::Filesys::Watcher>.  It uses
L<IO::KQueue> as the underlying implementation.  It also works on Mac OS but
you have little reason to prefer it over
L<AnyEvent::Filesys::Watcher::FSEvents> because of its limitations.

=head1 CONSTRUCTOR

You should normally call the
L<constructor of the base class|AnyEvent::Filesys::Watch/"CONSTRUCTOR"> that
will pick the optimal backend for the current platform.

The following constructors are available:

=over 4

=item B<new(OPTIONS)>

Creates a new B<AnyEvent::Filesys::Watcher::KQueue>.  The constructor may throw an
exception in case of an error!

B<OPTIONS> is a hash of named options:

=over 8

=item B<directories DIRECTORIES>

B<DIRECTORIES> is a reference to an array of directories to monitor. A single
directory can also be passed as a scalar.

Optional. The default is the base directory, see "base_dir" below.

=item B<dirs DIRECTORIES>

This is an alias for the option "directories".

=item B<base_dir BASE_DIRECTORY>

Relative path names for the "directories" option are resolved relative to
B<BASE_DIRECTORY>.

The default is the current working directory at the time that the
object was instantiated.

=item B<callback CALLBACK>

A code reference that is called, when a modification to the monitored
directories is deteced. The callback is passed a list of
L<AnyEvent::Filesys::Watcher::Events>.

One of the options "callback" or "raw_events" (see below) are required.

=item B<cb CALLBACK>

This is an alias for the parameter B<callback>.

This argument is required if the argument B<callback> has not been given.

=item B<filter FILTER>

B<FILTER> should either be a regular expression or a code reference.  If this
is a regular expression, only (absolute) file names matching that regular
expressions can cause an event.

If B<FILTER> is a code reference, the subrouting receives the absolute file
name as an argument and should return a truthy value for all files that
should cause an event.

Optional. By default, all events are passed through.

=item B<raw_events CALLBACK>

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.