Bug 6942 - Add link to manual to help/authorities/authorities-home.tt
[wip/koha-chris_n.git] / C4 / Scheduler.pm
1 package C4::Scheduler;
2
3 # Copyright 2007 Liblime Ltd
4 #
5 # This file is part of Koha.
6 #
7 # Koha is free software; you can redistribute it and/or modify it under the
8 # terms of the GNU General Public License as published by the Free Software
9 # Foundation; either version 2 of the License, or (at your option) any later
10 # version.
11 #
12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
15 #
16 # You should have received a copy of the GNU General Public License along
17 # with Koha; if not, write to the Free Software Foundation, Inc.,
18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19
20 use strict;
21 #use warnings; FIXME - Bug 2505
22
23 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
24 use C4::Context;
25 use Schedule::At;
26
27 BEGIN {
28         # set the version for version checking
29         $VERSION = 0.02;
30         require Exporter;
31         @ISA = qw(Exporter);
32         @EXPORT =
33                 qw(get_jobs get_at_jobs get_at_job add_at_job remove_at_job);
34 }
35
36 =head1 NAME
37
38 C4::Scheduler - Module for running jobs with the unix at command
39
40 =head1 SYNOPSIS
41
42   use C4::Scheduler;
43
44 =head1 DESCRIPTION
45
46 =cut
47
48 =head1 METHODS
49
50 =head2 get_jobs();
51
52 This will return all scheduled jobs
53
54 =cut
55
56 sub get_jobs {
57     my $jobs = get_at_jobs();
58 # add call to get cron jobs here too
59     return ($jobs);
60 }
61
62 =head2 get_at_jobs();
63
64 This will return all At scheduled jobs
65
66 =cut
67
68 sub get_at_jobs {
69         my %jobs = Schedule::At::getJobs();
70         return (\%jobs);
71 }
72
73 =head2 get_at_job($id)
74
75 This will return the At job with the given id
76
77 =cut
78
79 sub get_at_job {
80         my ($id)=@_;
81         my %jobs = Schedule::At::getJobs(JOBID => $id);
82 }
83
84 =head2 add_at_job ($time,$command)
85
86 Given a timestamp and a command this will schedule the job to run at that time.
87
88 Returns true if the job is added to the queue and false otherwise.
89
90 =cut
91
92 sub add_at_job {
93         my ($time,$command) = @_;
94     # FIXME - a description of the task to be run 
95     # may be a better tag, since the tag is displayed
96     # in the job list that the administrator sees - e.g.,
97     # "run report foo, send to foo@bar.com"
98         Schedule::At::add(TIME => $time, COMMAND => $command, TAG => $command);
99
100     # FIXME - this method of checking whether the job was added
101     # to the queue is less than perfect:
102     #
103     # 1. Since the command is the tag, it is possible that there is
104     #    already a job in the queue with the same tag.  However, since
105     #    the tag is what displays in the job list, we can't just
106     #    give it a unique ID.
107     # 2. Schedule::At::add() is supposed to return a non-zero
108     #    value if it fails to add a job - however, it does
109     #    not check all error conditions - in particular, it does
110     #    not check the return value of the "at" run; it basically
111     #    complains only if it can't find at.
112     # 3. Similary, Schedule::At::add() does not do something more useful,
113     #    such as returning the job ID.  To be fair, it is possible
114     #    that 'at' does not allow this in any portable way.
115     # 4. Although unlikely, it is possible that a job could be added
116     #    and completed instantly, thus dropping off the queue.
117     my $job_found = 0;
118     eval {
119             my %jobs = Schedule::At::getJobs(TAG => $command);
120         $job_found = scalar(keys %jobs) > 0;
121     };
122     if ($@) {
123         return 0;
124     } else {
125         return $job_found;
126     }
127 }
128
129 sub remove_at_job {
130         my ($jobid)=@_;
131         Schedule::At::remove(JOBID => $jobid);
132 }
133
134 1;
135 __END__
136
137 =head1 BUGS
138
139 At some point C<C4::Scheduler> should be refactored:
140
141 =over
142
143 =item At and C<Schedule::At> does not work on Win32.
144
145 =item At is not installed by default on all platforms.
146
147 =item The At queue used by Koha is owned by the httpd user.  If multiple
148 Koha databases share an Apache instance on a server, everybody can
149 see everybody's jobs.
150
151 =item There is no support for scheduling a job to run more than once.
152
153 =back
154
155 =head1 AUTHOR
156
157 Chris Cormack <crc@liblime.com>
158
159 =cut