| AnyEvent::Filesys::Notify - An AnyEvent compatible module to monitor files/directories for changes |
AnyEvent::Filesys::Notify - An AnyEvent compatible module to monitor files/directories for changes
use AnyEvent::Filesys::Notify;
my $notifier = AnyEvent::Filesys::Notify->new(
dirs => [ qw( this_dir that_dir ) ],
interval => 2.0, # Optional depending on underlying watcher
filter => sub { shift !~ /\.(swp|tmp)$/ },
cb => sub {
my (@events) = @_;
# ... process @events ...
},
);
# enter an event loop, see AnyEvent documentation
Event::loop();
This module provides a cross platform interface to monitor files and directories within an AnyEvent event loop. The heavy lifting is done by the Linux::INotify2 manpage or the Mac::FSEvents manpage on their respective O/S. A fallback which scans the directories at regular intervals is include for other systems. See IMPLEMENTATIONS for more on the backends.
Events are passed to the callback (specified as a CodeRef to cb in the
constructor) in the form of the AnyEvent::Filesys::Notify::Event manpages.
new()A constructor for a new AnyEvent watcher that will monitor the files in the given directories and execute a callback when a modification is detected. No action is take until a event loop is entered.
Arguments for new are:
dirs => [ '/var/log', '/etc' ],
An ArrayRef of directories to watch. Required.
interval => 1.5, # seconds
Specifies the time in fractional seconds between file system checks for the the AnyEvent::Filesys::Notify::Role::Fallback manpage implementation.
Specifies the latency for the Mac::FSEvents manpage for the
AnyEvent::Filesys::Notify::Role::Mac implementation.
Ignored for the AnyEvent::Filesys::Notify::Role::Linux implementation.
filter => qr/\.(ya?ml|co?nf|jso?n)$/,
filter => sub { shift !~ /\.(swp|tmp)$/,
A CodeRef or Regexp which is used to filter wanted/unwanted events. If this is a Regexp, we attempt to match the absolute path name and filter out any that do not match. If a CodeRef, the absolute path name is passed as the only argument and the event is fired only if there sub returns a true value.
cb => sub { my @events = @_; ... },
A CodeRef that is called when a modification to the monitored directory(ies) is
detected. The callback is passed a list of
the AnyEvent::Filesys::Notify::Event manpages. Required.
no_external => 1,
Force the use of the Fallback watcher implementation. This is not encouraged as the Fallback implement is very inefficient, but it does not require either the Linux::INotify2 manpage nor the Mac::FSEvents manpage. Optional.
Uses the Linux::INotify2 manpage to monitor directories. Sets up an AnyEvent->io
watcher to monitor the $inotify->fileno filehandle.
Uses the Mac::FSEvents manpage to monitor directories. Sets up an AnyEvent->io
watcher to monitor the $fsevent->watch filehandle.
A simple scan of the watched directories at regular intervals. Sets up an
AnyEvent->timer watcher which is executed every interval seconds
(or fractions thereof). interval can be specified in the constructor to
the AnyEvent::Filesys::Notify manpage and defaults to 2.0 seconds.
This is a very inefficient implementation. Use one of the others if possible.
At the time of writing there were several very nice modules that accomplish the task of watching files or directories and providing notifications about changes. Two of which offer a unified interface that work on any system: the Filesys::Notify::Simple manpage and the File::ChangeNotify manpage.
the AnyEvent::Filesys::Notify manpage exists because I need a way to simply tie the functionality those modules provide into an event framework. Neither of the existing modules seem to work with well with an event loop. the Filesys::Notify::Simple manpage does not supply a non-blocking interface and the File::ChangeNotify manpage requires you to poll an method for new events. You could fork off a process to run the Filesys::Notify::Simple manpage and use an event handler to watch for notices from that child, or setup a timer to check the File::ChangeNotify manpage at regular intervals, but both of those approaches seem inefficient or overly complex. Particularly, since the underlying watcher implementations (the Mac::FSEvents manpage and the Linux::INotify2 manpage) provide a filehandle that you can use and IO event to watch.
This is not slight against the authors of those modules. Both are well respected, are certainly finer coders than I am, and built modules which are perfect for many situations. If one of their modules will work for you by all means use it, but if you are already using an event loop, this module may fit the bill.
Modules used to implement this module AnyEvent, the Mac::FSEvents manpage, the Linux::INotify2 manpage, Moose.
Alternatives to this module the Filesys::Notify::Simple manpage, the File::ChangeNotify manpage.
Please report any bugs or suggestions at http://rt.cpan.org/
Mark Grimes, <mgrimes@cpan.org>
Copyright (C) 2009 by Mark Grimes
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.
| AnyEvent::Filesys::Notify - An AnyEvent compatible module to monitor files/directories for changes |