/ 
PkgForge-Registry-1.3.0
River stage zero No dependents
/ PkgForge::Registry

NAME

PkgForge::Registry - A Moose class used for access to the PkgForge registry.

VERSION

This documentation refers to PkgForge::Registry version 1.3.0

SYNOPSIS

use PkgForge::Registry;

my $registry = PkgForge::Registry->new();

# or more usefully...

my $registry
      = PkgForge::Registry->new_with_config( configfile => "foo.yml" );

# Get the DBIx::Class schema object

my $schema = $registry->schema;

# Provides some high-level methods

if ( !$registry->job_exists($job) ) {
    $registry->register_job($job);
}

$registry->update_job_status($job,'valid');

DESCRIPTION

This class manages access to the Package Forge registry. It provides configuration handling methods for setting the various DBI parameters which are used to load the DBIx::Class schema object. It also provides some high-level functions which are used for registering build jobs and managing the status of separate tasks associated with each job.

ATTRIBUTES

This class has the following attributes:

name

This is the name of the database being used to store the registry information. This attibute MUST be specified, there is no default value.

host

This is the host name for the database server. This attribute is optional, see DBD::Pg for details of the default value.

port

This is the port number for the database server. This attribute is optional, see DBD::Pg for details of the default value.

user

This is the name of the user to be used for accessing the database. This attribute is optional, see DBD::Pg for details of the default value.

pass

This is the password for the user to be used for accessing the database. This attribute is optional, see DBD::Pg for details of the default value.

schema

This gives access to the DBIx::Class::Schema object.

configfile

The name for a configuration file which can be used for loading the registry attributes. The default is /etc/pkgforge/registry.yml. This only has an effect when you create a new object using the new_with_config method.

SUBROUTINES/METHODS

This class has the following methods:

new()

Create a new instance of this class. Optionally a hash (or reference to a hash) of attributes and their values can be specified.

new_with_config()

Create a new instance of this class using the attribute values set in a configuration file. By default, the /etc/pkgforge/registry.yml will be loaded, if it exists. The configuration file can be changed using the configfile attribute. See PkgForge::ConfigFile for more details.

build_dsn()

This returns the DBI Data Source Name (DSN) built from the various attributes. The DSN is passed through to the DBI layer and this method is mainly provided to help future sub-classes which might need to override the database driver.

register_job($job)

This method takes a PkgForge::Job object and registers the job into the PkgForge registry. Firstly a check is made that no other job with the same UUID has already been registered. If successful the method will return true, if anything fails then the method will die.

register_tasks($job)

This method takes a PkgForge::Job object and registers the associated tasks (if any). Firstly this method checks that the job has already been registered (this should be done with register_job). It then calls the process_build_targets method on the job object with the current list of active build target platforms to find out which platforms and architectures are required. A task is added for each required platform (if any). The job status will be updated to registered if the tasks are successfully registered. If successful the method will return true, if anything fails then the method will die.

get_job_status($job)

This method takes a PkgForge::Job object and returns the name of the current status for the job. This method will die if it cannot find the relevant job, if no status is found then unknown will be returned.

update_job_status($job, $status_name)

This method takes a PkgForge::Job object and the name of a status to which the job status field should be set. If anything fails this method will die.

reset_unfinished_tasks($builder_name)

This method takes the name of a registered builder and resets any associated unfinished tasks (in the building status) to the needs build status. This is particularly useful when a shut down of a builder has been requested before a task is finished. The task can then be picked up again later by another operational daemon.

next_new_task($builder_name)

This method takes the name of a registered builder and returns the next task in the status needs build (if any). If a new task is found then it will be moved into the building status, the current job for that builder will be recorded and a PkgForge::Registry::Schema::Result::Job object will be returned. If no new tasks are found the method will return undef, if an error occurs the method will die.

Whilst selecting the next task all rows in the database for that platform containing tasks needing building will be locked. This is to avoid multiple builders for the same platform taking on the same tasks.

fail_task( $builder_name, $job_uuid )

This registers a task as having failed to build on the platform supported by the specified builder. Note that, to maintain consistency, this method requires the specified job to be the same as that which is considered current for the builder.

finalise_task( $builder_name, $job_uuid )

This registers a task as having successfully built on the platform supported by the specified builder. Note that, to maintain consistency, this method requires the specified job to be the same as that which is considered current for the builder.

CONFIGURATION AND ENVIRONMENT

If the new_with_config method is used then configuration information can be loaded from a file. The default file name is /etc/pkgforge/registry.yml but that can be overridden using the configfile attribute.

It is not necessary to set all the attributes to successfully connect to the database. The DBI layer has support for using environment variables for nearly all possible connection options, see DBD::Pg for full details.

DEPENDENCIES

This module is powered by Moose and uses MooseX::ConfigFromFile and MooseX::Types. The DBIx::Class object-relational mapper modules are used for database access. Currently PkgForge requires PostgreSQL for the database backend, this means that the DBD::Pg module is also necessary.

SEE ALSO

PkgForge

PLATFORMS

This is the list of platforms on which we have tested this software. We expect this software to work on any Unix-like platform which is supported by Perl.

ScientificLinux5, Fedora13

BUGS AND LIMITATIONS

Please report any bugs or problems (or praise!) to bugs@lcfg.org, feedback and patches are also always very welcome.

AUTHOR

Stephen Quinney <squinney@inf.ed.ac.uk>

LICENSE AND COPYRIGHT

Copyright (C) 2010 University of Edinburgh. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the terms of the GPL, version 2 or later.