/ 
IPC-Concurrency-DBI-v1.2.0
River stage zero No dependents
/ IPC::Concurrency::DBI

NAME

IPC::Concurrency::DBI - Control how many instances of an application run in parallel, using DBI as the IPC method.

VERSION

Version 1.2.0

SYNOPSIS

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

You can use this module for example to prevent more than one instance of a program from running at any given time, or to never have more than N instances running in parallel to prevent exhausting all the available resources.

It uses DBI as a storage layer for information about instances and applications, which is particularly useful in contexts where Sarbanes-Oxley regulations allow you database access but not file write rights in production environments.

# Configure the concurrency object.
use IPC::Concurrency::DBI;
my $concurrency_manager = IPC::Concurrency::DBI->new(
	'database_handle' => $dbh,
	'verbose'         => 1,
);

# Create the tables that the concurrency manager needs to store information
# about the applications and instances.
$concurrency_manager->create_tables();

# Register cron_script.pl as an application we want to limit to 10 parallel
# instances. We only need to do this once, obviously.
$concurrency_manager->register_application(
	name              => 'cron_script.pl',
	maximum_instances => 10,
);

# 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.
unless ( my $instance = $application->start_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();

SUPPORTED DATABASES

This distribution currently supports:

  • SQLite

  • MySQL

  • PostgreSQL

Please contact me if you need support for another database type, I'm always glad to add extensions if you can help me with testing.

METHODS

new()

Create a new IPC::Concurrency::DBI object.

my $concurrency_manager = IPC::Concurrency::DBI->new(
	'database_handle'   => $dbh,
	'verbose'           => 1,
);

Arguments:

  • database handle

    Mandatory, a DBI object.

  • verbose

    Optional, see verbose() for options.

register_application()

Register a new application with the concurrency manager and define the maximum number of instances that should be allowed to run in parallel.

$concurrency_manager->register_application(
	name              => 'cron_script.pl',
	maximum_instances => 10,
);

'name' is a unique name for the application. It can be the name of the script for a cron script, for example.

'maximum_instances' is the maximum number of instances that should be allowed to run in parallel.

get_application()

Retrieve an application by name or by application ID.

# Retrieve the application by name.
my $application = $concurrency_manager->get_application(
	name => 'cron_script.pl',
);
die 'Application not found'
	unless defined( $application );

# Retrieve the application by ID.
my $application = $concurrency_manager->get_application(
	id => 12345,
);
die 'Application not found'
	unless defined( $application );

create_tables()

Create the tables that the concurrency manager needs to store information about the applications and instances.

$concurrency_manager->create_tables(
	drop_if_exist => $boolean,      #default 0
);

By default, it won't drop any table but you can force that by setting 'drop_if_exist' to 1.

ACCESSORS

get_database_handle()

Returns the database handle used for this object.

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

get_database_type()

Return the database type corresponding to the database handle associated with the IPC::Concurrency::DBI object.

my $database_type = $concurrency_manager->get_database_type();

get_verbose()

Return the verbosity level, which is used in the module to determine when and what type of debugging statements / information should be warned out.

See set_verbose() for the possible values this function can return.

warn 'Verbose' if $queue->get_verbose();

warn 'Very verbose' if $queue->get_verbose() > 1;

set_verbose()

Control the verbosity of the warnings in the code:

  • 0 will not display any warning;

  • 1 will only give one line warnings about the current operation;

  • 2 will also usually output the SQL queries performed.

$queue->set_verbose(1); # turn on verbose information

$queue->set_verbose(2); # be extra verbose

$queue->set_verbose(0); # quiet now!

DEPRECATED METHODS

verbose()

Please use get_verbose() and set_verbose() instead.

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:

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

ACKNOWLEDGEMENTS

I originally developed this project for ThinkGeek (http://www.thinkgeek.com/). Thanks for allowing me to open-source it!

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-2017 Guillaume Aubert.

This code is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

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 LICENSE file for more details.