NAME

POEx::Inotify - inotify interface for POE

SYNOPSIS

    use strict;

    use POE;
    use POEx::Inotify;

    POEx::Inotify->new( alias=>'notify' );

    POE::Session->create(
        package_states => [ 
                'main' => [ qw(_start notification) ],
        ],
    );

    $poe_kernel->run();
    exit 0;

    sub _start {
        my( $kernel, $heap ) = @_[ KERNEL, HEAP ];

        $kernel->post( 'notify' => monitor => {
                path => '.',
                mask  => IN_CLOSE_WRITE,
                event => 'notification',
                args => [ $args ]
             } );
        return;  
    }

    sub notification {
        my( $kernel, $e, $args ) = @_[ KERNEL, ARG0, ARG1];
        print "File ready: ", $e->fullname, "\n";
        $kernel->post( notify => 'shutdown' );
        return;
    }

DESCRIPTION

POEx::Inotify is a simple interface to the Linux file and directory change notification interface, also called inotify.

It can monitor an existing directory for new files, deleted files, new directories and more. It can monitor an existing file to see if it changes, is deleted or moved.

METHODS

spawn

    POEx::Inotify->spawn( %options );

Creates the POEx::Inotify session. It takes a number of arguments, all of which are optional.

alias

The session alias to register with the kernel. Defaults to inotify.

options

A hashref of POE::Session options that are passed to the component's session creator.

EVENTS

monitor

    $poe_kernel->call( inotify => 'monitor', $arg );

Starts monitoring the specified path for the specified types of changes.

Accepts one argument, a hashref containing the following keys:

path

The filesystem path to the directory to be monitored. Mandatory.

mask

A mask of events that you wish to monitor. May be any of the following constants (exported by Linux::Inotify2) ORed together. Defaults to IN_ALL_EVENTS.

IN_ACCESS

object was accessed

IN_MODIFY

object was modified

IN_ATTRIB

object metadata changed

IN_CLOSE_WRITE

writable fd to file / to object was closed

IN_CLOSE_NOWRITE

readonly fd to file / to object closed

IN_OPEN

object was opened

IN_MOVED_FROM

file was moved from this object (directory)

IN_MOVED_TO

file was moved to this object (directory)

IN_CREATE

file was created in this object (directory)

IN_DELETE

file was deleted from this object (directory)

IN_DELETE_SELF

object itself was deleted

IN_MOVE_SELF

object itself was moved

IN_ALL_EVENTS

all of the above events

IN_ONESHOT

only send event once

IN_ONLYDIR

only watch the path if it is a directory

IN_DONT_FOLLOW

don't follow a sym link

IN_MASK_ADD

not supported with the current version of this module

IN_CLOSE

same as IN_CLOSE_WRITE | IN_CLOSE_NOWRITE

IN_MOVE

same as IN_MOVED_FROM | IN_MOVED_TO

event

The name of the event handler in the current session to post changes back to. Mandatory.

The event handler will receive an Linux::Inotify2::Event as its first argument. Other arguments are those specified by "args".

args

An arrayref of arguments that will be passed to the event handler.

Example

    use Linux::Inotify2;

    my $dir = '/var/ftp/incoming';

    my $arg = {
            path => $path
            mask => IN_DELETE|IN_CLOSE,
            event => 'uploaded',
            args  => [ $dir ]
        };
    $poe_kernel->call( inotify => 'monitor', $arg );

    sub uploaded 
    {
        my( $e, $path ) = @_[ARG0, ARG1];
        warn $e->fullname, " was uploaded to $path";
    }

unmonitor

    $poe_kernel->call( inotify => 'unmonitor', $arg );

Ends monitoring of the specified path for the current session.

Accepts one argument, a hashref containing the following keys:

path

The filesystem path to the directory to to stop monitoring. Mandatory.

event

Name of the monitor event that was used in the original "monitor" call. Mandatory. You may use * to unmonitor all events for the current session.

Note

Multiple sessions may monitor the same path at the same time. A single session may monitor multiple paths. However, if a single session is monitoring the same path multiple times it must use different events to distinguish them.

shutdown

    $poe_kernel->call( inotify => 'shutdown' );
    # OR
    $poe_kernel->signal( $poe_kernel => 'shutdown' );
 

Shuts down the component gracefully. All monitored paths will be closed. Has no arguments.

SEE ALSO

POE, Linux::Inotify2.

This module's API was heavily inspired by POE::Component::Win32::ChangeNotify.

AUTHOR

Philip Gwyn, <gwyn -at- cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Philip Gwyn. All rights reserved.

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.8 or, at your option, any later version of Perl 5 you may have available.

cpanm POEx::Inotify

perl -MCPAN -e shell
install POEx::Inotify