cpan/Test-Harness/lib/TAP/Parser/Scheduler/Job.pm

   1 package TAP::Parser::Scheduler::Job;
   2
   3 use strict;
   4 use warnings;
   5 use Carp;
   6
   7 =head1 NAME
   8
   9 TAP::Parser::Scheduler::Job - A single testing job.
  10
  11 =head1 VERSION
  12
  13 Version 3.34
  14
  15 =cut
  16
  17 our $VERSION = '3.34';
  18
  19 =head1 SYNOPSIS
  20
  21     use TAP::Parser::Scheduler::Job;
  22
  23 =head1 DESCRIPTION
  24
  25 Represents a single test 'job'.
  26
  27 =head1 METHODS
  28
  29 =head2 Class Methods
  30
  31 =head3 C<new>
  32
  33     my $job = TAP::Parser::Scheduler::Job->new(
  34         $filename, $description
  35     );
  36
  37 Given the filename and description of a test as scalars, returns a new
  38 L<TAP::Parser::Scheduler::Job> object.
  39
  40 =cut
  41
  42 sub new {
  43     my ( $class, $name, $desc, @ctx ) = @_;
  44     return bless {
  45         filename    => $name,
  46         description => $desc,
  47         @ctx ? ( context => \@ctx ) : (),
  48     }, $class;
  49 }
  50
  51 =head2 Instance Methods
  52
  53 =head3 C<on_finish>
  54
  55     $self->on_finish(\&method).
  56
  57 Register a closure to be called when this job is destroyed. The callback
  58 will be passed the C<TAP::Parser::Scheduler::Job> object as it's only argument.
  59
  60 =cut
  61
  62 sub on_finish {
  63     my ( $self, $cb ) = @_;
  64     $self->{on_finish} = $cb;
  65 }
  66
  67 =head3 C<finish>
  68
  69    $self->finish;
  70
  71 Called when a job is complete to unlock it. If a callback has been registered
  72 with C<on_finish>, it calls it. Otherwise, it does nothing.
  73
  74 =cut
  75
  76 sub finish {
  77     my $self = shift;
  78     if ( my $cb = $self->{on_finish} ) {
  79         $cb->($self);
  80     }
  81 }
  82
  83 =head2 Attributes
  84
  85   $self->filename;
  86   $self->description;
  87   $self->context;
  88
  89 These are all "getters" which return the data set for these attributes during object construction.
  90
  91
  92 =head3 C<filename>
  93
  94 =head3 C<description>
  95
  96 =head3 C<context>
  97
  98 =cut
  99
 100 sub filename    { shift->{filename} }
 101 sub description { shift->{description} }
 102 sub context     { @{ shift->{context} || [] } }
 103
 104 =head3 C<as_array_ref>
 105
 106 For backwards compatibility in callbacks.
 107
 108 =cut
 109
 110 sub as_array_ref {
 111     my $self = shift;
 112     return [ $self->filename, $self->description, $self->{context} ||= [] ];
 113 }
 114
 115 =head3 C<is_spinner>
 116
 117   $self->is_spinner;
 118
 119 Returns false indicating that this is a real job rather than a
 120 'spinner'. Spinners are returned when the scheduler still has pending
 121 jobs but can't (because of locking) return one right now.
 122
 123 =cut
 124
 125 sub is_spinner {0}
 126
 127 1;