/ 
POE-Component-DirWatch-Object-0.01
River stage one • 1 direct dependent • 1 total dependent
/ POE::Component::DirWatch::Object

NAME

POE::Component::DirWatch::Object - POE directory watcher object

SYNOPSIS

use POE::Component::DirWatch::Object;

#$watcher is a PoCo::DW:Object 
my $watcher = POE::Component::DirWatch::Object->new
  (
   alias      => 'dirwatch',
   directory  => '/some_dir',
   filter     => sub { $_[0] =~ /\.gz$/ && -f $_[1] },
   callback   => \&some_sub,
   interval   => 1,
  );

$poe_kernel->run;

DESCRIPTION

POE::Component::DirWatch::Object watches a directory for files. Upon finding a file it will invoke the user-supplied callback function.

This module was primarily designed as an Moose-based replacement for POE::Component::Dirwatch. While all known functionality of the original is meant to be covered in a similar way there is some subtle differences.

Its primary intended use is processing a "drop-box" style directory, such as an FTP upload directory.

Public Methods

new( \%attrs)

alias

The alias for the DirWatch session. Defaults to dirwatch if not specified.

directory

The path of the directory to watch. This is a required argument.

interval

The interval waited between the end of a directory poll and the start of another. Default to 1 if not specified.

WARNING: This is number NOT the interval between polls. A lengthy blocking callback, high-loads, or slow applications may delay the time between polls. You can see: http://poe.perl.org/?POE_Cookbook/Recurring_Alarms for more info.

callback

A reference to a subroutine that will be called when a matching file is found in the directory.

This subroutine is called with two arguments: the name of the file, and its full pathname. It usually makes most sense to process the file and remove it from the directory.

This is a required argument.

filter

A reference to a subroutine that will be called for each file in the watched directory. It should return a TRUE value if the file qualifies as found, FALSE if the file is to be ignored.

This subroutine is called with two arguments: the name of the file, and its full pathname.

If not specified, defaults to sub { -f $_[1] }.

Accessors Note: You should never have to use any of these unless you are subclassing. For most tasks you should be able to implement any functionality you need without ever dealing with these objects. That being said, hacking is fun.

alias Read-only. Returns the alias of the POE session. Maybe allow a way to rename the session during runtime?

directory Read-only; Returns the directory we are currently watching TODO: allow dir to change during runtime

dir_handle Read-only; Returns a reference to a DirHandle object

filter Read-Write; Returns the coderef being used to filter files.

interval Read-Write; Returns the interval in seconds that the polling routine wait after it is done running and before it runs again. This is NOT the time between the start of polls, it is the time between the end of one poll and the start of another.

callback Read-Write; Returns the coderef being called when a file is found.

Private methods These methods are documented here just in case you subclass. Please do not call them directly. If you are wondering why some are needed it is so Moose's 'before' and 'after' work.

_filter Code provided because it's more explanatory. sub _filter{ return shift->filter->(@_) }

_callback Code provided because it's more explanatory. sub _filter{ return shift->filter->(@_) }

_start Runs when $poe_kernel->run is called. It will create a new DirHandle watching to $watcher->directory, set the session's alias and schedule the first _poll.

_poll This is the re-occurring action. Every time it runs it will search for files, _filter() them, and then _callback() with matches.

_stop Close that filehandle.

_shutdown Delete the heap, remove the alias we are using and remove all set alarms.

BUILD Constructor. create()s a POE::Session and stores it in $self->session.

meta Todo

TODO

Use Win32::ChangeNotify on Win32 platforms for better performance.
Spin the directory polling into an async operation.
Enable suspend / wakeup functionality
Allow user to change the directory watched during runtime.
ImproveDocs
Write some tests. (after I read PDN and learn how)
Figure out why stringifying breaks things so I can add it
Figure out why taint mode fails

Subclassing

Please see Moose for the proper way to subclass this. And please remember to shift $self out of @_ on any functions called by POE directly so that you don't screw up the named @_ positions (@_[KERNEL, HEAP, ...])

SEE ALSO

POE, POE::Session, POE::Component, POE::Component::DirWatch, Moose

AUTHOR

Guillermo Roditi, <groditi@cpan.org>

Based on the POE::Component::Dirwatch code by: Eric Cholet, <cholet@logilune.com> (I also copy pasted some POD)

BUGS

Please report any bugs or feature requests to bug-poe-component-dirwatch-object at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-DirWatch-Object. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc POE::Component::DirWatch::Object

You can also look for information at:

ACKNOWLEDGEMENTS

People who answered way too many questions from an inquisitive idiot:

#PoE & #Moose
Matt S Trout <mst@shadowcatsystems.co.uk>
Rocco Caputo
Charles Reiss

COPYRIGHT

Copyright 2006 Guillermo Roditi. All Rights Reserved. This is free software; you may redistribute it and/or modify it under the same terms as Perl itself.