/ 
IPC-Concurrency-DBI-1.0.2
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.0.2

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.

Note that currently only MySQL and SQLite are fully tested. Patches or testing environments for other DBD::* modules are welcome.

# 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();

METHODS

new()

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

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

'database handle': mandatory, a DBI object.

'verbose': optional, see verbose() for options.

verbose()

Control the verbosity of the warnings in the code.

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

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

warn 'Verbose' if $queue->verbose(); # getter-style

Allows turning on/off debugging information.

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
	database_type => $database_type #default SQLite
);

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

'database_type' currently supports 'SQLite' and 'MySQL'. Patches or requests for other DBD::* modules are welcome!

INTERNAL METHODS

_get_database_handle()

Returns the database handle used for this queue.

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

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

BUGS

Please report any bugs or feature requests to bug-ipc-concurrency-dbi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPC-Concurrency-DBI. 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:

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

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License.

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