|
34
|
1 /* |
|
|
2 * task.h -- worker task management |
|
|
3 * |
|
|
4 * Copyright (c) 2021-2022 David Demelier <markand@malikania.fr> |
|
|
5 * |
|
|
6 * Permission to use, copy, modify, and/or distribute this software for any |
|
|
7 * purpose with or without fee is hereby granted, provided that the above |
|
|
8 * copyright notice and this permission notice appear in all copies. |
|
|
9 * |
|
|
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
|
|
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
|
|
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
|
|
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
|
|
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
|
|
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
|
|
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
|
|
17 */ |
|
|
18 |
|
18
|
19 #ifndef SCIWORKERD_TASK_H |
|
|
20 #define SCIWORKERD_TASK_H |
|
|
21 |
|
34
|
22 /** |
|
|
23 * \file task.h |
|
|
24 * \brief Worker task management. |
|
|
25 */ |
|
|
26 |
|
18
|
27 #include <sys/types.h> |
|
|
28 |
|
|
29 struct pollfd; |
|
|
30 struct task; |
|
|
31 |
|
34
|
32 /** |
|
|
33 * \brief Task status. |
|
|
34 */ |
|
18
|
35 enum taskstatus { |
|
34
|
36 TASKSTATUS_PENDING, /*!< not started yet. */ |
|
|
37 TASKSTATUS_RUNNING, /*!< currently running. */ |
|
|
38 TASKSTATUS_EXITED, /*!< process exited normally. */ |
|
|
39 TASKSTATUS_KILLED /*!< process killed killed. */ |
|
18
|
40 }; |
|
|
41 |
|
34
|
42 /** |
|
|
43 * \brief Task termination code. |
|
|
44 */ |
|
18
|
45 struct taskcode { |
|
34
|
46 int exitcode; /*!< Normal exit code (if sigcode == 0). */ |
|
|
47 int sigcode; /*!< Signal termination code (exitcode == 0). */ |
|
18
|
48 }; |
|
|
49 |
|
34
|
50 /** |
|
|
51 * Construct a new task with the given tag. |
|
|
52 * |
|
|
53 * The task is just initialized, you need to call setup and start before |
|
|
54 * continuing |
|
|
55 * |
|
|
56 * \pre tag != NULL |
|
|
57 * \param tag the task tag |
|
|
58 * \return a new initialized task |
|
|
59 */ |
|
18
|
60 struct task * |
|
19
|
61 task_new(const char *tag); |
|
18
|
62 |
|
34
|
63 /** |
|
|
64 * Create a temporary file containing the script code to execute for this task. |
|
|
65 * |
|
|
66 * \pre self != NULL |
|
|
67 * \pre script != NULL |
|
|
68 * \param self the task object |
|
|
69 * \param script the script code to execute |
|
|
70 * \return 0 on success or -1 on error |
|
|
71 */ |
|
18
|
72 int |
|
|
73 task_setup(struct task *self, const char *script); |
|
|
74 |
|
34
|
75 /** |
|
|
76 * Fork the process to start the task. |
|
|
77 * |
|
|
78 * \pre self != NULL |
|
|
79 * \param self the task object |
|
|
80 * \return the child PID on success or -1 on error |
|
|
81 */ |
|
18
|
82 pid_t |
|
|
83 task_start(struct task *self); |
|
|
84 |
|
34
|
85 /** |
|
|
86 * Wait for the task to complete. |
|
|
87 * |
|
|
88 * You should usually call this function when you're sure that the task is over |
|
|
89 * otherwise it would block until it's complete. |
|
|
90 * |
|
|
91 * \pre self != NULL |
|
|
92 * \param self the task object |
|
|
93 * \return 0 on success or -1 one error |
|
|
94 */ |
|
18
|
95 int |
|
|
96 task_wait(struct task *self); |
|
|
97 |
|
34
|
98 /** |
|
|
99 * Send a termination signal to the task. |
|
|
100 * |
|
|
101 * \pre self != NULL |
|
|
102 * \param self the task object |
|
|
103 * \return 0 on success or -1 one error |
|
|
104 */ |
|
18
|
105 int |
|
|
106 task_kill(struct task *self); |
|
|
107 |
|
34
|
108 /** |
|
|
109 * Prepare the pollfd structure with the task pipe. |
|
|
110 * |
|
|
111 * \pre self != NULL |
|
|
112 * \param self the task object |
|
|
113 * \param fd the pollfd structure to fill |
|
|
114 */ |
|
18
|
115 void |
|
|
116 task_prepare(struct task *self, struct pollfd *fd); |
|
|
117 |
|
34
|
118 /** |
|
|
119 * Synchronize the child output. |
|
|
120 * |
|
|
121 * The following return values are possible: |
|
|
122 * |
|
|
123 * == 0: child exited |
|
|
124 * >= 0: data has been received, keep going |
|
|
125 * < 0: I/O error, you should kill and wait |
|
|
126 * |
|
|
127 * \pre self != NULL |
|
|
128 * \param self the task object |
|
|
129 * \param fd the pollfd structure result |
|
|
130 * \return various condition as described |
|
|
131 */ |
|
18
|
132 int |
|
|
133 task_sync(struct task *self, const struct pollfd *fd); |
|
|
134 |
|
34
|
135 /** |
|
|
136 * Tells when the task has been started. |
|
|
137 * |
|
|
138 * \pre self != NULL |
|
|
139 * \param self the task object |
|
|
140 */ |
|
18
|
141 time_t |
|
|
142 task_uptime(const struct task *self); |
|
|
143 |
|
34
|
144 /** |
|
|
145 * Returns the task PID. |
|
|
146 * |
|
|
147 * \pre self != NULL |
|
|
148 * \param self the task object |
|
|
149 * \return the task PID |
|
|
150 * \warning the task must be running |
|
|
151 */ |
|
19
|
152 pid_t |
|
|
153 task_pid(const struct task *self); |
|
|
154 |
|
34
|
155 /** |
|
|
156 * Return the task console output. |
|
|
157 * |
|
|
158 * \pre self != NULL |
|
|
159 * \param self the task object |
|
|
160 * \return the console output or NULL if none |
|
|
161 */ |
|
18
|
162 const char * |
|
|
163 task_console(const struct task *self); |
|
|
164 |
|
34
|
165 /** |
|
|
166 * Get the task status. |
|
|
167 * |
|
|
168 * \pre self != NULL |
|
|
169 * \param self the task object |
|
|
170 * \return the current task status |
|
|
171 */ |
|
18
|
172 enum taskstatus |
|
|
173 task_status(const struct task *self); |
|
|
174 |
|
34
|
175 /** |
|
|
176 * Get the task exit or signal code |
|
|
177 * |
|
|
178 * \pre self != NULL |
|
|
179 * \param self the task object |
|
|
180 * \return the task exit/signal codes |
|
|
181 */ |
|
18
|
182 struct taskcode |
|
|
183 task_code(const struct task *self); |
|
|
184 |
|
34
|
185 /** |
|
|
186 * Free the task and its resources. |
|
|
187 * |
|
|
188 * \pre self != NULL |
|
|
189 * \param self the task object |
|
|
190 * \warning the task must not be running |
|
|
191 */ |
|
18
|
192 void |
|
|
193 task_free(struct task *self); |
|
|
194 |
|
|
195 #endif /* !SCIWORKERD_TASK_H */ |
