1 /* Copyright (C) 2010-2020 The RetroArch team
3 * ---------------------------------------------------------------------------------------
4 * The following license statement only applies to this file (task_queue.h).
5 * ---------------------------------------------------------------------------------------
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:
13 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
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.
23 #ifndef __LIBRETRO_SDK_TASK_QUEUE_H__
24 #define __LIBRETRO_SDK_TASK_QUEUE_H__
30 #include <retro_common.h>
31 #include <retro_common_api.h>
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
47 typedef struct retro_task retro_task_t;
48 typedef void (*retro_task_callback_t)(retro_task_t *task,
50 void *user_data, const char *error);
52 typedef void (*retro_task_handler_t)(retro_task_t *task);
54 typedef bool (*retro_task_finder_t)(retro_task_t *task,
57 typedef void (*retro_task_queue_msg_t)(retro_task_t *task,
59 unsigned prio, unsigned duration, bool flush);
61 typedef bool (*retro_task_retriever_t)(retro_task_t *task, void *data);
63 typedef bool (*retro_task_condition_fn_t)(void *data);
68 } decompress_task_data_t;
72 /* when the task should run (0 for as soon as possible) */
75 retro_task_handler_t handler;
77 /* always called from the main loop */
78 retro_task_callback_t callback;
80 /* task cleanup handler to free allocated resources, will
81 * be called immediately after running the main callback */
82 retro_task_handler_t cleanup;
84 /* created by the handler, destroyed by the user */
87 /* owned by the user */
90 /* created and destroyed by the code related to the handler */
93 /* created by task handler; destroyed by main loop
94 * (after calling the callback) */
97 void (*progress_cb)(retro_task_t*);
99 /* handler can modify but will be
100 * free()d automatically if non-NULL. */
104 * (e.g. associate a sticky notification to a task) */
105 void *frontend_userdata;
107 /* don't touch this. */
110 /* -1 = unmetered/indeterminate, 0-100 = current progress percentage */
113 /* task identifier */
118 /* if set to true, frontend will
119 use an alternative look for the
120 task progress display */
121 bool alternative_look;
123 /* set to true by the handler to signal
124 * the task has finished executing. */
127 /* set to true by the task system
128 * to signal the task *must* end. */
131 /* if true no OSD messages will be displayed. */
135 typedef struct task_finder_data
137 retro_task_finder_t func;
139 } task_finder_data_t;
141 typedef struct task_retriever_info
143 struct task_retriever_info *next;
145 } task_retriever_info_t;
147 typedef struct task_retriever_data
149 task_retriever_info_t *list;
150 retro_task_handler_t handler;
151 retro_task_retriever_t func;
153 } task_retriever_data_t;
155 void *task_queue_retriever_info_next(task_retriever_info_t **link);
157 void task_queue_retriever_info_free(task_retriever_info_t *list);
160 * Signals a task to end without waiting for
162 void task_queue_cancel_task(void *task);
164 void task_set_finished(retro_task_t *task, bool finished);
166 void task_set_mute(retro_task_t *task, bool mute);
168 void task_set_error(retro_task_t *task, char *error);
170 void task_set_progress(retro_task_t *task, int8_t progress);
172 void task_set_title(retro_task_t *task, char *title);
174 void task_set_data(retro_task_t *task, void *data);
176 void task_set_cancelled(retro_task_t *task, bool cancelled);
178 void task_free_title(retro_task_t *task);
180 bool task_get_cancelled(retro_task_t *task);
182 bool task_get_finished(retro_task_t *task);
184 bool task_get_mute(retro_task_t *task);
186 char* task_get_error(retro_task_t *task);
188 int8_t task_get_progress(retro_task_t *task);
190 char* task_get_title(retro_task_t *task);
192 void* task_get_data(retro_task_t *task);
194 bool task_is_on_main_thread(void);
196 void task_queue_set_threaded(void);
198 void task_queue_unset_threaded(void);
200 bool task_queue_is_threaded(void);
203 * Calls func for every running task
204 * until it returns true.
205 * Returns a task or NULL if not found.
207 bool task_queue_find(task_finder_data_t *find_data);
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
215 void task_queue_retrieve(task_retriever_data_t *data);
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);
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);
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);
235 /* Sends a signal to terminate all the tasks.
237 * This won't terminate the tasks immediately.
238 * They will finish as soon as possible.
240 * This must only be called from the main thread. */
241 void task_queue_reset(void);
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);
249 /* Initializes the task system.
250 * This initializes the task system
251 * and chooses an appropriate
252 * implementation according to the settings.
254 * This must only be called from the main thread. */
255 void task_queue_init(bool threaded, retro_task_queue_msg_t msg_push);
257 /* Allocates and inits a new retro_task_t */
258 retro_task_t *task_init(void);