/ 
AnyEvent-Tools-0.01
River stage one • 1 direct dependent • 1 total dependent
/ AnyEvent::Tools

NAME

AnyEvent::Tools - instrument collection for AnyEvent.

SYNOPSIS

Mutexes

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
        });

    });
}

Read/Write mutexes

# 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
        }

    });
}

FOREACHES

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
        \@array,
        sub {
            my ($guard, $element, $index, $first_flag, $last_flag) = @_;

            ... # do something with $array[$index];
        },
        sub {
            ... # do something after all cycles

        };

async_foreach
        \%hash,
        sub {
            my ($guard, $key, $value, $first_flag, $last_flag) = @_;

            ... # do something with $hash{$key};
        },
        sub {
            my ($guard) = @_;

            ... # do something after all cycles

        };

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.

FUNCTIONS

mutex

returns unlocked mutex.

This object provides the following methods:

lock(CODEREF)

You declare that You want to lock mutex. When it is possible the mutex will be locked and Your callback will be called.

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.

Example:

$mutex->lock(sub {
    my $guard = shift;
    ... # do something

    undef $guard;       # unlock mutex
});

The callback receives a guard (see AnyEvent::Util::guard) which unlocks the mutex. Hold the guard while You need locked resourse.

is_locked

Returns TRUE if mutex is locked now. Usually You shoudn't use the function.

rw_mutex

returns unlocked read-write mutex.

This object provides the following methods:

rlock(CODEREF)

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.

There may be a lot of read processes running simultaneously that catch the lock.

wlock(CODEREF).

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.

There may be only one write process that catches the lock.

Both callbacks receive a guard to hold the mutex locked.

is_locked

Returns TRUE if the mutex has 'read' or 'write' lock status.

is_rlocked

Returns TRUE if the mutex has 'read' lock status.

Important: this method returns FALSE if the mutex is wlocked (is_wlocked), so if You want to know if any lock is set, use the function is_locked.

is_wlocked

Returns TRUE if the mutex has 'write' lock status.

Usually You shoudn't use is_[rw]?locked functions.

async_repeat(COUNT, CALLBACK [, DONE_CALLBACK ])

Repeats calling Your callback(s).

async_repeat 10, sub { $count++ };
async_repeat 20, sub { $count++ }, sub { $done = 1 };

The function async_repeat returns the guard if it is called in non-void context. Destroy the guard if You want to cancel iterations.

Iteration callback receives the following arguments:

1. guard

The next iteration will not start until the guard is destroyed.

2. iteration number

The number of current iteration.

3. first_flag

TRUE on the first iteration.

4. last_flag

TRUE on the last iteration.

async_for(HASREF|ARRAYREF, CALLBACK [, DONE_CALLBACK ]);

Calls Your callbacks for each array or hash element.

The function returns the guard if it is called in non-void context. Destroy the guard if You want to cancel iterations.

If You process an array using the function, iteration callback will receive the following arguments:

1. guard

The next iteration will not start until the guard is destroyed.

2. element

Next array element.

3. index

Index of array element.

4. first_flag

The iteration is the first.

5. last_flag

The iteration is the last.

If You process a hash using the function, iteration callback will receive the following arguments:

1. guard

The next iteration will not start until the guard is destroyed.

2. key
3. value
4. first_flag

The iteration is the first.

5. last_flag

The iteration is the last.

async_rfor(HASREF|ARRAYREF, CALLBACK [, DONE_CALLBACK ]);

The same as async_for but has reverse sequence.

SEE ALSO

AnyEvent

AUTHOR

Dmitry E. Oboukhov, <unera@debian.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Dmitry E. Oboukhov

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.

VCS

The project is placed in my git repo. See here: http://git.uvw.ru/?p=anyevent-tools;a=summary