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