The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
POE-Component-DirWatch-Object-0.04
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?

session

Read-only; 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.

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.

dispatch_list

Read-Write; Returns a list of the files enqueued to be processed. Messing with this before 'dispatch' is the preferred way of messing with the list of files to be processed other than filter

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 event.

_poll

Triggered by the poll event this is the re-occurring action. Every time it runs it will search for files, _filter() them, store the matching files as a list and trigger the dispatch event.

_dispatch

Triggered, by the dispatch event this method will iterate through $self->dispatch_list and send a callback event for every file in the dispatch list.

_pause

This is a TODO. email with suggestions as to how you'd like it to work.

_resume

This is a TODO. email with suggestions as to how you'd like it to work.

_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 pause / resume 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, ...])

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

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.