view release on metacpan or  search on metacpan

lib/Mac/FSEvents.pm  view on Meta::CPAN

                                    # optionally specify an arrayref of multiple paths
      latency       => 2.0,         # optional, time to delay before returning events
      since         => 451349510,   # optional, return events from this eventId
      watch_root    => 1,           # optional, fire events if the watched path changes
      ignore_self   => 1,           # optional, ignore events from this process
      file_events   => 1,           # optional, fire events on files instead of dirs
  );
  ### OR
  my $fs = Mac::FSEvents->new( '/' ); # Only specify the path

  my $fh = $fs->watch;

  # Select on this filehandle, or use an event loop:
  my $sel = IO::Select->new($fh);
  while ( $sel->can_read ) {
      my @events = $fs->read_events;
      for my $event ( @events ) {
          printf "Directory %s changed\n", $event->path;
      }
  }

  # or use blocking polling:
  while ( my @events = $fs->read_events ) {
      ...
  }

  # stop watching
  $fs->stop;

=head1 DESCRIPTION

This module implements the FSEvents API present in Mac OSX 10.5 and later.
It enables you to watch a large directory tree and receive events when any
changes are made to directories or files within the tree.

Event monitoring occurs in a separate C thread from the rest of your application.

=head1 METHODS

=over 4

=item B<new> ( { ARGUMENTS } )

=item B<new> ( ARGUMENTS )

=item B<new> ( PATH )

Create a new watcher. C<ARGUMENTS> is a hash or hash reference with the following keys:

=over 8

=item path

Required. A plain string or arrayref of strings of directories to watch. All
subdirectories beneath these directories are watched.

=item latency

Optional.  The number of seconds the FSEvents service should wait after hearing
about an event from the kernel before passing it along.  Specifying a larger value
may result in fewer callbacks and greater efficiency on a busy filesystem.  Fractional
seconds are allowed.

Default: 2.0

=item since

Optional.  A previously obtained event ID may be passed as the since argument.  A
notification will be sent for every event that has happened since that ID.  This can
be useful for seeing what has changed while your program was not running.

=item ignore_self

(Only available on OS X 10.6 or greater)

Don't send events triggered by the current process. Useful if you are also modifying
files in the watch list.

=item file_events

(Only available on OS X 10.7 or greater)

Send events for files. By default, only directory-level events are generated,
and may be coelesced if they happen simultaneously. With this flag, an event
will be generated for every change to a file.

=item watch_root

Request notifications if the location of the paths being watched change. For example,
if there is a watch for C</foo/bar>, and it is renamed to C</foo/buzz>, an event will
be generated with the C<root_changed> flag set.

=item flags

Optional.  Sets the flags provided to L<FSEventStreamCreate>.  In order to
import the flag constants, you must provide C<:flags> to C<use Mac::FSEvents>.

This method of setting flags is discouraged in favor of using the constructor argument,
above.

The following flags are supported:

=over 8

=item NONE

No flags. The default.

=item WATCH_ROOT

Set by the C<watch_root> constructor argument.

=item IGNORE_SELF

Set by the C<ignore_self> constructor argument.

=item FILE_EVENTS

Set by the C<file_events> constructor argument.

=back