.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Cpanel::TaskQueue::PluginManager 3"
.TH Cpanel::TaskQueue::PluginManager 3 "2011-01-04" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Cpanel::TaskQueue::PluginManager \- Supplies support for loading the Queue task processing plugins.
.SH "VERSION"
.IX Header "VERSION"
This document describes \f(CW\*(C`Cpanel::TaskQueue::PluginManager\*(C'\fR version 0.307.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Cpanel::TaskQueue::PluginManager;
.Ve
.PP
.Vb 3
\&   # Loads the modules found in '/usr/local/cpanel/Cpanel/TaskQueue/Plugin' assuming their
\&   #  names are Cpanel::TaskQueue::Plugin::*.
\&   Cpanel::TaskQueuePlugin::Manager::load_plugins( '/usr/local/cpanel', 'Cpanel::TaskQueue::Plugin' );
.Ve
.PP
.Vb 6
\&   # If you have multiple directories and/or namespaces, you can use the convenience method
\&   #   Smart enough not to try to reload any that already match.
\&   Cpanel::TaskQueue::PluginManager::load_all_plugins(
\&       directories => [ '/usr/local/cpanel', '.', '/home/fred/tasks' ],
\&       namespaces => [ 'Cpanel::TaskQueue::Plugin', 'MyHandlers' ]
\&    );
.Ve
.PP
.Vb 1
\&    my @loaded = Cpanel::TaskQueue::PluginManager::list_loaded_plugins();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module wraps up the logic to load any modules located in a particular
directory as plugins for the Cpanel::TaskQueue class. It also registers them
with that class.
.SH "INTERFACE"
.IX Header "INTERFACE"
The interface for this module consists of three functions.
.ie n .IP "Cpanel::TaskQueue::PluginManager::load_plugins( $dir\fR, \f(CW$namespace )" 4
.el .IP "Cpanel::TaskQueue::PluginManager::load_plugins( \f(CW$dir\fR, \f(CW$namespace\fR )" 4
.IX Item "Cpanel::TaskQueue::PluginManager::load_plugins( $dir, $namespace )"
This function loads all modules described by the supplied parameters and attempts to
register them with \f(CW\*(C`Cpanel::TaskQueue\*(C'\fR. The two required parameters are
.RS 4
.IP "\fIroot_dir\fR" 4
.IX Item "root_dir"
The \fIroot_dir\fR required parameter defines a directory used to find plugins. \fIroot_dir\fR
must be in \f(CW@INC\fR in order for perl to load the plugin modules.
.IP "\fInamespace\fR" 4
.IX Item "namespace"
This parameter specifies the namespace in which to find the plugin module. The
namespace is needed to properly resolve the name of the module.
.RE
.RS 4
.Sp
The actual directory where the plugin modules are located is made by combining
the \fIroot_dir\fR and \fInamespace\fR the same way Perl does. The '::' characters in
the namespace are replaced with path separators. This relative path is combined
with the \fIroot_dir\fR to create the actual path we search.
.RE
.ie n .IP "Cpanel::TaskQueue::PluginManager::load_all_plugins( directories => $dirs\fR, namespaces => \f(CW$ns )" 4
.el .IP "Cpanel::TaskQueue::PluginManager::load_all_plugins( directories => \f(CW$dirs\fR, namespaces => \f(CW$ns\fR )" 4
.IX Item "Cpanel::TaskQueue::PluginManager::load_all_plugins( directories => $dirs, namespaces => $ns )"
This function helps to deal with distributed sets of plugins. It requires two
named arguments:
.RS 4
.IP "\fIdirectories\fR" 4
.IX Item "directories"
A reference to an array of root directories. These directories are used as the
\&\fIroot_dir\fR parameter to the \f(CW\*(C`load_plugins\*(C'\fR method.
.IP "\fInamespaces\fR" 4
.IX Item "namespaces"
A reference to an array of namespaces. These namespaces are used as the \fInamespace\fR
parameter to the \f(CW\*(C`load_plugins\*(C'\fR method.
.RE
.RS 4
.Sp
This method just calls the \f(CW\*(C`load_plugins\*(C'\fR function with every combination of
directory and namespace supplied. This allows multiple directories (maybe system,
site, and special) to be searched for plugins. The plugins may also be separated
into multiple namespaces (maybe \f(CW\*(C`Cpanel::TaskQueue::Plugin\*(C'\fR, \f(CW\*(C`Site::Tasks\*(C'\fR,
\&\f(CW\*(C`Cpanel::Backup::Tasks\*(C'\fR).
.Sp
Using the examples above, would generate 9 different locations to search for
plugins and load any found in those locations.
.RE
.ie n .IP "Cpanel::TaskQueue::PluginManager::load_plugin_by_name( $module_name )" 4
.el .IP "Cpanel::TaskQueue::PluginManager::load_plugin_by_name( \f(CW$module_name\fR )" 4
.IX Item "Cpanel::TaskQueue::PluginManager::load_plugin_by_name( $module_name )"
Loads only the plugin defined by the specified full Perl module name. The
directory containing the module must already be part of the Perl path.
.Sp
Returns a true value is successful and a false value otherwise.
.IP "\fICpanel::TaskQueue::PluginManager::list_loaded_plugins()\fR" 4
.IX Item "Cpanel::TaskQueue::PluginManager::list_loaded_plugins()"
Returns a list of the names of the loaded plugins in no particular order.
.IP "\fICpanel::TaskQueue::PluginManager::get_plugins_hash()\fR" 4
.IX Item "Cpanel::TaskQueue::PluginManager::get_plugins_hash()"
Returns a reference to a hash listing the loaded plugins. The hash maps the
module names of loaded plugins to an anonymous array of the commands that the
module provides.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """No directory list supplied.""" 4
.el .IP "\f(CWNo directory list supplied.\fR" 4
.IX Item "No directory list supplied."
\&\f(CW\*(C`load_all_plugins\*(C'\fR was called without a \fIdirectories\fR parameter.
.ie n .IP """No namepsace list supplied.""" 4
.el .IP "\f(CWNo namepsace list supplied.\fR" 4
.IX Item "No namepsace list supplied."
\&\f(CW\*(C`load_all_plugins\*(C'\fR was called without a \fInamespaces\fR parameter.
.ie n .IP """No directory supplied for finding plugins.""" 4
.el .IP "\f(CWNo directory supplied for finding plugins.\fR" 4
.IX Item "No directory supplied for finding plugins."
\&\f(CW\*(C`load_plugins\*(C'\fR was called without the required \fIrootdir\fR parameter.
.ie n .IP """Supplied directory '%s' does not exist.""" 4
.el .IP "\f(CWSupplied directory '%s' does not exist.\fR" 4
.IX Item "Supplied directory '%s' does not exist."
The root directory parameter passed to \f(CW\*(C`load_plugins\*(C'\fR was not a valid directory.
.ie n .IP """Supplied directory '%s' not part of Perl's include path.""" 4
.el .IP "\f(CWSupplied directory '%s' not part of Perl's include path.\fR" 4
.IX Item "Supplied directory '%s' not part of Perl's include path."
The root directory parameter passed to \f(CW\*(C`load_plugins\*(C'\fR is not part of Perl's
include path. Plugins in that directory will not be able to be loaded.
.ie n .IP """No namespace for plugins specified.""" 4
.el .IP "\f(CWNo namespace for plugins specified.\fR" 4
.IX Item "No namespace for plugins specified."
\&\f(CW\*(C`load_plugins\*(C'\fR was called without the required \fInamespace\fR parameter.
.ie n .IP """Namespace '%s' not a valid Perl namespace.""" 4
.el .IP "\f(CWNamespace '%s' not a valid Perl namespace.\fR" 4
.IX Item "Namespace '%s' not a valid Perl namespace."
The string passed to \f(CW\*(C`load_plugins\*(C'\fR as a namespace is not a valid namespace.
.ie n .IP """Failed to load '%s' plugin: %s""" 4
.el .IP "\f(CWFailed to load '%s' plugin: %s\fR" 4
.IX Item "Failed to load '%s' plugin: %s"
Attempting to load the named plugin module failed for the reason given.
.ie n .IP """Plugin '%s' not registered, no 'to_register' method.""" 4
.el .IP "\f(CWPlugin '%s' not registered, no 'to_register' method.\fR" 4
.IX Item "Plugin '%s' not registered, no 'to_register' method."
The named plugin does not supply the \f(CW\*(C`to_register\*(C'\fR package method. Without
this method, we cannot register the plugin with the \f(CW\*(C`Cpanel::TaskQueue\*(C'\fR
module.
.Sp
This may mean that the named module is intended to be a \f(CW\*(C`TaskQueue\*(C'\fR plugin. 
.ie n .IP """Plugin '%s': invalid registration entry""" 4
.el .IP "\f(CWPlugin '%s': invalid registration entry\fR" 4
.IX Item "Plugin '%s': invalid registration entry"
The \f(CW\*(C`to_register\*(C'\fR package method of the named plugin returned data that was
inconsistent with registering a \f(CW\*(C`TaskQueue\*(C'\fR plugin. This method is expected to
return a list of arrayrefs. Each of these arrayrefs should be a two item list.
.Sp
Either the named module is not a \f(CW\*(C`TaskQueue\*(C'\fR plugin or the \f(CW\*(C`to_register\*(C'\fR method
needs to be fixed.
.ie n .IP """Plugin '%s' register failed: %s""" 4
.el .IP "\f(CWPlugin '%s' register failed: %s\fR" 4
.IX Item "Plugin '%s' register failed: %s"
Registering a command returned by \f(CW\*(C`to_register\*(C'\fR failed for the reason given.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Cpanel::TaskQueue::PluginManager requires no configuration files or environment
variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Cpanel::TaskQeue
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Cpanel::TaskQueue::TaskProcessor
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
At present, this module does not have any support for enabling/disabling individual
plugins.  That will probably be an important feature at some point.
.SH "AUTHOR"
.IX Header "AUTHOR"
G. Wade Johnson  \f(CW\*(C`wade@cpanel.net\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2009, CPanel. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
\&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
\&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
\&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
\&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
\&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
\&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0
\&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
\&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
\&\s-1SUCH\s0 \s-1DAMAGES\s0.