Commit | Line | Data |
---|---|---|
3719602c PC |
1 | /* Copyright (C) 2010-2020 The RetroArch team |
2 | * | |
3 | * --------------------------------------------------------------------------------------- | |
4 | * The following license statement only applies to this file (task_queue.h). | |
5 | * --------------------------------------------------------------------------------------- | |
6 | * | |
7 | * Permission is hereby granted, free of charge, | |
8 | * to any person obtaining a copy of this software and associated documentation files (the "Software"), | |
9 | * to deal in the Software without restriction, including without limitation the rights to | |
10 | * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, | |
11 | * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: | |
12 | * | |
13 | * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. | |
14 | * | |
15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, | |
16 | * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
17 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
18 | * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, | |
19 | * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
20 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
21 | */ | |
22 | ||
23 | #ifndef __LIBRETRO_SDK_TASK_QUEUE_H__ | |
24 | #define __LIBRETRO_SDK_TASK_QUEUE_H__ | |
25 | ||
26 | #include <stdint.h> | |
27 | #include <stddef.h> | |
28 | #include <boolean.h> | |
29 | ||
30 | #include <retro_common.h> | |
31 | #include <retro_common_api.h> | |
32 | ||
33 | #include <libretro.h> | |
34 | ||
35 | RETRO_BEGIN_DECLS | |
36 | ||
37 | enum task_type | |
38 | { | |
39 | TASK_TYPE_NONE, | |
40 | /* Only one blocking task can exist in the queue at a time. | |
41 | * Attempts to add a new one while another is running is | |
42 | * ignored. | |
43 | */ | |
44 | TASK_TYPE_BLOCKING | |
45 | }; | |
46 | ||
47 | typedef struct retro_task retro_task_t; | |
48 | typedef void (*retro_task_callback_t)(retro_task_t *task, | |
49 | void *task_data, | |
50 | void *user_data, const char *error); | |
51 | ||
52 | typedef void (*retro_task_handler_t)(retro_task_t *task); | |
53 | ||
54 | typedef bool (*retro_task_finder_t)(retro_task_t *task, | |
55 | void *userdata); | |
56 | ||
57 | typedef void (*retro_task_queue_msg_t)(retro_task_t *task, | |
58 | const char *msg, | |
59 | unsigned prio, unsigned duration, bool flush); | |
60 | ||
61 | typedef bool (*retro_task_retriever_t)(retro_task_t *task, void *data); | |
62 | ||
63 | typedef bool (*retro_task_condition_fn_t)(void *data); | |
64 | ||
65 | typedef struct | |
66 | { | |
67 | char *source_file; | |
68 | } decompress_task_data_t; | |
69 | ||
70 | struct retro_task | |
71 | { | |
72 | /* when the task should run (0 for as soon as possible) */ | |
73 | retro_time_t when; | |
74 | ||
75 | retro_task_handler_t handler; | |
76 | ||
77 | /* always called from the main loop */ | |
78 | retro_task_callback_t callback; | |
79 | ||
80 | /* task cleanup handler to free allocated resources, will | |
81 | * be called immediately after running the main callback */ | |
82 | retro_task_handler_t cleanup; | |
83 | ||
84 | /* created by the handler, destroyed by the user */ | |
85 | void *task_data; | |
86 | ||
87 | /* owned by the user */ | |
88 | void *user_data; | |
89 | ||
90 | /* created and destroyed by the code related to the handler */ | |
91 | void *state; | |
92 | ||
93 | /* created by task handler; destroyed by main loop | |
94 | * (after calling the callback) */ | |
95 | char *error; | |
96 | ||
97 | void (*progress_cb)(retro_task_t*); | |
98 | ||
99 | /* handler can modify but will be | |
100 | * free()d automatically if non-NULL. */ | |
101 | char *title; | |
102 | ||
103 | /* frontend userdata | |
104 | * (e.g. associate a sticky notification to a task) */ | |
105 | void *frontend_userdata; | |
106 | ||
107 | /* don't touch this. */ | |
108 | retro_task_t *next; | |
109 | ||
110 | /* -1 = unmetered/indeterminate, 0-100 = current progress percentage */ | |
111 | int8_t progress; | |
112 | ||
113 | /* task identifier */ | |
114 | uint32_t ident; | |
115 | ||
116 | enum task_type type; | |
117 | ||
118 | /* if set to true, frontend will | |
119 | use an alternative look for the | |
120 | task progress display */ | |
121 | bool alternative_look; | |
122 | ||
123 | /* set to true by the handler to signal | |
124 | * the task has finished executing. */ | |
125 | bool finished; | |
126 | ||
127 | /* set to true by the task system | |
128 | * to signal the task *must* end. */ | |
129 | bool cancelled; | |
130 | ||
131 | /* if true no OSD messages will be displayed. */ | |
132 | bool mute; | |
133 | }; | |
134 | ||
135 | typedef struct task_finder_data | |
136 | { | |
137 | retro_task_finder_t func; | |
138 | void *userdata; | |
139 | } task_finder_data_t; | |
140 | ||
141 | typedef struct task_retriever_info | |
142 | { | |
143 | struct task_retriever_info *next; | |
144 | void *data; | |
145 | } task_retriever_info_t; | |
146 | ||
147 | typedef struct task_retriever_data | |
148 | { | |
149 | task_retriever_info_t *list; | |
150 | retro_task_handler_t handler; | |
151 | retro_task_retriever_t func; | |
152 | size_t element_size; | |
153 | } task_retriever_data_t; | |
154 | ||
155 | void *task_queue_retriever_info_next(task_retriever_info_t **link); | |
156 | ||
157 | void task_queue_retriever_info_free(task_retriever_info_t *list); | |
158 | ||
159 | /** | |
160 | * Signals a task to end without waiting for | |
161 | * it to complete. */ | |
162 | void task_queue_cancel_task(void *task); | |
163 | ||
164 | void task_set_finished(retro_task_t *task, bool finished); | |
165 | ||
166 | void task_set_mute(retro_task_t *task, bool mute); | |
167 | ||
168 | void task_set_error(retro_task_t *task, char *error); | |
169 | ||
170 | void task_set_progress(retro_task_t *task, int8_t progress); | |
171 | ||
172 | void task_set_title(retro_task_t *task, char *title); | |
173 | ||
174 | void task_set_data(retro_task_t *task, void *data); | |
175 | ||
176 | void task_set_cancelled(retro_task_t *task, bool cancelled); | |
177 | ||
178 | void task_free_title(retro_task_t *task); | |
179 | ||
180 | bool task_get_cancelled(retro_task_t *task); | |
181 | ||
182 | bool task_get_finished(retro_task_t *task); | |
183 | ||
184 | bool task_get_mute(retro_task_t *task); | |
185 | ||
186 | char* task_get_error(retro_task_t *task); | |
187 | ||
188 | int8_t task_get_progress(retro_task_t *task); | |
189 | ||
190 | char* task_get_title(retro_task_t *task); | |
191 | ||
192 | void* task_get_data(retro_task_t *task); | |
193 | ||
194 | bool task_is_on_main_thread(void); | |
195 | ||
196 | void task_queue_set_threaded(void); | |
197 | ||
198 | void task_queue_unset_threaded(void); | |
199 | ||
200 | bool task_queue_is_threaded(void); | |
201 | ||
202 | /** | |
203 | * Calls func for every running task | |
204 | * until it returns true. | |
205 | * Returns a task or NULL if not found. | |
206 | */ | |
207 | bool task_queue_find(task_finder_data_t *find_data); | |
208 | ||
209 | /** | |
210 | * Calls func for every running task when handler | |
211 | * parameter matches task handler, allowing the | |
212 | * list parameter to be filled with user-defined | |
213 | * data. | |
214 | */ | |
215 | void task_queue_retrieve(task_retriever_data_t *data); | |
216 | ||
217 | /* Checks for finished tasks | |
218 | * Takes the finished tasks, if any, | |
219 | * and runs their callbacks. | |
220 | * This must only be called from the main thread. */ | |
221 | void task_queue_check(void); | |
222 | ||
223 | /* Pushes a task | |
224 | * The task will start as soon as possible. | |
225 | * If a second blocking task is attempted, false will be returned | |
226 | * and the task will be ignored. */ | |
227 | bool task_queue_push(retro_task_t *task); | |
228 | ||
229 | /* Blocks until all non-scheduled tasks have finished. | |
230 | * Will return early if cond is not NULL | |
231 | * and cond(data) returns false. | |
232 | * This must only be called from the main thread. */ | |
233 | void task_queue_wait(retro_task_condition_fn_t cond, void* data); | |
234 | ||
235 | /* Sends a signal to terminate all the tasks. | |
236 | * | |
237 | * This won't terminate the tasks immediately. | |
238 | * They will finish as soon as possible. | |
239 | * | |
240 | * This must only be called from the main thread. */ | |
241 | void task_queue_reset(void); | |
242 | ||
243 | /* Deinitializes the task system. | |
244 | * This deinitializes the task system. | |
245 | * The tasks that are running at | |
246 | * the moment will stay on hold */ | |
247 | void task_queue_deinit(void); | |
248 | ||
249 | /* Initializes the task system. | |
250 | * This initializes the task system | |
251 | * and chooses an appropriate | |
252 | * implementation according to the settings. | |
253 | * | |
254 | * This must only be called from the main thread. */ | |
255 | void task_queue_init(bool threaded, retro_task_queue_msg_t msg_push); | |
256 | ||
257 | /* Allocates and inits a new retro_task_t */ | |
258 | retro_task_t *task_init(void); | |
259 | ||
260 | RETRO_END_DECLS | |
261 | ||
262 | #endif |