NAME

Dancer::Plugin::GearmanXS - a Dancer Gearman::XS client

SYNOPSIS

This plugin allows Dancer to communicate with Gearman servers, requesting they perform a task and return the result.

By default, task parameters are serialised using Storable's nfreeze method. Your Gearman workers will need to agree on the method used to serialize data.

You will need to configure a list of Gearman servers the plugin will be contacting. In your configuration file:

    plugins:
        GearmanXS:
            job_servers:
                - 127.0.0.1
                - 192.168.1.100:12345

The job servers list defaults to 127.0.0.1:4730 if not specified.

In your package/app:

    package MyApp;
    use Dancer;
    use Dancer::Plugin::GearmanXS;
    use YAML;

    # use YAML as serializer rather than Storable
    gearman_serializer => sub {
        Dump(@_);
    };

    get '/' => sub {

        ## using the underlying Gearman::XS interface
        my ($retval,$result) =
            gearman->do(
                'task_name',
                { arg1 => 'val1' },
            );
        );
        # check $retval and use gearman_client->error()

        ## using the simplified interface which serializes for you
        my $res = gearman_do( 'task_name', { arg1 => 'val1' } );

        template index => { result => $result }
    };

Error management can be done via either gearman->error or gearman_error.

If you need access to advanced features like add_task_high_background or set_fail_fn, use the gearman function: it's a Gearman::XS::Client object.

KEYWORDS

gearman

This method gives you direct access to the Gearman::XS::Client instance. See the module's POD for what you could do with it. The other methods are shorthand for more common tasks, but do not provide the same degree of control as accessing the client object directly.

gearman_error

Accesses the error method for the Gearman::XS::Client.

gearman_serializer

This method returns the current serializer subroutine reference. You can pass it a subroutine reference if you would like to use a serializer other than Storable's nfreeze.

gearman_do

Creates, dispatches and waits on a task to complete, returning the result (scalar reference on success, or undef on failure). Uses the gearman_serializer to serialize the argument(s) given. Use gearman_error in case the of failure.

    my $result = gearman_do('add', [1,2]);
    return template error => { error => gearman_error } unless $result;

gearman_background

Creates and dispatches a job to be run in the background, not waiting for any result. Returns undef on failure, or the job handle.

    my $task = gearman_background('update_minicpan',
        ['/opt/minicpan','0755']
    );
    return template error => { error => gearman_error } unless $task;

gearman_add_task

Adds a task to be run in parallel, returning a task object. It does not start executing the task: you will need to call gearman_run_tasks in order to do that. Returns undef on failure, or the task object.

    # fetches these sites are up, in parallel
    for my $site ( 'http://google.com', 'http://yahoo.com' ) {
        my $task = gearman_add_task('fetch_site', $site);
        return template error => { error => gearman_error } unless $task;
    }
    my $ret = gearman_run_tasks;
    return template error => { error => gearman_error } unless $ret;
    ## Tasks have completed

gearman_run_tasks

Once a number of tasks have been queued via gearman_add_tasks, this method allows them to run in parallel, and returns whether there has been a failure. See gearman_add_task for an example.

AUTHOR

Marco Fontani - <MFONTANI at cpan.org>

BUGS

Please report any bugs via e-mail.

SEE ALSO

Dancer - Dancer

Gearman::XS - Gearman::XS

Gearman site - http://www.gearman.org

Yosemite National Park: it's worth visiting.

LICENSE AND COPYRIGHT

Copyright 2011 Marco Fontani.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm Dancer::Plugin::GearmanXS

perl -MCPAN -e shell
install Dancer::Plugin::GearmanXS