NAME

IPC::Concurrency::DBI::Application - Application identifier that represents the resource that will be limited.

VERSION

Version 1.1.2

SYNOPSIS

This module allows controlling how many instances of a given program are allowed to run in parallel. It does not manage forking or starting those instances.

See the documentation of IPC::Concurrency::DBI for more information.

        # Configure the concurrency object.
        use IPC::Concurrency::DBI;
        my $concurrency_manager = IPC::Concurrency::DBI->new(
                'database_handle' => $dbh,
                'verbose'         => 1,
        );
        
        # Retrieve the application.
        my $application = $concurrency_manager->get_application(
                name => 'cron_script.pl',
        );
        
        # Count how many instances are currently running.
        my $instances_count = $application->get_instances_count();
        
        # NOT IMPLEMENTED YET: Get a list of what instances are currently running.
        # my $instances = $application->get_instances_list()
        
        # Start a new instance of the application. If this returns undef, we've
        # reached the limit.
        my $instance = $concurrent_program->start_instance();
        unless ( defined( $instance ) )
        {
                print "Too many instances of $0 are already running.\n";
                exit;
        }
        
        # [...] Do some work.
        
        # Now that the application is about to exit, flag the instance as completed.
        # (note: this is implicit when $instance is destroyed).
        $instance->finish();

METHODS

new()

Create a new IPC::Concurrency::DBI::Application object. This function should not be called directly and its API could change, instead use IPC::Concurrency::DBI->get_application().

        # Retrieve the application by name.
        my $application = IPC::Concurrency::DBI::Application->new(
                database_handle => $dbh,
                name            => 'cron_script.pl',
        );
        die 'Application not found'
                unless defined( $application );
        
        # Retrieve the application by ID.
        my $application = IPC::Concurrency::DBI::Application->new(
                database_handle => $dbh,
                id              => 12345,
        );
        die 'Application not found'
                unless defined( $application );

'database handle': mandatory, a DBI object.

'name': the name of the application to retrieve.

'id': the internal ID of the application to retrieve.

start_instance()

Start a new instance of the current application.

        my $instance = $application->start_instance();
        unless ( defined( $instance ) )
        {
                print "Too many instances of $0 are already running.\n";
                exit;
        }

GETTERS / SETTERS

get_instances_count()

Retrieve the number of instances that currently running.

        my $instances_count = $application->get_instances_count();

get_maximum_instances()

Retrieve the maximum number of instances of the current application that are allowed to run in parallel.

        my $maximum_instances = $application->get_maximum_instances();

set_maximum_instances()

Change the maximum number of instances of the current application that are allowed to run in parallel.

        $application->set_maximum_instances( 10 );

get_name()

Returns the name of the current application.

        my $name = $application->get_name();

get_id()

Returns the internal ID of the current application.

        my $application_id = $self->get_id();

INTERNAL METHODS

get_database_handle()

Returns the database handle used for this object.

        my $database_handle = $concurrency_manager->get_database_handle();

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/guillaumeaubert/IPC-Concurrency-DBI/issues/new. 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 IPC::Concurrency::DBI

You can also look for information at:

• GitHub's request tracker

  https://github.com/guillaumeaubert/IPC-Concurrency-DBI/issues

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/IPC-Concurrency-DBI

• CPAN Ratings

  http://cpanratings.perl.org/d/IPC-Concurrency-DBI

• MetaCPAN

  https://metacpan.org/release/IPC-Concurrency-DBI

ACKNOWLEDGEMENTS

Thanks to ThinkGeek (http://www.thinkgeek.com/) and its corporate overlords at Geeknet (http://www.geek.net/), for footing the bill while I eat pizza and write code for them!

Thanks to Jacob Rose <jacob at thinkgeek.com> for suggesting the idea of this module and brainstorming with me about the features it should offer.

COPYRIGHT & LICENSE

Copyright 2011-2013 Guillaume Aubert.

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/