From 58cba4da24d9f14bce8a6beeaf5cb7a5975911a2 Mon Sep 17 00:00:00 2001
From: Oliver Gorwits <oliver@cpan.org>
Date: Sat, 10 May 2014 22:06:41 +0100
Subject: [PATCH] add POD for JobQueue

---
 .../App/Netdisco/Daemon/DB/Result/Admin.pm    |  2 +
 Netdisco/lib/App/Netdisco/Daemon/JobQueue.pm  | 93 +++++++++++++++++++
 .../lib/App/Netdisco/JobQueue/PostgreSQL.pm   | 16 ++--
 3 files changed, 103 insertions(+), 8 deletions(-)

diff --git a/Netdisco/lib/App/Netdisco/Daemon/DB/Result/Admin.pm b/Netdisco/lib/App/Netdisco/Daemon/DB/Result/Admin.pm
index 64f3899c..39c09fd5 100644
--- a/Netdisco/lib/App/Netdisco/Daemon/DB/Result/Admin.pm
+++ b/Netdisco/lib/App/Netdisco/Daemon/DB/Result/Admin.pm
@@ -44,4 +44,6 @@ __PACKAGE__->add_columns(
 
 __PACKAGE__->set_primary_key("job");
 
+sub extra { (shift)->subaction }
+
 1;
diff --git a/Netdisco/lib/App/Netdisco/Daemon/JobQueue.pm b/Netdisco/lib/App/Netdisco/Daemon/JobQueue.pm
index db48aa05..84ea889f 100644
--- a/Netdisco/lib/App/Netdisco/Daemon/JobQueue.pm
+++ b/Netdisco/lib/App/Netdisco/Daemon/JobQueue.pm
@@ -17,4 +17,97 @@ sub jq_defer    { shift and JobQueue::jq_defer(@_) }
 sub jq_complete { shift and JobQueue::jq_complete(@_) }
 sub jq_insert   { shift and JobQueue::jq_insert(@_) }
 
+=head1 NAME
+
+App::Netdisco::Daemon::JobQueue
+
+=head1 DESCRIPTION
+
+Interface for Netdisco job queue.
+
+There are no default exports, however the C<:all> tag will export all
+subroutines.
+
+=head1 EXPORT_OK
+
+=head2 jq_get( $num? )
+
+Returns a list of randomly selected queued jobs. Default is to return one job,
+unless C<$num> is provided. Jobs are returned as objects which implement the
+Netdisco job instance interface (see below).
+
+=head2 jq_getlocal()
+
+Returns the list of jobs currently booked out to this processing node (denoted
+by the local hostname). Jobs are returned as objects which implement the
+Netdisco job instance interface (see below).
+
+=head2 jq_queued( $job_type )
+
+Returns a list of IP addresses of devices which currently have a job of the
+given C<$job_type> queued (e.g. C<discover>, C<arpnip>, etc).
+
+=head2 jq_lock( $job )
+
+Marks a job in the queue as booked out to this processing node (denoted by the
+local hostname). The C<$job> parameter must be an object which implements the
+Netdisco job instance interface (see below).
+
+Returns true if successful else returns false.
+
+=head2 jq_defer( $job )
+
+Marks a job in the queue as available for taking. This is usually done after a
+job is booked but the processing node changes its mind and decides to return
+the job to the queue. The C<$job> parameter must be an object which implements
+the Netdisco job instance interface (see below).
+
+Returns true if successful else returns false.
+
+=head2 jq_complete( $job )
+
+Marks a job as complete. The C<$job> parameter must be an object which
+implements the Netdisco job instance interface (see below). The queue item's
+status, log and finished fields will be updated from the passed C<$job>.
+
+Returns true if successful else returns false.
+
+=head2 jq_insert( \%job | [ %job, \%job ...] )
+
+Adds the passed jobs to the queue.
+
+=head1 Job Instance Interface
+
+=head2 id (auto)
+
+=head2 type (required)
+
+=head2 wid (required, default 0)
+
+=head2 entered
+
+=head2 started
+
+=head2 finished
+
+=head2 device
+
+=head2 port
+
+=head2 action
+
+=head2 subaction or extra
+
+=head2 status
+
+=head2 username
+
+=head2 userip
+
+=head2 log
+
+=head2 debug
+
+=cut
+
 true;
diff --git a/Netdisco/lib/App/Netdisco/JobQueue/PostgreSQL.pm b/Netdisco/lib/App/Netdisco/JobQueue/PostgreSQL.pm
index d9c71d54..0ccb6880 100644
--- a/Netdisco/lib/App/Netdisco/JobQueue/PostgreSQL.pm
+++ b/Netdisco/lib/App/Netdisco/JobQueue/PostgreSQL.pm
@@ -67,7 +67,7 @@ sub jq_queued {
 sub jq_lock {
   my $job = shift;
   my $fqdn = hostfqdn || 'localhost';
-  my $happy = 0;
+  my $happy = false;
 
   # lock db row and update to show job has been picked
   try {
@@ -76,7 +76,7 @@ sub jq_lock {
         ->find($job->id, {for => 'update'})
         ->update({ status => "queued-$fqdn" });
     });
-    $happy = 1;
+    $happy = true;
   };
 
   return $happy;
@@ -84,7 +84,7 @@ sub jq_lock {
 
 sub jq_defer {
   my $job = shift;
-  my $happy = 0;
+  my $happy = false;
 
   # lock db row and update to show job is available
   try {
@@ -93,7 +93,7 @@ sub jq_defer {
         ->find($job->id, {for => 'update'})
         ->update({ status => 'queued' });
     });
-    $happy = 1;
+    $happy = true;
   };
 
   return $happy;
@@ -101,7 +101,7 @@ sub jq_defer {
 
 sub jq_complete {
   my $job = shift;
-  my $happy = 0;
+  my $happy = false;
 
   # lock db row and update to show job is done/error
   try {
@@ -113,7 +113,7 @@ sub jq_complete {
           finished => $job->finished,
         });
     });
-    $happy = 1;
+    $happy = true;
   };
 
   return $happy;
@@ -122,7 +122,7 @@ sub jq_complete {
 sub jq_insert {
   my $jobs = shift;
   $jobs = [$jobs] if ref [] ne ref $jobs;
-  my $happy = 0;
+  my $happy = false;
 
   try {
     schema('netdisco')->txn_do(sub {
@@ -138,7 +138,7 @@ sub jq_insert {
         }} @$jobs
       ]);
     });
-    $happy = 1;
+    $happy = true;
   };
 
   return $happy;