POEx::Inotify - inotify interface for POE
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; }
POEx::Inotify is a simple interface to the Linux file and directory change notification interface, also called inotify.
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.
POEx::Inotify->spawn( %options );
Creates the POEx::Inotify session. It takes a number of arguments, all of which are optional.
POEx::Inotify
The session alias to register with the kernel. Defaults to inotify.
A hashref of POE::Session options that are passed to the component's session creator.
$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:
The filesystem path to the directory to be monitored. Mandatory.
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_ALL_EVENTS
object was accessed
object was modified
object metadata changed
writable fd to file / to object was closed
readonly fd to file / to object closed
object was opened
file was moved from this object (directory)
file was moved to this object (directory)
file was created in this object (directory always, file in cooked mode)
file was deleted from this object (directory)
object itself was deleted
object itself was moved
all of the above events
only send event once
only watch the path if it is a directory
don't follow a sym link
not supported with the current version of this module
same as IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
same as IN_MOVED_FROM | IN_MOVED_TO
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".
An arrayref of arguments that will be passed to the event handler.
A hashref of mask=>event tupples. You may use events to register multiple callbacks at once. The keys are masks, the values are either a scalar (event in current session), arrayref (first element is an event, next elements are arguments) or hashref (with the keys event and args.
events
event
args
And remember, => will turn a bare word into a string. So use , or () to force the use of a constant.
=>
,
()
{ IN_CLOSE_WRITE => 'file_changed' } # WRONG! { IN_CLOSE_WRITE, 'file_changed' } # OK { IN_CLOSE_WRITE() => 'file_changed' } # OK
One of 2 strings: raw or cooked. Raw mode requires that the monitored path exist prior to calling "monitor"; if the path doesn't exist, an exception is thrown.
raw
cooked
Cooked mode, however, will wait for the path to be created and then start monitoring it. It does this by checking the parent directories and monitoring the deepest one that exists. And if the path is deleted then parent directories are monitored until the path is created again.
Finaly, in cooked mode, IN_CREATE events are generated for the path. These are normaly never generated for files. For directories, which normaly generate IN_CREATE when a file is created, you may check name; it will be '' for the directory creation event.
IN_CREATE
name
''
The default is cooked.
use Linux::Inotify2; my $dir = '/var/ftp/incoming'; # Monitor a single event my $M = { path => $dir, mask => IN_DELETE|IN_CLOSE, event => 'uploaded', args => [ $dir ] }; $poe_kernel->call( inotify => 'monitor', $M ); sub uploaded { my( $e, $dir ) = @_[ARG0, ARG1]; warn $e->fullname, " was uploaded to $dir"; ..... } # monitor multiple events $M = { path => $path events => { (IN_MOVE_TO|IN_CLOSE_WRITE) => 'file_created', (IN_MOVE_FROM|IN_DELETE) => { event => 'file_deleted', args => [ $one, $two ] }, IN_CLOSE_NOWRITE, [ 'file_accessed', $path ] } }; $poe_kernel->call( inotify => 'monitor', $M ); sub file_created { my( $e ) = $_[ARG0]; ..... } sub file_deleted { my( $e, $one, $two ) = $_[ARG0, ARG1, ARG2]; ..... } sub file_accessed { my( $e, $path ) = $_[ARG0, ARG1]; ..... }
$poe_kernel->call( inotify => 'unmonitor', $arg );
Ends monitoring of the specified path for the current session.
The filesystem path to the directory to to stop monitoring. Mandatory.
Name of the monitor event that was used in the original "monitor" call. You may use * to unmonitor all events for the current session.
*
Use this to unregister multiple events at once. This argument may be an arrayref of event names, or a hashref of mask=>event name tupples.
events => \@names, events => { IN_CLOSE_WRITE() => 'event' }
Note that the mask doesn't have to be an exact match to remove an event. For example, if you monitored IN_CLOSE, which is IN_CLOSE_WRITE|IN_CLOSE_NOWRITE, but only use IN_CLOSE_NOWRITE in your unmonitor call, it will still match and unmonitor IN_CLOSE.
IN_CLOSE
IN_CLOSE_WRITE|IN_CLOSE_NOWRITE
IN_CLOSE_NOWRITE
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.
$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.
IN_CREATE_SELF
recursive
Inotify, POE, Linux::Inotify2.
This module's API was heavily inspired by POE::Component::Win32::ChangeNotify.
Philip Gwyn, <gwyn -at- cpan.org>
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.
To install POEx::Inotify, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POEx::Inotify
CPAN shell
perl -MCPAN -e shell install POEx::Inotify
For more information on module installation, please visit the detailed CPAN module installation guide.