Annotation of embedaddon/strongswan/src/libstrongswan/processing/jobs/job.h, revision 1.1.1.1
1.1 misho 1: /*
2: * Copyright (C) 2012 Tobias Brunner
3: * Copyright (C) 2005-2006 Martin Willi
4: * Copyright (C) 2005 Jan Hutter
5: * HSR 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_status_t job_status_t;
29: typedef enum job_requeue_type_t job_requeue_type_t;
30: typedef struct job_requeue_t job_requeue_t;
31:
32: #include <library.h>
33:
34: /**
35: * Priority classes of jobs
36: */
37: enum job_priority_t {
38: /** Critical infrastructure jobs that should always been served */
39: JOB_PRIO_CRITICAL = 0,
40: /** Short jobs executed with highest priority */
41: JOB_PRIO_HIGH,
42: /** Default job priority */
43: JOB_PRIO_MEDIUM,
44: /** Low priority jobs with thread blocking operations */
45: JOB_PRIO_LOW,
46: JOB_PRIO_MAX
47: };
48:
49: /**
50: * Enum names for job priorities
51: */
52: extern enum_name_t *job_priority_names;
53:
54: /**
55: * Job status
56: */
57: enum job_status_t {
58: /** The job is queued and has not yet been executed */
59: JOB_STATUS_QUEUED = 0,
60: /** During execution */
61: JOB_STATUS_EXECUTING,
62: /** If the job got canceled */
63: JOB_STATUS_CANCELED,
64: /** The job was executed successfully */
65: JOB_STATUS_DONE,
66: };
67:
68: /**
69: * How a job is handled after is has been executed.
70: */
71: enum job_requeue_type_t {
72: /** Do not requeue job, destroy it */
73: JOB_REQUEUE_TYPE_NONE = 0,
74: /** Requeue the job fairly, i.e. it is inserted at the end of the queue */
75: JOB_REQUEUE_TYPE_FAIR,
76: /** Reexecute the job directly, without the need of requeueing it */
77: JOB_REQUEUE_TYPE_DIRECT,
78: /** Rescheduled the job via scheduler_t */
79: JOB_REQUEUE_TYPE_SCHEDULE,
80: };
81:
82: /**
83: * Job requeueing policy.
84: *
85: * The job requeueing policy defines how a job is handled after it has been
86: * executed.
87: */
88: struct job_requeue_t {
89: /** How to handle the job after executing it */
90: job_requeue_type_t type;
91: /** How to reschedule the job, if so */
92: enum {
93: JOB_SCHEDULE,
94: JOB_SCHEDULE_MS,
95: JOB_SCHEDULE_TV,
96: } schedule;
97: /** Time to reschedule the job */
98: union {
99: uint32_t rel;
100: timeval_t abs;
101: } time;
102: };
103:
104: /**
105: * Helper macros to easily define requeueing policies.
106: */
107: #define __JOB_REQUEUE(t) (job_requeue_t){ .type = t }
108: #define JOB_REQUEUE_NONE __JOB_REQUEUE(JOB_REQUEUE_TYPE_NONE)
109: #define JOB_REQUEUE_FAIR __JOB_REQUEUE(JOB_REQUEUE_TYPE_FAIR)
110: #define JOB_REQUEUE_DIRECT __JOB_REQUEUE(JOB_REQUEUE_TYPE_DIRECT)
111: #define __JOB_RESCHEDULE(t, ...) (job_requeue_t){ .type = JOB_REQUEUE_TYPE_SCHEDULE, .schedule = t, { __VA_ARGS__ } }
112: #define JOB_RESCHEDULE(s) __JOB_RESCHEDULE(JOB_SCHEDULE, .rel = s)
113: #define JOB_RESCHEDULE_MS(ms) __JOB_RESCHEDULE(JOB_SCHEDULE_MS, .rel = ms)
114: #define JOB_RESCHEDULE_TV(tv) __JOB_RESCHEDULE(JOB_SCHEDULE_TV, .abs = tv)
115:
116: /**
117: * Job interface as it is stored in the job queue.
118: */
119: struct job_t {
120:
121: /**
122: * Status of this job, is modified exclusively by the processor/scheduler
123: */
124: job_status_t status;
125:
126: /**
127: * Execute a job.
128: *
129: * The processing facility executes a job using this method. Jobs are
130: * one-shot, they are destroyed after execution (depending on the return
131: * value here), so don't use a job once it has been queued.
132: *
133: * @return policy how to requeue the job
134: */
135: job_requeue_t (*execute) (job_t *this);
136:
137: /**
138: * Cancel a job.
139: *
140: * Implementing this method is optional. It allows potentially blocking
141: * jobs to be canceled during shutdown.
142: *
143: * If no special action is to be taken simply return FALSE then the thread
144: * executing the job will be canceled. If TRUE is returned the job is
145: * expected to return from execute() itself (i.e. the thread won't be
146: * canceled explicitly and can still be joined later).
147: * Jobs that return FALSE have to make sure they provide the appropriate
148: * cancellation points.
149: *
150: * @note Regular jobs that do not block MUST NOT implement this method.
151: * @note This method could be called even before execute() has been called.
152: *
153: * @return FALSE to cancel the thread, TRUE if canceled otherwise
154: */
155: bool (*cancel)(job_t *this);
156:
157: /**
158: * Get the priority of a job.
159: *
160: * @return job priority
161: */
162: job_priority_t (*get_priority)(job_t *this);
163:
164: /**
165: * Destroy a job.
166: *
167: * Is called after a job is executed or got canceled. It is also called
168: * for queued jobs that were never executed.
169: *
170: * Use the status of a job to decide what to do during destruction.
171: */
172: void (*destroy)(job_t *this);
173: };
174:
175: #endif /** JOB_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>