.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "AnyEvent::Tools 3pm" .TH AnyEvent::Tools 3pm "2021-01-06" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" AnyEvent::Tools \- instrument collection for AnyEvent. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .SS "Objects pool" .IX Subsection "Objects pool" .Vb 3 \& use AnyEvent::Tools qw(pool); \& my $dbh1 = ... \& my $dbh2 = ... \& \& ... \& my $dbhN = ... \& \& \& my $pool = pool($dbh1, $dbh2, $dbh3, ..., $dbhN); \& \& # later \& ... \& $pool\->get(sub { \& my ($guard, $dbh) = @_; \& ... # Enjoy $dbh here \& \& undef $guard; # the other process can use the $dbh \& }); .Ve .SS "Mutexes" .IX Subsection "Mutexes" .Vb 1 \& use AnyEvent::Tools qw(mutex); \& \& my $dbh = new AnyEvent::DBI(bla); \& my $mutex_dbh = mutex; \& \& \& sub some_callback() { \& ... \& $mutex_dbh\->lock(sub { \& my ($mutex_guard) = @_; \& \& $dbh\->exec("SELECT * FROM table", sub { \& my ($dbh, $rows, $rv) = @_; \& ... \& \& undef $mutex_guard; # unlock mutex \& }); \& \& }); \& } .Ve .SS "Read/Write mutexes" .IX Subsection "Read/Write mutexes" .Vb 2 \& # Your data \& my @shared_data; \& \& use AnyEvent::Tools qw(rw_mutex); \& use AnyEvent::Tools qw(:mutex); # mutex and rw_mutex \& my $rw_mutex = rw_mutex; \& \& sub some_callback() { \& ... \& $rw_mutex\->rlock(sub { \& my ($mutex_guard) = @_; \& \& ... \& \& # You can read Your data here \& ... \& # later \& ... = sub { \& # done \& \& undef $mutex_guard; # unlock mutex \& } \& \& }); \& } \& \& sub other_callback() { \& ... \& $rw_mutex\->wlock(sub { \& my ($mutex_guard) = @_; \& ... \& \& # You can write Your data here \& ... \& # later \& ... = sub { \& # done \& \& undef $mutex_guard; # unlock mutex \& } \& \& }); \& } .Ve .SS "Foreaches" .IX Subsection "Foreaches" .Vb 1 \& use AnyEvent::Tools qw(:foreach); \& \& async_repeat $count, \& sub { \& my ($guard, $iteration, $first_flag, $last_flag) = @_; \& \& ... do something $count times \& }, \& sub { \& ... # do something after all cycles \& }; \& \& \& async_foreach \& \e@array, \& sub { \& my ($guard, $element, $index, $first_flag, $last_flag) = @_; \& \& ... # do something with $array[$index]; \& }, \& sub { \& ... # do something after all cycles \& \& }; \& \& async_foreach \& \e%hash, \& sub { \& my ($guard, $key, $value, $first_flag, $last_flag) = @_; \& \& ... # do something with $hash{$key}; \& }, \& sub { \& my ($guard) = @_; \& \& ... # do something after all cycles \& \& }; .Ve .SS "Buffers" .IX Subsection "Buffers" .Vb 4 \& use AnyEvent::Tools \*(Aq:pool\*(Aq; # pool and buffer \& use AnyEvent::Tools qw(buffer); # buffer only \& my $buffer = buffer; \& $buffer\->on_flush( sub { ($guard, $objects_aref) = @_; .... }); \& \& ... \& \& $buffer\->push($obj1); \& $buffer\->push($obj2); \& $buffer\->push($obj3); \& $buffer\->push($obj4); \& \& $buffer\->flush; \& \& \& # autoflush after 30 second \& $buffer\->interval(30); \& \& # autoflush if it contains more than 50 elements \& $buffer\->size(50); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" In spite of event machine is started as one process, You may want to share one resource between a lot of subprocesses. Sometimes You also want to do something with a lot of data placed in hashes/arrays. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "mutex" .IX Subsection "mutex" returns unlocked mutex. .PP This object provides the following methods: .PP \fIlock(\s-1CODEREF\s0)\fR .IX Subsection "lock(CODEREF)" .PP You declare that You want to lock mutex. When it is possible the mutex will be locked and Your callback will be called. .PP If the method is called in non-void context it returns guard object which can be destroyed. So if You want You can cancel Your lockrequest. .PP Example: .PP .Vb 3 \& $mutex\->lock(sub { \& my $guard = shift; \& ... # do something \& \& undef $guard; # unlock mutex \& }); .Ve .PP The callback receives a guard (see AnyEvent::Util#guard) which unlocks the mutex. Hold the guard while You need locked resourse. .PP \fIis_locked\fR .IX Subsection "is_locked" .PP Returns \fB\s-1TRUE\s0\fR if mutex is locked now. Usually You shoudn't use the function. .SS "rw_mutex" .IX Subsection "rw_mutex" returns unlocked read-write mutex. .PP This object provides the following methods: .PP \fIrlock(\s-1CODEREF\s0)\fR .IX Subsection "rlock(CODEREF)" .PP You declare that You want to lock mutex for reading. When it is possible the mutex will be locked and Your callback will be called. .PP There may be a lot of read processes running simultaneously that catch the lock. .PP \fIwlock(\s-1CODEREF\s0).\fR .IX Subsection "wlock(CODEREF)." .PP You declare that You want to lock mutex for writing. When it is possible the mutex will be locked and Your callback will be called. .PP There may be only one write process that catches the lock. .PP Both callbacks receive a guard to hold the mutex locked. .PP \fIrlock_limit(\s-1NUMBER\s0)\fR .IX Subsection "rlock_limit(NUMBER)" .PP Get/Set count limit for rlock. If an rlock request is come and this limit is reached the request will be queued. .PP \fIis_locked\fR .IX Subsection "is_locked" .PP Returns \fB\s-1TRUE\s0\fR if the mutex has 'read' or 'write' lock status. .PP \fIis_rlocked\fR .IX Subsection "is_rlocked" .PP Returns \fB\s-1TRUE\s0\fR if the mutex has 'read' lock status. .PP \&\fBImportant\fR: this method returns \fB\s-1FALSE\s0\fR if the mutex is wlocked (is_wlocked), so if You want to know if any lock is set, use the function is_locked. .PP \fIis_wlocked\fR .IX Subsection "is_wlocked" .PP Returns \fB\s-1TRUE\s0\fR if the mutex has 'write' lock status. .PP Usually You shoudn't use is_[rw]?locked functions. .SS "async_repeat(\s-1COUNT, CALLBACK\s0 [, \s-1DONE_CALLBACK\s0 ])" .IX Subsection "async_repeat(COUNT, CALLBACK [, DONE_CALLBACK ])" Repeats calling Your callback(s). .PP .Vb 2 \& async_repeat 10, sub { $count++ }; \& async_repeat 20, sub { $count++ }, sub { $done = 1 }; .Ve .PP The function async_repeat returns the guard if it is called in non-void context. Destroy the guard if You want to cancel iterations. .PP Iteration callback receives the following arguments: .IP "1. guard" 4 .IX Item "1. guard" The next iteration will not start until the guard is destroyed. .IP "2. iteration number" 4 .IX Item "2. iteration number" The number of current iteration. .IP "3. first_flag" 4 .IX Item "3. first_flag" \&\s-1TRUE\s0 on the first iteration. .IP "4. last_flag" 4 .IX Item "4. last_flag" \&\s-1TRUE\s0 on the last iteration. .SS "async_for(HASREF|ARRAYREF, \s-1CALLBACK\s0 [, \s-1DONE_CALLBACK\s0 ]);" .IX Subsection "async_for(HASREF|ARRAYREF, CALLBACK [, DONE_CALLBACK ]);" Calls Your callbacks for each array or hash element. .PP The function returns the guard if it is called in non-void context. Destroy the guard if You want to cancel iterations. .PP If You process an array using the function, iteration callback will receive the following arguments: .IP "1. guard" 4 .IX Item "1. guard" The next iteration will not start until the guard is destroyed. .IP "2. element" 4 .IX Item "2. element" Next array element. .IP "3. index" 4 .IX Item "3. index" Index of array element. .IP "4. first_flag" 4 .IX Item "4. first_flag" The iteration is the first. .IP "5. last_flag" 4 .IX Item "5. last_flag" The iteration is the last. .PP If You process a hash using the function, iteration callback will receive the following arguments: .IP "1. guard" 4 .IX Item "1. guard" The next iteration will not start until the guard is destroyed. .IP "2. key" 4 .IX Item "2. key" .PD 0 .IP "3. value" 4 .IX Item "3. value" .IP "4. first_flag" 4 .IX Item "4. first_flag" .PD The iteration is the first. .IP "5. last_flag" 4 .IX Item "5. last_flag" The iteration is the last. .SS "async_rfor(HASREF|ARRAYREF, \s-1CALLBACK\s0 [, \s-1DONE_CALLBACK\s0 ]);" .IX Subsection "async_rfor(HASREF|ARRAYREF, CALLBACK [, DONE_CALLBACK ]);" The same as async_for but has reverse sequence. .SS "pool" .IX Subsection "pool" Returns the object that incapsulates object collection. You can cacth one object of the collection using the method: .PP \fIget($callback)\fR .IX Subsection "get($callback)" .PP .Vb 1 \& $pool\->get(sub { my ($guard, $object) = @_; ... }); .Ve .PP If there is a free object in the pool, Your callback will be called. The callback receives also a guard. Hold the guard while You use the object. .PP There are also a few methods: .PP \fIpush($object);\fR .IX Subsection "push($object);" .PP .Vb 1 \& my $id = $pool\->push($dbh); .Ve .PP Add an object in pool. Returns the object's identifier. You can use that to delete the object from pool: .PP \fIdelete($id)\fR .IX Subsection "delete($id)" .PP .Vb 2 \& $pool\->delete($id); \& $pool\->delete($id, sub { # on_delete }); .Ve .PP Deletes object from pool. .PP \&\fBNote\fR: The function will croak if it receives an ivalid object id. .SS "buffer" .IX Subsection "buffer" Returns the buffer object. Can receive a few named arguments: interval, size, on_flush. They are the same that the following functions. .PP It provides the following methods: .PP \fIpush\fR .IX Subsection "push" .PP Push the object into buffer. .PP .Vb 3 \& $buffer\->push(123); \& $buffer\->push($obj); \& $buffer\->push(1,2,3); .Ve .PP \fIunshift\fR .IX Subsection "unshift" .PP Unshift the object into buffer .PP .Vb 2 \& $buffer\->unshift(123); \& $buffer\->unshift(1,2,3); .Ve .PP \fIunshift_back\fR .IX Subsection "unshift_back" .PP The function can be called only inside on_flush handler (until its guard destroyed). It can be used to unshift non-flushed data (for example: if an error was occured) back to buffer. Receives \fB\s-1ARRAYREF\s0\fR (like on_flush's callback). .PP \fIflush\fR .IX Subsection "flush" .PP Flush buffer (calls on_flush function) .PP \fIinterval\fR .IX Subsection "interval" .PP Get/Set autoflush interval (zero == periodical autoflush is disabled) .PP \fIsize\fR .IX Subsection "size" .PP Get/Set buffer size (zero == buffer overflow autoflush is disabled) .PP \fIunique_cb\fR .IX Subsection "unique_cb" .PP If the callback is defined it will be called for each pushing element to determine its key value. If the key has already appeared since last flush the element will be ignored. So buffer will contain only unique objects. .PP \fIon_flush\fR .IX Subsection "on_flush" .PP Set flush callback. It will be called if flush function is called or buffer overflow is detected or timeout is exceeded. .PP The callback receives two arguments: .IP "guard" 4 .IX Item "guard" If You hold the guard, and user calls flush, flushing will be delayed. .IP "arrayref" 4 .IX Item "arrayref" Reference to object list that were accumulated. .SH "SEE ALSO" .IX Header "SEE ALSO" AnyEvent .SH "AUTHOR" .IX Header "AUTHOR" Dmitry E. Oboukhov, .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2011 by Dmitry E. Oboukhov .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available. .SH "VCS" .IX Header "VCS" The project is placed in my git repo. See here: