Update Test-Harness to CPAN version 3.39
[perl.git] / 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.39
14
15 =cut
16
17 our $VERSION = '3.39';
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;