Give processor_t more control over the lifecycle of a job
[strongswan.git] / src / libstrongswan / processing / jobs / job.h
1 /*
2 * Copyright (C) 2012 Tobias Brunner
3 * Copyright (C) 2005-2006 Martin Willi
4 * Copyright (C) 2005 Jan Hutter
5 * Hochschule fuer Technik Rapperswil
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * for more details.
16 */
17
18 /**
19 * @defgroup job job
20 * @{ @ingroup jobs
21 */
22
23 #ifndef JOB_H_
24 #define JOB_H_
25
26 typedef struct job_t job_t;
27 typedef enum job_priority_t job_priority_t;
28 typedef enum job_requeue_t job_requeue_t;
29 typedef enum job_status_t job_status_t;
30
31 #include <library.h>
32
33 /**
34 * Priority classes of jobs
35 */
36 enum job_priority_t {
37 /** Critical infrastructure jobs that should always been served */
38 JOB_PRIO_CRITICAL = 0,
39 /** Short jobs executed with highest priority */
40 JOB_PRIO_HIGH,
41 /** Default job priority */
42 JOB_PRIO_MEDIUM,
43 /** Low priority jobs with thread blocking operations */
44 JOB_PRIO_LOW,
45 JOB_PRIO_MAX
46 };
47
48 /**
49 * Enum names for job priorities
50 */
51 extern enum_name_t *job_priority_names;
52
53 /**
54 * Job requeueing policy.
55 *
56 * The job requeueing policy defines how a job is handled after it has been
57 * executed.
58 */
59 enum job_requeue_t {
60 /** Do not requeue job, destroy it */
61 JOB_REQUEUE_NONE = 0,
62 /** Requeue the job fairly, i.e. it is inserted at the end of the queue */
63 JOB_REQUEUE_FAIR,
64 /** Reexecute the job directly, without the need of requeueing it */
65 JOB_REQUEUE_DIRECT,
66 /** For jobs that rescheduled themselves via scheduler_t */
67 JOB_REQUEUE_SCHEDULED,
68 };
69
70 /**
71 * Job status
72 */
73 enum job_status_t {
74 /** The job is queued and has not yet been executed */
75 JOB_STATUS_QUEUED = 0,
76 /** During execution */
77 JOB_STATUS_EXECUTING,
78 /** If the job got canceled */
79 JOB_STATUS_CANCELED,
80 /** The job was executed successfully */
81 JOB_STATUS_DONE,
82 };
83
84 /**
85 * Job interface as it is stored in the job queue.
86 */
87 struct job_t {
88
89 /**
90 * Status of this job, is modified exclusively by the processor/scheduler
91 */
92 job_status_t status;
93
94 /**
95 * Execute a job.
96 *
97 * The processing facility executes a job using this method. Jobs are
98 * one-shot, they are destroyed after execution (depending on the return
99 * value here), so don't use a job once it has been queued.
100 *
101 * @return policy how to requeue the job
102 */
103 job_requeue_t (*execute) (job_t *this);
104
105 /**
106 * Get the priority of a job.
107 *
108 * @return job priority
109 */
110 job_priority_t (*get_priority)(job_t *this);
111
112 /**
113 * Destroy a job.
114 *
115 * Is called after a job is executed or got canceled. It is also called
116 * for queued jobs that were never executed.
117 *
118 * Use the status of a job to decide what to do during destruction.
119 */
120 void (*destroy) (job_t *this);
121 };
122
123 #endif /** JOB_H_ @}*/