-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME
191 lines (150 loc) · 6.59 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
NAME
POE::Component::DirWatch - POE directory watcher
SYNOPSIS
use POE::Component::DirWatch;
my $watcher = POE::Component::DirWatch->new
(
alias => 'dirwatch',
directory => '/some_dir',
filter => sub { $_[0]->is_file ? $_[0] =~ /\.gz$/ : 1 },
dir_callback => sub{ ... },
file_callback => sub{ ... },
interval => 1,
);
$poe_kernel->run;
DESCRIPTION
POE::Component::DirWatch watches a directory for files or directories.
Upon finding either it will invoke a user-supplied callback function
depending on whether the item is a file or directory.
ASYNCHRONOUS IO SUPPORT
This object supports asynchronous IO access using IO::AIO. At load time,
the class will detect whether IO::AIO is present in the host system and,
if it is present, apply the POE::Component::DirWatch::Role::AIO role to
the current class, adding the "aio" attribute, the <aio_callback> event,
and replacing "_poll" with an asynchronous version. If you do not wish
to use AIO you can specify so with he "no_aio" flag like this:
use POE::Component::DirWatch (no_aio => 1);
ATTRIBUTES
alias
Read only alias for the DirWatch session. Defaults to "dirwatch" if not
specified. You can NOT rename a session at runtime.
directory
Read-write, required. A Path::Class::Dir object for the directory
watched. Automatically coerces strings into Path::Class::Dir objects.
interval
Required read-write integer representing interval between the end of a
poll event and the scheduled start of the next. Defaults to 1.
file_callback
has_file_callback - predicate
clear_file_callback - clearer
Optional read-write code reference to call when a file is found. The
code reference will passed a single argument, a Path::Class::File object
representing the file found. It usually makes most sense to process the
file and remove it from the directory to avoid duplicate processing
dir_callback
has_dir_callback - predicate
clear_dir_callback - clearer
Optional read-write code reference to call when a directory is found.
The code reference will passed a single argument, a Path::Class::Dir
object representing the directory found.
filter
has_filter - predicate
clear_filter - clearer
An optional read-write code reference that, if present, will be called
for each item in the watched directory. The code reference will passed a
single argument, a Path::Class::File or Path::Class::Dir object
representing the file/dir found. The code should return true if the
callback should be called and false if the file should be ignored.
next_poll
has_next_poll - predicate
clear_next_poll - clearer
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.
OBJECT METHODS
new( \%attrs)
See SYNOPSIS and ATTRIBUTES.
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.
resume [$when]
Synchronous call to _resume. This just posts an immediate _resume event
to the kernel.
shutdown
Convenience method that posts a FIFO shutdown event.
meta
See Moose;
EVENT HANDLING METHODS
These methods are not part of the public interface of this class, and
expect to be called from whithin POE with the standard positional
arguments. Use them at your own risk.
_start
Runs when "$poe_kernel->run" is called to 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 items in the directory and call the
appropriate callback.
_file_callback
Will execute the "file_callback" code reference, if any.
_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.
#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.
TODO
More examples
More tests
ChangeNotify support (patches welcome!)
SEE ALSO
POE::Session, POE::Component, Moose, POE,
The git repository for this project can be found in on github,
<http://github.com/arcanez/poe-component-dirwatch/>
AUTHOR
Guillermo Roditi, <[email protected]>
BUGS
Please report any bugs or feature requests to
"bug-poe-component-dirwatch at rt.cpan.org", or through the web
interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-DirWatch>.
I will be notified, and then you'll automatically be notified of
progress on your bug as I make changes.
ACKNOWLEDGEMENTS
#poe & #moose on irc.perl.org
Matt S Trout
Rocco Caputo
Charles Reiss
Stevan Little
Eric Cholet
COPYRIGHT
Copyright 2006-2008 Guillermo Roditi. This is free software; you may
redistribute it and/or modify it under the same terms as Perl itself.