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,
# OR
callback => [$obj, 'some_sub'], #if you want $obj->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.
Apparently the original DirWatch no longer exists. Yes, I know Moose is a bit heavy but I don't really care. The original is still on BackPAN if you don't like my awesome replacement.
Public Methods
new( \%attrs)
See SYNOPSIS and Accessors / Attributes below.session
Returns a reference to the actual POE session. Please avoid this unless you are subclassing. Even then it is recommended that it is always used as $watcher->session->method because copying the object reference around could create a problem with lingering references.
pause [$until]
Synchronous call to _pause. This just posts an immediate _pause event to the kernel. Safe for use outside of POEish land (doesnt use @_[KERNEL, ARG0...])
resume [$when]
Synchronous call to _resume. This just posts an immediate _resume event to the kernel. Safe for use outside of POEish land (doesnt use @_[KERNEL, ARG0...])
shutdown
Convenience method that posts a FIFO shutdown event.
Accessors / Attributes
alias
The alias for the DirWatch session. Defaults to dirwatch if not specified. You can NOT rename a session at runtime.
directory
This is a required argument during new. The path of the directory to watch.
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
This is a required argument during new. The code to be called when a matching file is found.
The code called will be passed 2 arguments, the $filename and $filepath. This may take 2 different values. A 2 element arrayref or a single coderef. When given an arrayref the first item will be treated as an object and the second as a method name. See the SYNOPSYS.
It usually makes most sense to process the file and remove it from the directory.
#Example
callback => sub{ my($filename, $fullpath) = @_ }
# OR
callback => [$obj, 'mymethod']
#Where my method looks like:
sub mymethod {
my ($self, $filename, $fullpath) = @_;
...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] }.
next_poll
The ID of the alarm for the next scheduled poll, if any. Has clearer and predicate methods named clear_next_poll and has_next_poll. Please note that clearing the next_poll just clears the next poll id, it does not remove the alarm, please use pause for that.
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.
_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 event.
_poll
Triggered by the poll event this is the re-occurring action. _poll will use get a list of all files in the directory and call _aio_callback with the list of filenames (if any)
I promise I will make this async soon, it's just that IO::AIO doesnt work on FreeBSD.
_aio_callback
Schedule the next poll and dispatch any files found.
_dispatch
Triggered by the dispatch event, it recieves a filename in ARG0, it then proceeds to run the file through the filter and schedule a callback.
_callback
Triggered by the callback event, it derefernces the argument list that is passed to it in ARG0 and calls the appropriate coderef or object-method pair with $filename and $fullpath in @_;
_pause [$until]
Triggered by the _pause event this method will remove the alarm scheduling the next directory poll. It takes an optional argument of $until, which dictates when the polling should begin again. If $until is an integer smaller than the result of time() it will treat $until as the number of seconds to wait before polling. If $until is an integer larger than the result of time() it will treat $until as an epoch timestamp and schedule the poll alarm accordingly.
#these two are the same thing
$watcher->pause( time() + 60);
$watcher->pause( 60 );
#this is one also the same
$watcher->pause;
$watcher->resume( 60 );_resume [$when]
Triggered by the _resume event this method will remove the alarm scheduling the next directory poll (if any) and schedule a new poll alarm. It takes an optional argument of $when, which dictates when the polling should begin again. If $when is an integer smaller than the result of time() it will treat $until as the number of seconds to wait before polling. If $until is an integer larger than the result of time() it will treat $when as an epoch timestamp and schedule the poll alarm accordingly. If not specified, the alarm will be scheduled with a delay of zero.
_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
Test Happiness.
TODO
IO::AIOis b0rken on FreeBSD so I can't add support until it works- Use
Win32::ChangeNotifyon Win32 platforms for better performance. - Allow user to change the directory watched during runtime.
- ImproveDocs
- Write some tests. (after I read PDN and learn how)
- 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, ...])
Also check out POE::Component::DirWatch::Object::NewFile for a simple example of how to extend functionality.
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)
Currently maintained by Robert Rothenberg <rrwo@thermeon.com>
BUGS
Holler?
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.
CONTRIBUTING
The git repository can be found at https://github.com/robrwo/POE-Component-DirWatch-Object
Bugs can be reported http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-DirWatch-Object
ACKNOWLEDGEMENTS
People who answered way too many questions from an inquisitive idiot:
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.