/ 
POE-Component-DirWatch-Object-0.10
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,
     # 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::AIO is b0rken on FreeBSD so I can't add support until it works
Use Win32::ChangeNotify on 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)

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.

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
Stevan Little

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.