Module to monitor a file system for modifications which is AnyEvent compatible
Perl Shell
Pull request Compare This branch is 52 commits behind mvgrimes:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


    AnyEvent::Filesys::Notify - An AnyEvent compatible module to monitor
    files/directories for changes

    version 0.22

        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

    This module provides a cross platform interface to monitor files and
    directories within an AnyEvent event loop. The heavy lifting is done by
    Linux::INotify2 or Mac::FSEvents 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 AnyEvent::Filesys::Notify::Events.

    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 AnyEvent::Filesys::Notify::Role::Fallback implementation.

        Specifies the latency for Mac::FSEvents for the
        "AnyEvent::Filesys::Notify::Role::FSEvents" implementation.

        Ignored for the "AnyEvent::Filesys::Notify::Role::Inotify2"

            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
        AnyEvent::Filesys::Notify::Events. Required.

            backend => 'Fallback',
            backend => 'FreeBSD',
            backend => '+My::Filesys::Notify::Role::Backend',

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

            no_external => 1,

        This is retained for backward compatibility. Using "backend ="
        'Fallback'> is preferred. 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 Linux::INotify2
        nor Mac::FSEvents. Optional.

  INotify2 (Linux)
    Uses Linux::INotify2 to monitor directories. Sets up an "AnyEvent->io"
    watcher to monitor the "$inotify->fileno" filehandle.

  FSEvents (Mac)
    Uses Mac::FSEvents to monitor directories. Sets up an "AnyEvent->io"
    watcher to monitor the "$fsevent->watch" filehandle.

  KQueue (FreeBSD/Mac)
    Uses IO::KQueue to monitor directories. Sets up an "AnyEvent->io"
    watcher to monitor the "IO::KQueue" object.

    WARNING - IO::KQueue and the "kqueue()" system call require an open
    filehandle for every directory and file that is being watched. This
    makes it impossible to watch large directory structures (and inefficient
    to watch moderately sized directories). The use of the KQueue backend is

    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 AnyEvent::Filesys::Notify and defaults to 2.0 seconds.

    This is a very inefficient implementation. Use one of the others if

Why Another Module For File System Notifications
    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: Filesys::Notify::Simple and File::ChangeNotify.

    AnyEvent::Filesys::Notify 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.
    Filesys::Notify::Simple does not supply a non-blocking interface and
    File::ChangeNotify requires you to poll an method for new events. You
    could fork off a process to run Filesys::Notify::Simple and use an event
    handler to watch for notices from that child, or setup a timer to check
    File::ChangeNotify at regular intervals, but both of those approaches
    seem inefficient or overly complex. Particularly, since the underlying
    watcher implementations (Mac::FSEvents and Linux::INotify2) 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, Mac::FSEvents,
    Linux::INotify2, Moose.

    Alternatives to this module Filesys::Notify::Simple, File::ChangeNotify.

    Please report any bugs or suggestions at <>

    Forcing the "IO::KQueue" backend on a Mac does not seem to work. The
    "IO::KQueue" backend seems to be working fine on FreeBSD. I don't have
    the experience or time to fix it on a Mac. I would greatly appreciate
    any help troubleshooting this.

    Thanks to Gasol Wu <> who contributed the FreeBSD
    support for IO::KQueue.

    Mark Grimes, <>

    This software is copyright (c) 2013 by Mark Grimes, <>.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.