diff options
author | lurchi <lurchi@strangeplace.net> | 2018-02-01 19:54:54 +0100 |
---|---|---|
committer | lurchi <lurchi@strangeplace.net> | 2018-02-01 19:55:15 +0100 |
commit | 89d1b38101ea52dfe7ef20ab8f6604a6f973bbbd (patch) | |
tree | 5af6e4158cb3d996ed0e68abe0216d62ce4d6a86 /src/include/gnunet_scheduler_lib.h | |
parent | b3fdd5716f3e0622508e68450516d11a6d55a0ab (diff) | |
download | gnunet-89d1b38101ea52dfe7ef20ab8f6604a6f973bbbd.tar.gz gnunet-89d1b38101ea52dfe7ef20ab8f6604a6f973bbbd.zip |
scheduler API change to allow use with js event loop
- GNUNET_SCHEDUELR_run_with_driver has been replaced with
GNUNET_SCHEDULER_driver_init and GNUNET_SCHEDUELR_driver_done
- GNUNET_SCHEDULER_run_from_driver has been renamed to
GNUNET_SCHEDULER_do_work (as it's no longer being called from a driver
callback)
- documentation has been updated
Diffstat (limited to 'src/include/gnunet_scheduler_lib.h')
-rw-r--r-- | src/include/gnunet_scheduler_lib.h | 195 |
1 files changed, 133 insertions, 62 deletions
diff --git a/src/include/gnunet_scheduler_lib.h b/src/include/gnunet_scheduler_lib.h index d2805a685..e5c361567 100644 --- a/src/include/gnunet_scheduler_lib.h +++ b/src/include/gnunet_scheduler_lib.h | |||
@@ -237,29 +237,32 @@ struct GNUNET_SCHEDULER_Handle; | |||
237 | 237 | ||
238 | 238 | ||
239 | /** | 239 | /** |
240 | * Function called by the driver to tell the scheduler to run some of | 240 | * Function called by external event loop implementations to tell the |
241 | * the tasks that are ready. This function may return even though | 241 | * scheduler to run some of the tasks that are ready. Must be called |
242 | * there are tasks left to run just to give other tasks a chance as | 242 | * only after #GNUNET_SCHEDULER_driver_init has been called and before |
243 | * well. If we return #GNUNET_YES, the driver should call this | 243 | * #GNUNET_SCHEDULER_driver_done is called. |
244 | * function again as soon as possible, while if we return #GNUNET_NO | 244 | * This function may return even though there are tasks left to run |
245 | * it must block until either the operating system has more work (the | 245 | * just to give other tasks a chance as well. If we return #GNUNET_YES, |
246 | * scheduler has no more work to do right now) or the timeout set by | 246 | * the event loop implementation should call this function again as |
247 | * the scheduler (using the set_wakeup callback) is reached. | 247 | * soon as possible, while if we return #GNUNET_NO it must block until |
248 | * | 248 | * either the operating system has more work (the scheduler has no more |
249 | * @param sh scheduler handle that was given to the `loop` | 249 | * work to do right now) or the timeout set by the scheduler (using the |
250 | * @return #GNUNET_OK if there are more tasks that are ready, | 250 | * set_wakeup callback) is reached. |
251 | * and thus we would like to run more (yield to avoid | 251 | * |
252 | * blocking other activities for too long) | 252 | * @param sh scheduler handle that was returned by |
253 | * #GNUNET_NO if we are done running tasks (yield to block) | 253 | * #GNUNET_SCHEDULER_driver_init |
254 | * #GNUNET_SYSERR on error, e.g. no tasks were ready | 254 | * @return #GNUNET_YES if there are more tasks that are ready, |
255 | * and thus we would like to run more (yield to avoid | ||
256 | * blocking other activities for too long) #GNUNET_NO | ||
257 | * if we are done running tasks (yield to block) | ||
255 | */ | 258 | */ |
256 | int | 259 | int |
257 | GNUNET_SCHEDULER_run_from_driver (struct GNUNET_SCHEDULER_Handle *sh); | 260 | GNUNET_SCHEDULER_do_work (struct GNUNET_SCHEDULER_Handle *sh); |
258 | 261 | ||
259 | 262 | ||
260 | /** | 263 | /** |
261 | * API a driver has to implement for | 264 | * API an external event loop has to implement for |
262 | * #GNUNET_SCHEDULER_run_with_driver(). | 265 | * #GNUNET_SCHEDULER_driver_init. |
263 | */ | 266 | */ |
264 | struct GNUNET_SCHEDULER_Driver | 267 | struct GNUNET_SCHEDULER_Driver |
265 | { | 268 | { |
@@ -311,23 +314,6 @@ struct GNUNET_SCHEDULER_Driver | |||
311 | (*set_wakeup)(void *cls, | 314 | (*set_wakeup)(void *cls, |
312 | struct GNUNET_TIME_Absolute dt); | 315 | struct GNUNET_TIME_Absolute dt); |
313 | 316 | ||
314 | /** | ||
315 | * Event loop's "main" function, to be called from | ||
316 | * #GNUNET_SCHEDULER_run_with_driver() to actually | ||
317 | * launch the loop. The loop should run as long as | ||
318 | * tasks (added by the add callback) are available | ||
319 | * OR the wakeup time (added by the set_wakeup | ||
320 | * callback) is not FOREVER. | ||
321 | * | ||
322 | * @param cls closure | ||
323 | * @param sh scheduler handle to pass to | ||
324 | * #GNUNET_SCHEDULER_run_from_driver() | ||
325 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | ||
326 | */ | ||
327 | int | ||
328 | (*loop)(void *cls, | ||
329 | struct GNUNET_SCHEDULER_Handle *sh); | ||
330 | |||
331 | }; | 317 | }; |
332 | 318 | ||
333 | 319 | ||
@@ -341,25 +327,55 @@ typedef void | |||
341 | 327 | ||
342 | 328 | ||
343 | /** | 329 | /** |
344 | * Initialize and run scheduler. This function will return when all | 330 | * Function called by external event loop implementations to initialize |
345 | * tasks have completed. On systems with signals, receiving a SIGTERM | 331 | * the scheduler. An external implementation has to provide @a driver |
346 | * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown | 332 | * which contains callbacks for the scheduler (see definition of struct |
347 | * to be run after the active task is complete. As a result, SIGTERM | 333 | * #GNUNET_SCHEDULER_Driver) for instructing the external implementation |
348 | * causes all shutdown tasks to be scheduled with reason | 334 | * to watch for events. If it detects any event it is expected to call |
349 | * #GNUNET_SCHEDULER_REASON_SHUTDOWN. (However, tasks added | 335 | * #GNUNET_SCHEDULER_do_work to let the scheduler handle it. If an event |
350 | * afterwards will execute normally!). Note that any particular | 336 | * is related to a specific task (e.g. the scheduler gave instructions |
351 | * signal will only shut down one scheduler; applications should | 337 | * to watch a file descriptor), the external implementation is expected |
352 | * always only create a single scheduler. | 338 | * to mark that task ready before by calling #GNUNET_SCHEDULER_task_ready. |
339 | |||
340 | * This function has to be called before any tasks are scheduled and | ||
341 | * before GNUNET_SCHEDULER_do_work is called for the first time. It | ||
342 | * allocates resources that have to be freed again by calling | ||
343 | * #GNUNET_SCHEDULER_driver_done. | ||
353 | * | 344 | * |
354 | * @param driver drive to use for the event loop | 345 | * This function installs the same signal handlers as |
355 | * @param task task to run first (and immediately) | 346 | * #GNUNET_SCHEDULER_run. This means SIGTERM (and other similar signals) |
356 | * @param task_cls closure of @a task | 347 | * will induce a call to #GNUNET_SCHEDULER_shutdown during the next |
357 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | 348 | * call to #GNUNET_SCHEDULER_do_work. As a result, SIGTERM causes all |
349 | * active tasks to be scheduled with reason | ||
350 | * #GNUNET_SCHEDULER_REASON_SHUTDOWN. (However, tasks added afterwards | ||
351 | * will execute normally!). Note that any particular signal will only | ||
352 | * shut down one scheduler; applications should always only create a | ||
353 | * single scheduler. | ||
354 | * | ||
355 | * @param driver to use for the event loop | ||
356 | * @return handle to be passed to #GNUNET_SCHEDULER_do_work and | ||
357 | * #GNUNET_SCHEDULER_driver_done | ||
358 | */ | 358 | */ |
359 | int | 359 | struct GNUNET_SCHEDULER_Handle * |
360 | GNUNET_SCHEDULER_run_with_driver (const struct GNUNET_SCHEDULER_Driver *driver, | 360 | GNUNET_SCHEDULER_driver_init (const struct GNUNET_SCHEDULER_Driver *driver); |
361 | GNUNET_SCHEDULER_TaskCallback task, | 361 | |
362 | void *task_cls); | 362 | |
363 | /** | ||
364 | * Counter-part of #GNUNET_SCHEDULER_driver_init. Has to be called | ||
365 | * by external event loop implementations after the scheduler has | ||
366 | * shut down. This is the case if both of the following conditions | ||
367 | * are met: | ||
368 | * | ||
369 | * - all tasks the scheduler has added through the driver's add | ||
370 | * callback have been removed again through the driver's del | ||
371 | * callback | ||
372 | * - the timeout the scheduler has set through the driver's | ||
373 | * add_wakeup callback is FOREVER | ||
374 | * | ||
375 | * @param sh the handle returned by #GNUNET_SCHEDULER_driver_init | ||
376 | */ | ||
377 | void | ||
378 | GNUNET_SCHEDULER_driver_done (struct GNUNET_SCHEDULER_Handle *sh); | ||
363 | 379 | ||
364 | 380 | ||
365 | /** | 381 | /** |
@@ -462,10 +478,15 @@ GNUNET_SCHEDULER_get_task_context (void); | |||
462 | 478 | ||
463 | /** | 479 | /** |
464 | * Cancel the task with the specified identifier. | 480 | * Cancel the task with the specified identifier. |
465 | * The task must not yet have run. | 481 | * The task must not yet have run. Only allowed to be called as long as the |
482 | * scheduler is running, that is one of the following conditions is met: | ||
483 | * | ||
484 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
485 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
486 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
466 | * | 487 | * |
467 | * @param task id of the task to cancel | 488 | * @param task id of the task to cancel |
468 | * @return the closure of the callback of the cancelled task | 489 | * @return original closure of the task |
469 | */ | 490 | */ |
470 | void * | 491 | void * |
471 | GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task); | 492 | GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task); |
@@ -634,6 +655,12 @@ GNUNET_SCHEDULER_add_at_with_priority (struct GNUNET_TIME_Absolute at, | |||
634 | * used as a timeout on the socket being ready. The task will be | 655 | * used as a timeout on the socket being ready. The task will be |
635 | * scheduled for execution once either the delay has expired or the | 656 | * scheduled for execution once either the delay has expired or the |
636 | * socket operation is ready. It will be run with the DEFAULT priority. | 657 | * socket operation is ready. It will be run with the DEFAULT priority. |
658 | * Only allowed to be called as long as the scheduler is running, that | ||
659 | * is one of the following conditions is met: | ||
660 | * | ||
661 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
662 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
663 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
637 | * | 664 | * |
638 | * @param delay when should this operation time out? | 665 | * @param delay when should this operation time out? |
639 | * @param rfd read file-descriptor | 666 | * @param rfd read file-descriptor |
@@ -656,6 +683,12 @@ GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay, | |||
656 | * socket being ready. The task will be scheduled for execution once | 683 | * socket being ready. The task will be scheduled for execution once |
657 | * either the delay has expired or the socket operation is ready. It | 684 | * either the delay has expired or the socket operation is ready. It |
658 | * will be run with the DEFAULT priority. | 685 | * will be run with the DEFAULT priority. |
686 | * Only allowed to be called as long as the scheduler is running, that | ||
687 | * is one of the following conditions is met: | ||
688 | * | ||
689 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
690 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
691 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
659 | * | 692 | * |
660 | * @param delay when should this operation time out? | 693 | * @param delay when should this operation time out? |
661 | * @param priority priority to use for the task | 694 | * @param priority priority to use for the task |
@@ -678,9 +711,16 @@ GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay, | |||
678 | * specified file descriptor is ready for writing. The delay can be | 711 | * specified file descriptor is ready for writing. The delay can be |
679 | * used as a timeout on the socket being ready. The task will be | 712 | * used as a timeout on the socket being ready. The task will be |
680 | * scheduled for execution once either the delay has expired or the | 713 | * scheduled for execution once either the delay has expired or the |
681 | * socket operation is ready. It will be run with the DEFAULT priority. | 714 | * socket operation is ready. It will be run with the priority of |
715 | * the calling task. | ||
716 | * Only allowed to be called as long as the scheduler is running, that | ||
717 | * is one of the following conditions is met: | ||
718 | * | ||
719 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
720 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
721 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
682 | * | 722 | * |
683 | * * @param delay when should this operation time out? | 723 | * @param delay when should this operation time out? |
684 | * @param wfd write file-descriptor | 724 | * @param wfd write file-descriptor |
685 | * @param task main function of the task | 725 | * @param task main function of the task |
686 | * @param task_cls closure of @a task | 726 | * @param task_cls closure of @a task |
@@ -700,6 +740,12 @@ GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay, | |||
700 | * used as a timeout on the socket being ready. The task will be | 740 | * used as a timeout on the socket being ready. The task will be |
701 | * scheduled for execution once either the delay has expired or the | 741 | * scheduled for execution once either the delay has expired or the |
702 | * socket operation is ready. | 742 | * socket operation is ready. |
743 | * Only allowed to be called as long as the scheduler is running, that | ||
744 | * is one of the following conditions is met: | ||
745 | * | ||
746 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
747 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
748 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
703 | * | 749 | * |
704 | * @param delay when should this operation time out? | 750 | * @param delay when should this operation time out? |
705 | * @param priority priority of the task | 751 | * @param priority priority of the task |
@@ -707,7 +753,7 @@ GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay, | |||
707 | * @param on_read whether to poll the file-descriptor for readability | 753 | * @param on_read whether to poll the file-descriptor for readability |
708 | * @param on_write whether to poll the file-descriptor for writability | 754 | * @param on_write whether to poll the file-descriptor for writability |
709 | * @param task main function of the task | 755 | * @param task main function of the task |
710 | * @param task_cls closure of @a task | 756 | * @param task_cls closure of task |
711 | * @return unique task identifier for the job | 757 | * @return unique task identifier for the job |
712 | * only valid until "task" is started! | 758 | * only valid until "task" is started! |
713 | */ | 759 | */ |
@@ -720,19 +766,26 @@ GNUNET_SCHEDULER_add_net_with_priority (struct GNUNET_TIME_Relative delay, | |||
720 | GNUNET_SCHEDULER_TaskCallback task, | 766 | GNUNET_SCHEDULER_TaskCallback task, |
721 | void *task_cls); | 767 | void *task_cls); |
722 | 768 | ||
769 | |||
723 | /** | 770 | /** |
724 | * Schedule a new task to be run with a specified delay or when the | 771 | * Schedule a new task to be run with a specified delay or when the |
725 | * specified file descriptor is ready for reading. The delay can be | 772 | * specified file descriptor is ready for reading. The delay can be |
726 | * used as a timeout on the socket being ready. The task will be | 773 | * used as a timeout on the socket being ready. The task will be |
727 | * scheduled for execution once either the delay has expired or the | 774 | * scheduled for execution once either the delay has expired or the |
728 | * socket operation is ready. It will be run with the DEFAULT priority. | 775 | * socket operation is ready. It will be run with the DEFAULT priority. |
776 | * Only allowed to be called as long as the scheduler is running, that | ||
777 | * is one of the following conditions is met: | ||
778 | * | ||
779 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
780 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
781 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
729 | * | 782 | * |
730 | * * @param delay when should this operation time out? | 783 | * @param delay when should this operation time out? |
731 | * @param rfd read file-descriptor | 784 | * @param rfd read file-descriptor |
732 | * @param task main function of the task | 785 | * @param task main function of the task |
733 | * @param task_cls closure of @a task | 786 | * @param task_cls closure of @a task |
734 | * @return unique task identifier for the job | 787 | * @return unique task identifier for the job |
735 | * only valid until "task" is started! | 788 | * only valid until @a task is started! |
736 | */ | 789 | */ |
737 | struct GNUNET_SCHEDULER_Task * | 790 | struct GNUNET_SCHEDULER_Task * |
738 | GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay, | 791 | GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay, |
@@ -747,8 +800,14 @@ GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay, | |||
747 | * used as a timeout on the socket being ready. The task will be | 800 | * used as a timeout on the socket being ready. The task will be |
748 | * scheduled for execution once either the delay has expired or the | 801 | * scheduled for execution once either the delay has expired or the |
749 | * socket operation is ready. It will be run with the DEFAULT priority. | 802 | * socket operation is ready. It will be run with the DEFAULT priority. |
803 | * Only allowed to be called as long as the scheduler is running, that | ||
804 | * is one of the following conditions is met: | ||
805 | * | ||
806 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
807 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
808 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
750 | * | 809 | * |
751 | * * @param delay when should this operation time out? | 810 | * @param delay when should this operation time out? |
752 | * @param wfd write file-descriptor | 811 | * @param wfd write file-descriptor |
753 | * @param task main function of the task | 812 | * @param task main function of the task |
754 | * @param task_cls closure of @a task | 813 | * @param task_cls closure of @a task |
@@ -768,6 +827,12 @@ GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay, | |||
768 | * used as a timeout on the socket being ready. The task will be | 827 | * used as a timeout on the socket being ready. The task will be |
769 | * scheduled for execution once either the delay has expired or the | 828 | * scheduled for execution once either the delay has expired or the |
770 | * socket operation is ready. | 829 | * socket operation is ready. |
830 | * Only allowed to be called as long as the scheduler is running, that | ||
831 | * is one of the following conditions is met: | ||
832 | * | ||
833 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
834 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
835 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
771 | * | 836 | * |
772 | * @param delay when should this operation time out? | 837 | * @param delay when should this operation time out? |
773 | * @param priority priority of the task | 838 | * @param priority priority of the task |
@@ -801,8 +866,14 @@ GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay, | |||
801 | * (prerequisite-run) | 866 | * (prerequisite-run) |
802 | * && (delay-ready | 867 | * && (delay-ready |
803 | * || any-rs-ready | 868 | * || any-rs-ready |
804 | * || any-ws-ready) | 869 | * || any-ws-ready) ) |
805 | * </code> | 870 | * </code> |
871 | * Only allowed to be called as long as the scheduler is running, that | ||
872 | * is one of the following conditions is met: | ||
873 | * | ||
874 | * - #GNUNET_SCHEDULER_run has been called and has not returned yet | ||
875 | * - #GNUNET_SCHEDULER_driver_init has been run and | ||
876 | * #GNUNET_SCHEDULER_driver_done has not been called yet | ||
806 | * | 877 | * |
807 | * @param prio how important is this task? | 878 | * @param prio how important is this task? |
808 | * @param delay how long should we wait? | 879 | * @param delay how long should we wait? |
@@ -811,7 +882,7 @@ GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay, | |||
811 | * @param task main function of the task | 882 | * @param task main function of the task |
812 | * @param task_cls closure of @a task | 883 | * @param task_cls closure of @a task |
813 | * @return unique task identifier for the job | 884 | * @return unique task identifier for the job |
814 | * only valid until "task" is started! | 885 | * only valid until @a task is started! |
815 | */ | 886 | */ |
816 | struct GNUNET_SCHEDULER_Task * | 887 | struct GNUNET_SCHEDULER_Task * |
817 | GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio, | 888 | GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio, |