src/include/gnunet_scheduler_lib.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2009-2016 GNUnet e.V.
   4
   5       GNUnet is free software: you can redistribute it and/or modify it
   6       under the terms of the GNU Affero General Public License as published
   7       by the Free Software Foundation, either version 3 of the License,
   8       or (at your option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       Affero General Public License for more details.
  14
  15       You should have received a copy of the GNU Affero General Public License
  16       along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * API to schedule computations using continuation passing style
  26  *
  27  * @defgroup scheduler  Scheduler library
  28  * Event loop (scheduler)
  29  *
  30  * Schedule computations using continuation passing style.
  31  *
  32  * @{
  33  */
  34
  35 #ifndef GNUNET_SCHEDULER_LIB_H
  36 #define GNUNET_SCHEDULER_LIB_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 /**
  47  * Opaque reference to a task.
  48  */
  49 struct GNUNET_SCHEDULER_Task;
  50
  51 /**
  52  * Reasons why the schedule may have triggered
  53  * the task now.
  54  */
  55 enum GNUNET_SCHEDULER_Reason
  56 {
  57   /**
  58    * This task is not ready.
  59    */
  60   GNUNET_SCHEDULER_REASON_NONE = 0,
  61
  62   /**
  63    * This is the very first task run during startup.
  64    */
  65   GNUNET_SCHEDULER_REASON_STARTUP = 1,
  66
  67   /**
  68    * We are shutting down and are running all shutdown-related tasks.
  69    */
  70   GNUNET_SCHEDULER_REASON_SHUTDOWN = 2,
  71
  72   /**
  73    * The specified timeout has expired.
  74    * (also set if the delay given was 0).
  75    */
  76   GNUNET_SCHEDULER_REASON_TIMEOUT = 4,
  77
  78   /**
  79    * The reading socket is ready.
  80    */
  81   GNUNET_SCHEDULER_REASON_READ_READY = 8,
  82
  83   /**
  84    * The writing socket is ready.
  85    */
  86   GNUNET_SCHEDULER_REASON_WRITE_READY = 16,
  87
  88   /**
  89    * The prerequisite task is done.
  90    */
  91   GNUNET_SCHEDULER_REASON_PREREQ_DONE = 32
  92 };
  93
  94
  95 #include "gnunet_time_lib.h"
  96 #include "gnunet_network_lib.h"
  97
  98
  99 /**
 100  * Possible events on FDs, used as a bitmask.
 101  * Modelled after GPollFD.
 102  */
 103 enum GNUNET_SCHEDULER_EventType
 104 {
 105   /**
 106    * No event (useful for timeout).
 107    */
 108   GNUNET_SCHEDULER_ET_NONE = 0,
 109
 110   /**
 111    * Data available for reading.
 112    */
 113   GNUNET_SCHEDULER_ET_IN = 1,
 114
 115   /**
 116    * Buffer available for writing.
 117    */
 118   GNUNET_SCHEDULER_ET_OUT = 2,
 119
 120   /**
 121    *
 122    */
 123   GNUNET_SCHEDULER_ET_HUP = 4,
 124
 125   /**
 126    *
 127    */
 128   GNUNET_SCHEDULER_ET_ERR = 8,
 129
 130   /**
 131    *
 132    */
 133   GNUNET_SCHEDULER_ET_PRI = 16,
 134
 135   /**
 136    *
 137    */
 138   GNUNET_SCHEDULER_ET_NVAL = 32
 139 };
 140
 141
 142 /**
 143  * Information about an event relating to a file descriptor/socket.
 144  */
 145 struct GNUNET_SCHEDULER_FdInfo
 146 {
 147   /**
 148    * GNUnet network socket the event is about, matches @a sock,
 149    * NULL if this is about a file handle or if no network
 150    * handle was given to the scheduler originally.
 151    */
 152   const struct GNUNET_NETWORK_Handle *fd;
 153
 154   /**
 155    * GNUnet file handle the event is about, matches @a sock,
 156    * NULL if this is about a network socket or if no network
 157    * handle was given to the scheduler originally.
 158    */
 159   const struct GNUNET_DISK_FileHandle *fh;
 160
 161   /**
 162    * Type of the event that was generated related to @e sock.
 163    */
 164   enum GNUNET_SCHEDULER_EventType et;
 165
 166   /**
 167    * Underlying OS handle the event was about.
 168    */
 169   int sock;
 170 };
 171
 172
 173 /**
 174  * Context information passed to each scheduler task.
 175  */
 176 struct GNUNET_SCHEDULER_TaskContext
 177 {
 178   /**
 179    * Reason why the task is run now
 180    */
 181   enum GNUNET_SCHEDULER_Reason reason;
 182
 183   /**
 184    * Length of the following array.
 185    */
 186   unsigned int fds_len;
 187
 188   /**
 189    * Array of length @e fds_len with information about ready FDs.
 190    * Note that we use the same format regardless of the internal
 191    * event loop that was used.  The given array should only contain
 192    * information about file descriptors relevant to the current task.
 193    */
 194   const struct GNUNET_SCHEDULER_FdInfo *fds;
 195
 196   /**
 197    * Set of file descriptors ready for reading; note that additional
 198    * bits may be set that were not in the original request.
 199    * @deprecated
 200    */
 201   const struct GNUNET_NETWORK_FDSet *read_ready;
 202
 203   /**
 204    * Set of file descriptors ready for writing; note that additional
 205    * bits may be set that were not in the original request.
 206    * @deprecated
 207    */
 208   const struct GNUNET_NETWORK_FDSet *write_ready;
 209 };
 210
 211
 212 /**
 213  * Function used by event-loop implementations to signal the scheduler
 214  * that a particular @a task is ready due to an event specified in the
 215  * et field of @a fdi.
 216  *
 217  * This function will then queue the task to notify the application
 218  * that the task is ready (with the respective priority).
 219  *
 220  * @param task the task that is ready
 221  * @param fdi information about the related FD
 222  */
 223 void
 224 GNUNET_SCHEDULER_task_ready (struct GNUNET_SCHEDULER_Task *task,
 225                              struct GNUNET_SCHEDULER_FdInfo *fdi);
 226
 227
 228 /**
 229  * Handle to the scheduler's state to be used by the driver.
 230  */
 231 struct GNUNET_SCHEDULER_Handle;
 232
 233
 234 /**
 235  * Function called by external event loop implementations to tell the
 236  * scheduler to run some of the tasks that are ready. Must be called
 237  * only after #GNUNET_SCHEDULER_driver_init has been called and before
 238  * #GNUNET_SCHEDULER_driver_done is called.
 239  * This function may return even though there are tasks left to run
 240  * just to give other tasks a chance as well.  If we return #GNUNET_YES,
 241  * the event loop implementation should call this function again as
 242  * soon as possible, while if we return #GNUNET_NO it must block until
 243  * either the operating system has more work (the scheduler has no more
 244  * work to do right now) or the timeout set by the scheduler (using the
 245  * set_wakeup callback) is reached.
 246  *
 247  * @param sh scheduler handle that was returned by
 248  *        #GNUNET_SCHEDULER_driver_init
 249  * @return #GNUNET_YES if there are more tasks that are ready,
 250  *         and thus we would like to run more (yield to avoid
 251  *         blocking other activities for too long) #GNUNET_NO
 252  *         if we are done running tasks (yield to block)
 253  */
 254 int
 255 GNUNET_SCHEDULER_do_work (struct GNUNET_SCHEDULER_Handle *sh);
 256
 257
 258 /**
 259  * API an external event loop has to implement for
 260  * #GNUNET_SCHEDULER_driver_init.
 261  */
 262 struct GNUNET_SCHEDULER_Driver
 263 {
 264   /**
 265    * Closure to pass to the functions in this struct.
 266    */
 267   void *cls;
 268
 269   /**
 270    * Add a @a task to be run if the conditions specified in the
 271    * et field of the given @a fdi are satisfied. The et field will
 272    * be cleared after this call and the driver is expected to set
 273    * the type of the actual event before passing @a fdi to
 274    * #GNUNET_SCHEDULER_task_ready.
 275    *
 276    * @param cls closure
 277    * @param task task to add
 278    * @param fdi conditions to watch for
 279    * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 280    *   (i.e. @a fdi too high or invalid)
 281    */
 282   int
 283   (*add)(void *cls,
 284          struct GNUNET_SCHEDULER_Task *task,
 285          struct GNUNET_SCHEDULER_FdInfo *fdi);
 286
 287   /**
 288    * Delete a @a task from the set of tasks to be run. A task may
 289    * comprise multiple FdInfo entries previously added with the add
 290    * function. The driver is expected to delete them all.
 291    *
 292    * @param cls closure
 293    * @param task task to delete
 294    * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 295    *   (i.e. @a task does not match prior @e add call)
 296    */
 297   int
 298   (*del)(void *cls,
 299          struct GNUNET_SCHEDULER_Task *task);
 300
 301   /**
 302    * Set time at which we definitively want to get a wakeup call.
 303    *
 304    * @param cls closure
 305    * @param dt time when we want to wake up next
 306    */
 307   void
 308   (*set_wakeup)(void *cls,
 309                 struct GNUNET_TIME_Absolute dt);
 310 };
 311
 312
 313 /**
 314  * Signature of the main function of a task.
 315  *
 316  * @param cls closure
 317  */
 318 typedef void
 319 (*GNUNET_SCHEDULER_TaskCallback) (void *cls);
 320
 321
 322 /**
 323  * Function called by external event loop implementations to initialize
 324  * the scheduler. An external implementation has to provide @a driver
 325  * which contains callbacks for the scheduler (see definition of struct
 326  * #GNUNET_SCHEDULER_Driver). The callbacks are used to instruct the
 327  * external implementation to watch for events. If it detects any of
 328  * those events it is expected to call #GNUNET_SCHEDULER_do_work to let
 329  * the scheduler handle it. If an event is related to a specific task
 330  * (e.g. the scheduler gave instructions to watch a file descriptor),
 331  * the external implementation is expected to mark that task ready
 332  * before by calling #GNUNET_SCHEDULER_task_ready.
 333  *
 334  * This function has to be called before any tasks are scheduled and
 335  * before GNUNET_SCHEDULER_do_work is called for the first time. It
 336  * allocates resources that have to be freed again by calling
 337  * #GNUNET_SCHEDULER_driver_done.
 338  *
 339  * This function installs the same signal handlers as
 340  * #GNUNET_SCHEDULER_run. This means SIGTERM (and other similar signals)
 341  * will induce a call to #GNUNET_SCHEDULER_shutdown during the next
 342  * call to #GNUNET_SCHEDULER_do_work. As a result, SIGTERM causes all
 343  * active tasks to be scheduled with reason
 344  * #GNUNET_SCHEDULER_REASON_SHUTDOWN. (However, tasks added afterwards
 345  * will execute normally!). Note that any particular signal will only
 346  * shut down one scheduler; applications should always only create a
 347  * single scheduler.
 348  *
 349  * @param driver to use for the event loop
 350  * @return handle to be passed to #GNUNET_SCHEDULER_do_work and
 351  *         #GNUNET_SCHEDULER_driver_done
 352  */
 353 struct GNUNET_SCHEDULER_Handle *
 354 GNUNET_SCHEDULER_driver_init (const struct GNUNET_SCHEDULER_Driver *driver);
 355
 356
 357 /**
 358  * Counter-part of #GNUNET_SCHEDULER_driver_init. Has to be called
 359  * by external event loop implementations after the scheduler has
 360  * shut down. This is the case if both of the following conditions
 361  * are met:
 362  *
 363  * - all tasks the scheduler has added through the driver's add
 364  *   callback have been removed again through the driver's del
 365  *   callback
 366  * - the timeout the scheduler has set through the driver's
 367  *   add_wakeup callback is FOREVER
 368  *
 369  * @param sh the handle returned by #GNUNET_SCHEDULER_driver_init
 370  */
 371 void
 372 GNUNET_SCHEDULER_driver_done (struct GNUNET_SCHEDULER_Handle *sh);
 373
 374
 375 /**
 376  * Obtain the driver for using select() as the event loop.
 377  *
 378  * @return NULL on error
 379  */
 380 struct GNUNET_SCHEDULER_Driver *
 381 GNUNET_SCHEDULER_driver_select (void);
 382
 383
 384 /**
 385  * Signature of the select function used by the scheduler.
 386  * #GNUNET_NETWORK_socket_select matches it.
 387  *
 388  * @param cls closure
 389  * @param rfds set of sockets to be checked for readability
 390  * @param wfds set of sockets to be checked for writability
 391  * @param efds set of sockets to be checked for exceptions
 392  * @param timeout relative value when to return
 393  * @return number of selected sockets, #GNUNET_SYSERR on error
 394  */
 395 typedef int
 396 (*GNUNET_SCHEDULER_select) (void *cls,
 397                             struct GNUNET_NETWORK_FDSet *rfds,
 398                             struct GNUNET_NETWORK_FDSet *wfds,
 399                             struct GNUNET_NETWORK_FDSet *efds,
 400                             struct GNUNET_TIME_Relative timeout);
 401
 402
 403 /**
 404  * Initialize and run scheduler.  This function will return when all
 405  * tasks have completed.  On systems with signals, receiving a SIGTERM
 406  * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
 407  * to be run after the active task is complete.  As a result, SIGTERM
 408  * causes all shutdown tasks to be scheduled with reason
 409  * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
 410  * afterwards will execute normally!).  Note that any particular
 411  * signal will only shut down one scheduler; applications should
 412  * always only create a single scheduler.
 413  *
 414  * @param task task to run first (and immediately)
 415  * @param task_cls closure of @a task
 416  */
 417 void
 418 GNUNET_SCHEDULER_run (GNUNET_SCHEDULER_TaskCallback task,
 419                       void *task_cls);
 420
 421 /**
 422  * Initialize and run scheduler.  This function will return when all
 423  * tasks have completed.  When @ install_signals is GNUNET_YES, then
 424  * this function behaves in the same was as GNUNET_SCHEDULER_run does.
 425  * If @ install_signals is GNUNET_NO then no signal handlers are
 426  * installed.
 427  *
 428  * @param install_signals whether to install signals (GNUNET_YES/NO)
 429  * @param task task to run first (and immediately)
 430  * @param task_cls closure of @a task
 431  */
 432 void
 433 GNUNET_SCHEDULER_run_with_optional_signals (int install_signals,
 434                                             GNUNET_SCHEDULER_TaskCallback task,
 435                                             void *task_cls);
 436
 437
 438 /**
 439  * Request the shutdown of a scheduler.  Marks all tasks
 440  * awaiting shutdown as ready. Note that tasks
 441  * scheduled with #GNUNET_SCHEDULER_add_shutdown() AFTER this call
 442  * will be delayed until the next shutdown signal.
 443  */
 444 void
 445 GNUNET_SCHEDULER_shutdown (void);
 446
 447
 448 /**
 449  * Get information about the current load of this scheduler.  Use this
 450  * function to determine if an elective task should be added or simply
 451  * dropped (if the decision should be made based on the number of
 452  * tasks ready to run).
 453  *
 454  * @param p priority-level to query, use KEEP to query the level
 455  *          of the current task, use COUNT to get the sum over
 456  *          all priority levels
 457  * @return number of tasks pending right now
 458  */
 459 unsigned int
 460 GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p);
 461
 462
 463 /**
 464  * Obtain the reasoning why the current task was
 465  * started.
 466  *
 467  * @return task context with information why the current task is run
 468  */
 469 const struct GNUNET_SCHEDULER_TaskContext *
 470 GNUNET_SCHEDULER_get_task_context (void);
 471
 472
 473 /**
 474  * Cancel the task with the specified identifier.
 475  * The task must not yet have run. Only allowed to be called as long as the
 476  * scheduler is running, that is one of the following conditions is met:
 477  *
 478  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 479  * - #GNUNET_SCHEDULER_driver_init has been run and
 480  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 481  *
 482  * @param task id of the task to cancel
 483  * @return original closure of the task
 484  */
 485 void *
 486 GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task);
 487
 488
 489 /**
 490  * Continue the current execution with the given function.  This is
 491  * similar to the other "add" functions except that there is no delay
 492  * and the reason code can be specified.
 493  *
 494  * @param task main function of the task
 495  * @param task_cls closure for @a task
 496  * @param reason reason for task invocation
 497  * @param priority priority to use for the task
 498  */
 499 void
 500 GNUNET_SCHEDULER_add_with_reason_and_priority (GNUNET_SCHEDULER_TaskCallback
 501                                                task,
 502                                                void *task_cls,
 503                                                enum GNUNET_SCHEDULER_Reason
 504                                                reason,
 505                                                enum GNUNET_SCHEDULER_Priority
 506                                                priority);
 507
 508
 509 /**
 510  * Schedule a new task to be run with a specified priority.
 511  *
 512  * @param prio how important is the new task?
 513  * @param task main function of the task
 514  * @param task_cls closure of @a task
 515  * @return unique task identifier for the job
 516  *         only valid until @a task is started!
 517  */
 518 struct GNUNET_SCHEDULER_Task *
 519 GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio,
 520                                     GNUNET_SCHEDULER_TaskCallback task,
 521                                     void *task_cls);
 522
 523
 524 /**
 525  * Schedule a new task to be run as soon as possible. Note that this
 526  * does not guarantee that this will be the next task that is being
 527  * run, as other tasks with higher priority (or that are already ready
 528  * to run) might get to run first.  Just as with delays, clients must
 529  * not rely on any particular order of execution between tasks
 530  * scheduled concurrently.
 531  *
 532  * The task will be run with the DEFAULT priority.
 533  *
 534  * @param task main function of the task
 535  * @param task_cls closure of @a task
 536  * @return unique task identifier for the job
 537  *         only valid until @a task is started!
 538  */
 539 struct GNUNET_SCHEDULER_Task *
 540 GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_TaskCallback task,
 541                           void *task_cls);
 542
 543
 544 /**
 545  * Schedule a new task to be run on shutdown, that is when a CTRL-C
 546  * signal is received, or when #GNUNET_SCHEDULER_shutdown() is being
 547  * invoked.
 548  *
 549  * @param task main function of the task
 550  * @param task_cls closure of @a task
 551  * @return unique task identifier for the job
 552  *         only valid until @a task is started!
 553  */
 554 struct GNUNET_SCHEDULER_Task *
 555 GNUNET_SCHEDULER_add_shutdown (GNUNET_SCHEDULER_TaskCallback task,
 556                                void *task_cls);
 557
 558
 559 /**
 560  * Schedule a new task to be run as soon as possible with the
 561  * (transitive) ignore-shutdown flag either explicitly set or
 562  * explicitly enabled.  This task (and all tasks created from it,
 563  * other than by another call to this function) will either count or
 564  * not count for the 'lifeness' of the process.  This API is only
 565  * useful in a few special cases.
 566  *
 567  * @param lifeness #GNUNET_YES if the task counts for lifeness, #GNUNET_NO if not.
 568  * @param task main function of the task
 569  * @param task_cls closure of @a task
 570  * @return unique task identifier for the job
 571  *         only valid until @a task is started!
 572  */
 573 struct GNUNET_SCHEDULER_Task *
 574 GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness,
 575                                         GNUNET_SCHEDULER_TaskCallback task,
 576                                         void *task_cls);
 577
 578
 579 /**
 580  * Schedule a new task to be run with a specified delay.  The task
 581  * will be scheduled for execution once the delay has expired. It
 582  * will be run with the DEFAULT priority.
 583  *
 584  * @param delay with which the operation should be run
 585  * @param task main function of the task
 586  * @param task_cls closure of @a task
 587  * @return unique task identifier for the job
 588  *         only valid until @a task is started!
 589  */
 590 struct GNUNET_SCHEDULER_Task *
 591 GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay,
 592                               GNUNET_SCHEDULER_TaskCallback task,
 593                               void *task_cls);
 594
 595
 596 /**
 597  * Schedule a new task to be run at the specified time.  The task
 598  * will be scheduled for execution once specified time has been
 599  * reached. It will be run with the DEFAULT priority.
 600  *
 601  * @param at time at which this operation should run
 602  * @param task main function of the task
 603  * @param task_cls closure of @a task
 604  * @return unique task identifier for the job
 605  *         only valid until @a task is started!
 606  */
 607 struct GNUNET_SCHEDULER_Task *
 608 GNUNET_SCHEDULER_add_at (struct GNUNET_TIME_Absolute at,
 609                          GNUNET_SCHEDULER_TaskCallback task,
 610                          void *task_cls);
 611
 612
 613 /**
 614  * Schedule a new task to be run with a specified delay.  The task
 615  * will be scheduled for execution once the delay has expired.
 616  *
 617  * @param delay when should this operation time out?
 618  * @param priority priority to use for the task
 619  * @param task main function of the task
 620  * @param task_cls closure of @a task
 621  * @return unique task identifier for the job
 622  *         only valid until @a task is started!
 623  */
 624 struct GNUNET_SCHEDULER_Task *
 625 GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay,
 626                                             enum GNUNET_SCHEDULER_Priority
 627                                             priority,
 628                                             GNUNET_SCHEDULER_TaskCallback task,
 629                                             void *task_cls);
 630
 631
 632 /**
 633  * Schedule a new task to be run at the specified time.  The task
 634  * will be scheduled for execution at time @a at.
 635  *
 636  * @param at time when the operation should run
 637  * @param priority priority to use for the task
 638  * @param task main function of the task
 639  * @param task_cls closure of @a task
 640  * @return unique task identifier for the job
 641  *         only valid until @a task is started!
 642  */
 643 struct GNUNET_SCHEDULER_Task *
 644 GNUNET_SCHEDULER_add_at_with_priority (struct GNUNET_TIME_Absolute at,
 645                                        enum GNUNET_SCHEDULER_Priority priority,
 646                                        GNUNET_SCHEDULER_TaskCallback task,
 647                                        void *task_cls);
 648
 649
 650 /**
 651  * Schedule a new task to be run with a specified delay or when the
 652  * specified file descriptor is ready for reading.  The delay can be
 653  * used as a timeout on the socket being ready.  The task will be
 654  * scheduled for execution once either the delay has expired or the
 655  * socket operation is ready.  It will be run with the DEFAULT priority.
 656  * Only allowed to be called as long as the scheduler is running, that
 657  * is one of the following conditions is met:
 658  *
 659  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 660  * - #GNUNET_SCHEDULER_driver_init has been run and
 661  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 662  *
 663  * @param delay when should this operation time out?
 664  * @param rfd read file-descriptor
 665  * @param task main function of the task
 666  * @param task_cls closure of @a task
 667  * @return unique task identifier for the job
 668  *         only valid until @a task is started!
 669  */
 670 struct GNUNET_SCHEDULER_Task *
 671 GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay,
 672                                struct GNUNET_NETWORK_Handle *rfd,
 673                                GNUNET_SCHEDULER_TaskCallback task,
 674                                void *task_cls);
 675
 676
 677 /**
 678  * Schedule a new task to be run with a specified priority and to be
 679  * run after the specified delay or when the specified file descriptor
 680  * is ready for reading.  The delay can be used as a timeout on the
 681  * socket being ready.  The task will be scheduled for execution once
 682  * either the delay has expired or the socket operation is ready.  It
 683  * will be run with the DEFAULT priority.
 684  * Only allowed to be called as long as the scheduler is running, that
 685  * is one of the following conditions is met:
 686  *
 687  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 688  * - #GNUNET_SCHEDULER_driver_init has been run and
 689  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 690  *
 691  * @param delay when should this operation time out?
 692  * @param priority priority to use for the task
 693  * @param rfd read file-descriptor
 694  * @param task main function of the task
 695  * @param task_cls closure of @a task
 696  * @return unique task identifier for the job
 697  *         only valid until @a task is started!
 698  */
 699 struct GNUNET_SCHEDULER_Task *
 700 GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay,
 701                                              enum GNUNET_SCHEDULER_Priority
 702                                              priority,
 703                                              struct GNUNET_NETWORK_Handle *rfd,
 704                                              GNUNET_SCHEDULER_TaskCallback task,
 705                                              void *task_cls);
 706
 707
 708 /**
 709  * Schedule a new task to be run with a specified delay or when the
 710  * specified file descriptor is ready for writing.  The delay can be
 711  * used as a timeout on the socket being ready.  The task will be
 712  * scheduled for execution once either the delay has expired or the
 713  * socket operation is ready.  It will be run with the priority of
 714  * the calling task.
 715  * Only allowed to be called as long as the scheduler is running, that
 716  * is one of the following conditions is met:
 717  *
 718  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 719  * - #GNUNET_SCHEDULER_driver_init has been run and
 720  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 721  *
 722  * @param delay when should this operation time out?
 723  * @param wfd write file-descriptor
 724  * @param task main function of the task
 725  * @param task_cls closure of @a task
 726  * @return unique task identifier for the job
 727  *         only valid until @a task is started!
 728  */
 729 struct GNUNET_SCHEDULER_Task *
 730 GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay,
 731                                 struct GNUNET_NETWORK_Handle *wfd,
 732                                 GNUNET_SCHEDULER_TaskCallback task,
 733                                 void *task_cls);
 734
 735
 736 /**
 737  * Schedule a new task to be run with a specified delay or when the
 738  * specified file descriptor is ready.  The delay can be
 739  * used as a timeout on the socket being ready.  The task will be
 740  * scheduled for execution once either the delay has expired or the
 741  * socket operation is ready.
 742  * Only allowed to be called as long as the scheduler is running, that
 743  * is one of the following conditions is met:
 744  *
 745  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 746  * - #GNUNET_SCHEDULER_driver_init has been run and
 747  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 748  *
 749  * @param delay when should this operation time out?
 750  * @param priority priority of the task
 751  * @param fd file-descriptor
 752  * @param on_read whether to poll the file-descriptor for readability
 753  * @param on_write whether to poll the file-descriptor for writability
 754  * @param task main function of the task
 755  * @param task_cls closure of task
 756  * @return unique task identifier for the job
 757  *         only valid until "task" is started!
 758  */
 759 struct GNUNET_SCHEDULER_Task *
 760 GNUNET_SCHEDULER_add_net_with_priority (struct GNUNET_TIME_Relative delay,
 761                                         enum GNUNET_SCHEDULER_Priority priority,
 762                                         struct GNUNET_NETWORK_Handle *fd,
 763                                         int on_read,
 764                                         int on_write,
 765                                         GNUNET_SCHEDULER_TaskCallback task,
 766                                         void *task_cls);
 767
 768
 769 /**
 770  * Schedule a new task to be run with a specified delay or when the
 771  * specified file descriptor is ready for reading.  The delay can be
 772  * used as a timeout on the socket being ready.  The task will be
 773  * scheduled for execution once either the delay has expired or the
 774  * socket operation is ready. It will be run with the DEFAULT priority.
 775  * Only allowed to be called as long as the scheduler is running, that
 776  * is one of the following conditions is met:
 777  *
 778  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 779  * - #GNUNET_SCHEDULER_driver_init has been run and
 780  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 781  *
 782  * @param delay when should this operation time out?
 783  * @param rfd read file-descriptor
 784  * @param task main function of the task
 785  * @param task_cls closure of @a task
 786  * @return unique task identifier for the job
 787  *         only valid until @a task is started!
 788  */
 789 struct GNUNET_SCHEDULER_Task *
 790 GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay,
 791                                 const struct GNUNET_DISK_FileHandle *rfd,
 792                                 GNUNET_SCHEDULER_TaskCallback task,
 793                                 void *task_cls);
 794
 795
 796 /**
 797  * Schedule a new task to be run with a specified delay or when the
 798  * specified file descriptor is ready for writing.  The delay can be
 799  * used as a timeout on the socket being ready.  The task will be
 800  * scheduled for execution once either the delay has expired or the
 801  * socket operation is ready. It will be run with the DEFAULT priority.
 802  * Only allowed to be called as long as the scheduler is running, that
 803  * is one of the following conditions is met:
 804  *
 805  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 806  * - #GNUNET_SCHEDULER_driver_init has been run and
 807  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 808  *
 809  * @param delay when should this operation time out?
 810  * @param wfd write file-descriptor
 811  * @param task main function of the task
 812  * @param task_cls closure of @a task
 813  * @return unique task identifier for the job
 814  *         only valid until @a task is started!
 815  */
 816 struct GNUNET_SCHEDULER_Task *
 817 GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay,
 818                                  const struct GNUNET_DISK_FileHandle *wfd,
 819                                  GNUNET_SCHEDULER_TaskCallback task,
 820                                  void *task_cls);
 821
 822
 823 /**
 824  * Schedule a new task to be run with a specified delay or when the
 825  * specified file descriptor is ready.  The delay can be
 826  * used as a timeout on the socket being ready.  The task will be
 827  * scheduled for execution once either the delay has expired or the
 828  * socket operation is ready.
 829  * Only allowed to be called as long as the scheduler is running, that
 830  * is one of the following conditions is met:
 831  *
 832  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 833  * - #GNUNET_SCHEDULER_driver_init has been run and
 834  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 835  *
 836  * @param delay when should this operation time out?
 837  * @param priority priority of the task
 838  * @param fd file-descriptor
 839  * @param on_read whether to poll the file-descriptor for readability
 840  * @param on_write whether to poll the file-descriptor for writability
 841  * @param task main function of the task
 842  * @param task_cls closure of @a task
 843  * @return unique task identifier for the job
 844  *         only valid until @a task is started!
 845  */
 846 struct GNUNET_SCHEDULER_Task *
 847 GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay,
 848                                          enum GNUNET_SCHEDULER_Priority
 849                                          priority,
 850                                          const struct
 851                                          GNUNET_DISK_FileHandle *fd,
 852                                          int on_read,
 853                                          int on_write,
 854                                          GNUNET_SCHEDULER_TaskCallback task,
 855                                          void *task_cls);
 856
 857
 858 /**
 859  * Schedule a new task to be run with a specified delay or when any of
 860  * the specified file descriptor sets is ready.  The delay can be used
 861  * as a timeout on the socket(s) being ready.  The task will be
 862  * scheduled for execution once either the delay has expired or any of
 863  * the socket operations is ready.  This is the most general
 864  * function of the "add" family.  Note that the "prerequisite_task"
 865  * must be satisfied in addition to any of the other conditions.  In
 866  * other words, the task will be started when
 867  * <code>
 868  * (prerequisite-run)
 869  * && (delay-ready
 870  *     || any-rs-ready
 871  *     || any-ws-ready) )
 872  * </code>
 873  * Only allowed to be called as long as the scheduler is running, that
 874  * is one of the following conditions is met:
 875  *
 876  * - #GNUNET_SCHEDULER_run has been called and has not returned yet
 877  * - #GNUNET_SCHEDULER_driver_init has been run and
 878  *   #GNUNET_SCHEDULER_driver_done has not been called yet
 879  *
 880  * @param prio how important is this task?
 881  * @param delay how long should we wait?
 882  * @param rs set of file descriptors we want to read (can be NULL)
 883  * @param ws set of file descriptors we want to write (can be NULL)
 884  * @param task main function of the task
 885  * @param task_cls closure of @a task
 886  * @return unique task identifier for the job
 887  *         only valid until @a task is started!
 888  */
 889 struct GNUNET_SCHEDULER_Task *
 890 GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio,
 891                              struct GNUNET_TIME_Relative delay,
 892                              const struct GNUNET_NETWORK_FDSet *rs,
 893                              const struct GNUNET_NETWORK_FDSet *ws,
 894                              GNUNET_SCHEDULER_TaskCallback task,
 895                              void *task_cls);
 896
 897 /**
 898  * Sets the select function to use in the scheduler (scheduler_select).
 899  *
 900  * @param new_select new select function to use (NULL to reset to default)
 901  * @param new_select_cls closure for @a new_select
 902  */
 903 void
 904 GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select,
 905                              void *new_select_cls);
 906
 907
 908 /**
 909  * Change the async scope for the currently executing task and (transitively)
 910  * for all tasks scheduled by the current task after calling this function.
 911  * Nested tasks can begin their own nested async scope.
 912  *
 913  * Once the current task is finished, the async scope ID is reset to
 914  * its previous value.
 915  *
 916  * Must only be called from a running task.
 917  *
 918  * @param aid the asynchronous scope id to enter
 919  */
 920 void
 921 GNUNET_SCHEDULER_begin_async_scope (struct GNUNET_AsyncScopeId *aid);
 922
 923
 924 #if 0                           /* keep Emacsens' auto-indent happy */
 925 {
 926 #endif
 927 #ifdef __cplusplus
 928 }
 929 #endif
 930
 931 #endif
 932
 933 /** @} */ /* end of group scheduler */