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
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       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       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18       Boston, MA 02110-1301, USA.
  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   /**
 107    * No event (useful for timeout).
 108    */
 109   GNUNET_SCHEDULER_ET_NONE = 0,
 110
 111   /**
 112    * Data available for reading.
 113    */
 114   GNUNET_SCHEDULER_ET_IN = 1,
 115
 116   /**
 117    * Buffer available for writing.
 118    */
 119   GNUNET_SCHEDULER_ET_OUT = 2,
 120
 121   /**
 122    *
 123    */
 124   GNUNET_SCHEDULER_ET_HUP = 4,
 125
 126   /**
 127    *
 128    */
 129   GNUNET_SCHEDULER_ET_ERR = 8,
 130
 131   /**
 132    *
 133    */
 134   GNUNET_SCHEDULER_ET_PRI = 16,
 135
 136   /**
 137    *
 138    */
 139   GNUNET_SCHEDULER_ET_NVAL = 32
 140
 141 };
 142
 143
 144 /**
 145  * Information about an event relating to a file descriptor/socket.
 146  */
 147 struct GNUNET_SCHEDULER_FdInfo
 148 {
 149
 150   /**
 151    * GNUnet network socket the event is about, matches @a sock,
 152    * NULL if this is about a file handle or if no network
 153    * handle was given to the scheduler originally.
 154    */
 155   const struct GNUNET_NETWORK_Handle *fd;
 156
 157   /**
 158    * GNUnet file handle the event is about, matches @a sock,
 159    * NULL if this is about a network socket or if no network
 160    * handle was given to the scheduler originally.
 161    */
 162   const struct GNUNET_DISK_FileHandle *fh;
 163
 164   /**
 165    * Type of the event that was generated related to @e sock.
 166    */
 167   enum GNUNET_SCHEDULER_EventType et;
 168
 169   /**
 170    * Underlying OS handle the event was about.
 171    */
 172   int sock;
 173
 174 };
 175
 176
 177 /**
 178  * Context information passed to each scheduler task.
 179  */
 180 struct GNUNET_SCHEDULER_TaskContext
 181 {
 182   /**
 183    * Reason why the task is run now
 184    */
 185   enum GNUNET_SCHEDULER_Reason reason;
 186
 187   /**
 188    * Length of the following array.
 189    */
 190   unsigned int fds_len;
 191
 192   /**
 193    * Array of length @e fds_len with information about ready FDs.
 194    * Note that we use the same format regardless of the internal
 195    * event loop that was used.  The given array should only contain
 196    * information about file descriptors relevant to the current task.
 197    */
 198   const struct GNUNET_SCHEDULER_FdInfo *fds;
 199
 200   /**
 201    * Set of file descriptors ready for reading; note that additional
 202    * bits may be set that were not in the original request.
 203    * @deprecated
 204    */
 205   const struct GNUNET_NETWORK_FDSet *read_ready;
 206
 207   /**
 208    * Set of file descriptors ready for writing; note that additional
 209    * bits may be set that were not in the original request.
 210    * @deprecated
 211    */
 212   const struct GNUNET_NETWORK_FDSet *write_ready;
 213
 214 };
 215
 216
 217 /**
 218  * Function used by event-loop implementations to signal the scheduler
 219  * that a particular @a task is ready due to an event specified in the
 220  * et field of @a fdi.
 221  *
 222  * This function will then queue the task to notify the application
 223  * that the task is ready (with the respective priority).
 224  *
 225  * @param task the task that is ready
 226  * @param fdi information about the related FD
 227  */
 228 void
 229 GNUNET_SCHEDULER_task_ready (struct GNUNET_SCHEDULER_Task *task,
 230                              struct GNUNET_SCHEDULER_FdInfo *fdi);
 231
 232
 233 /**
 234  * Handle to the scheduler's state to be used by the driver.
 235  */
 236 struct GNUNET_SCHEDULER_Handle;
 237
 238
 239 /**
 240  * Function called by the driver to tell the scheduler to run some of
 241  * the tasks that are ready.  This function may return even though
 242  * there are tasks left to run just to give other tasks a chance as
 243  * well.  If we return #GNUNET_YES, the driver should call this
 244  * function again as soon as possible, while if we return #GNUNET_NO
 245  * it must block until either the operating system has more work (the
 246  * scheduler has no more work to do right now) or the timeout set by
 247  * the scheduler (using the set_wakeup callback) is reached.
 248  *
 249  * @param sh scheduler handle that was given to the `loop`
 250  * @return #GNUNET_OK if there are more tasks that are ready,
 251  *          and thus we would like to run more (yield to avoid
 252  *          blocking other activities for too long)
 253  *         #GNUNET_NO if we are done running tasks (yield to block)
 254  *         #GNUNET_SYSERR on error, e.g. no tasks were ready
 255  */
 256 int
 257 GNUNET_SCHEDULER_run_from_driver (struct GNUNET_SCHEDULER_Handle *sh);
 258
 259
 260 /**
 261  * API a driver has to implement for
 262  * #GNUNET_SCHEDULER_run_with_driver().
 263  */
 264 struct GNUNET_SCHEDULER_Driver
 265 {
 266
 267   /**
 268    * Closure to pass to the functions in this struct.
 269    */
 270   void *cls;
 271
 272   /**
 273    * Add a @a task to be run if the conditions specified in the
 274    * et field of the given @a fdi are satisfied. The et field will
 275    * be cleared after this call and the driver is expected to set
 276    * the type of the actual event before passing @a fdi to
 277    * #GNUNET_SCHEDULER_task_ready.
 278    *
 279    * @param cls closure
 280    * @param task task to add
 281    * @param fdi conditions to watch for
 282    * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 283    *   (i.e. @a fdi too high or invalid)
 284    */
 285   int
 286   (*add)(void *cls,
 287          struct GNUNET_SCHEDULER_Task *task,
 288          struct GNUNET_SCHEDULER_FdInfo *fdi);
 289
 290   /**
 291    * Delete a @a task from the set of tasks to be run. A task may
 292    * comprise multiple FdInfo entries previously added with the add
 293    * function. The driver is expected to delete them all.
 294    *
 295    * @param cls closure
 296    * @param task task to delete
 297    * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 298    *   (i.e. @a task does not match prior @e add call)
 299    */
 300   int
 301   (*del)(void *cls,
 302          struct GNUNET_SCHEDULER_Task *task);
 303
 304   /**
 305    * Set time at which we definitively want to get a wakeup call.
 306    *
 307    * @param cls closure
 308    * @param dt time when we want to wake up next
 309    */
 310   void
 311   (*set_wakeup)(void *cls,
 312                 struct GNUNET_TIME_Absolute dt);
 313
 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 };
 332
 333
 334 /**
 335  * Signature of the main function of a task.
 336  *
 337  * @param cls closure
 338  */
 339 typedef void
 340 (*GNUNET_SCHEDULER_TaskCallback) (void *cls);
 341
 342
 343 /**
 344  * Initialize and run scheduler.  This function will return when all
 345  * tasks have completed.  On systems with signals, receiving a SIGTERM
 346  * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
 347  * to be run after the active task is complete.  As a result, SIGTERM
 348  * causes all shutdown tasks to be scheduled with reason
 349  * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
 350  * afterwards will execute normally!).  Note that any particular
 351  * signal will only shut down one scheduler; applications should
 352  * always only create a single scheduler.
 353  *
 354  * @param driver drive to use for the event loop
 355  * @param task task to run first (and immediately)
 356  * @param task_cls closure of @a task
 357  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 358  */
 359 int
 360 GNUNET_SCHEDULER_run_with_driver (const struct GNUNET_SCHEDULER_Driver *driver,
 361                                   GNUNET_SCHEDULER_TaskCallback task,
 362                                   void *task_cls);
 363
 364
 365 /**
 366  * Obtain the driver for using select() as the event loop.
 367  *
 368  * @return NULL on error
 369  */
 370 struct GNUNET_SCHEDULER_Driver *
 371 GNUNET_SCHEDULER_driver_select (void);
 372
 373
 374 /**
 375  * Signature of the select function used by the scheduler.
 376  * #GNUNET_NETWORK_socket_select matches it.
 377  *
 378  * @param cls closure
 379  * @param rfds set of sockets to be checked for readability
 380  * @param wfds set of sockets to be checked for writability
 381  * @param efds set of sockets to be checked for exceptions
 382  * @param timeout relative value when to return
 383  * @return number of selected sockets, #GNUNET_SYSERR on error
 384  */
 385 typedef int
 386 (*GNUNET_SCHEDULER_select) (void *cls,
 387                             struct GNUNET_NETWORK_FDSet *rfds,
 388                             struct GNUNET_NETWORK_FDSet *wfds,
 389                             struct GNUNET_NETWORK_FDSet *efds,
 390                             struct GNUNET_TIME_Relative timeout);
 391
 392
 393 /**
 394  * Initialize and run scheduler.  This function will return when all
 395  * tasks have completed.  On systems with signals, receiving a SIGTERM
 396  * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
 397  * to be run after the active task is complete.  As a result, SIGTERM
 398  * causes all shutdown tasks to be scheduled with reason
 399  * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
 400  * afterwards will execute normally!).  Note that any particular
 401  * signal will only shut down one scheduler; applications should
 402  * always only create a single scheduler.
 403  *
 404  * @param task task to run first (and immediately)
 405  * @param task_cls closure of @a task
 406  */
 407 void
 408 GNUNET_SCHEDULER_run (GNUNET_SCHEDULER_TaskCallback task,
 409                       void *task_cls);
 410
 411 /**
 412  * Initialize and run scheduler.  This function will return when all
 413  * tasks have completed.  When @ install_signals is GNUNET_YES, then
 414  * this function behaves in the same was as GNUNET_SCHEDULER_run does.
 415  * If @ install_signals is GNUNET_NO then no signal handlers are
 416  * installed.
 417  *
 418  * @param install_signals whether to install signals (GNUNET_YES/NO)
 419  * @param task task to run first (and immediately)
 420  * @param task_cls closure of @a task
 421  */
 422 void
 423 GNUNET_SCHEDULER_run_with_optional_signals (int install_signals,
 424                                             GNUNET_SCHEDULER_TaskCallback task,
 425                                             void *task_cls);
 426
 427
 428 /**
 429  * Request the shutdown of a scheduler.  Marks all tasks
 430  * awaiting shutdown as ready. Note that tasks
 431  * scheduled with #GNUNET_SCHEDULER_add_shutdown() AFTER this call
 432  * will be delayed until the next shutdown signal.
 433  */
 434 void
 435 GNUNET_SCHEDULER_shutdown (void);
 436
 437
 438 /**
 439  * Get information about the current load of this scheduler.  Use this
 440  * function to determine if an elective task should be added or simply
 441  * dropped (if the decision should be made based on the number of
 442  * tasks ready to run).
 443  *
 444  * @param p priority-level to query, use KEEP to query the level
 445  *          of the current task, use COUNT to get the sum over
 446  *          all priority levels
 447  * @return number of tasks pending right now
 448  */
 449 unsigned int
 450 GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p);
 451
 452
 453 /**
 454  * Obtain the reasoning why the current task was
 455  * started.
 456  *
 457  * @return task context with information why the current task is run
 458  */
 459 const struct GNUNET_SCHEDULER_TaskContext *
 460 GNUNET_SCHEDULER_get_task_context (void);
 461
 462
 463 /**
 464  * Cancel the task with the specified identifier.
 465  * The task must not yet have run.
 466  *
 467  * @param task id of the task to cancel
 468  * @return the closure of the callback of the cancelled task
 469  */
 470 void *
 471 GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task);
 472
 473
 474 /**
 475  * Continue the current execution with the given function.  This is
 476  * similar to the other "add" functions except that there is no delay
 477  * and the reason code can be specified.
 478  *
 479  * @param task main function of the task
 480  * @param task_cls closure for @a task
 481  * @param reason reason for task invocation
 482  * @param priority priority to use for the task
 483  */
 484 void
 485 GNUNET_SCHEDULER_add_with_reason_and_priority (GNUNET_SCHEDULER_TaskCallback task,
 486                                                void *task_cls,
 487                                                enum GNUNET_SCHEDULER_Reason reason,
 488                                                enum GNUNET_SCHEDULER_Priority priority);
 489
 490
 491 /**
 492  * Schedule a new task to be run with a specified priority.
 493  *
 494  * @param prio how important is the new task?
 495  * @param task main function of the task
 496  * @param task_cls closure of @a task
 497  * @return unique task identifier for the job
 498  *         only valid until @a task is started!
 499  */
 500 struct GNUNET_SCHEDULER_Task *
 501 GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio,
 502                                     GNUNET_SCHEDULER_TaskCallback task,
 503                                     void *task_cls);
 504
 505
 506 /**
 507  * Schedule a new task to be run as soon as possible. Note that this
 508  * does not guarantee that this will be the next task that is being
 509  * run, as other tasks with higher priority (or that are already ready
 510  * to run) might get to run first.  Just as with delays, clients must
 511  * not rely on any particular order of execution between tasks
 512  * scheduled concurrently.
 513  *
 514  * The task will be run with the DEFAULT priority.
 515  *
 516  * @param task main function of the task
 517  * @param task_cls closure of @a task
 518  * @return unique task identifier for the job
 519  *         only valid until @a task is started!
 520  */
 521 struct GNUNET_SCHEDULER_Task *
 522 GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_TaskCallback task,
 523                           void *task_cls);
 524
 525
 526 /**
 527  * Schedule a new task to be run on shutdown, that is when a CTRL-C
 528  * signal is received, or when #GNUNET_SCHEDULER_shutdown() is being
 529  * invoked.
 530  *
 531  * @param task main function of the task
 532  * @param task_cls closure of @a task
 533  * @return unique task identifier for the job
 534  *         only valid until @a task is started!
 535  */
 536 struct GNUNET_SCHEDULER_Task *
 537 GNUNET_SCHEDULER_add_shutdown (GNUNET_SCHEDULER_TaskCallback task,
 538                                void *task_cls);
 539
 540
 541 /**
 542  * Schedule a new task to be run as soon as possible with the
 543  * (transitive) ignore-shutdown flag either explicitly set or
 544  * explicitly enabled.  This task (and all tasks created from it,
 545  * other than by another call to this function) will either count or
 546  * not count for the 'lifeness' of the process.  This API is only
 547  * useful in a few special cases.
 548  *
 549  * @param lifeness #GNUNET_YES if the task counts for lifeness, #GNUNET_NO if not.
 550  * @param task main function of the task
 551  * @param task_cls closure of @a task
 552  * @return unique task identifier for the job
 553  *         only valid until @a task is started!
 554  */
 555 struct GNUNET_SCHEDULER_Task *
 556 GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness,
 557                                         GNUNET_SCHEDULER_TaskCallback task,
 558                                         void *task_cls);
 559
 560
 561 /**
 562  * Schedule a new task to be run with a specified delay.  The task
 563  * will be scheduled for execution once the delay has expired. It
 564  * will be run with the DEFAULT priority.
 565  *
 566  * @param delay with which the operation should be run
 567  * @param task main function of the task
 568  * @param task_cls closure of @a task
 569  * @return unique task identifier for the job
 570  *         only valid until @a task is started!
 571  */
 572 struct GNUNET_SCHEDULER_Task *
 573 GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay,
 574                               GNUNET_SCHEDULER_TaskCallback task,
 575                               void *task_cls);
 576
 577
 578 /**
 579  * Schedule a new task to be run at the specified time.  The task
 580  * will be scheduled for execution once specified time has been
 581  * reached. It will be run with the DEFAULT priority.
 582  *
 583  * @param at time at which this operation should run
 584  * @param task main function of the task
 585  * @param task_cls closure of @a task
 586  * @return unique task identifier for the job
 587  *         only valid until @a task is started!
 588  */
 589 struct GNUNET_SCHEDULER_Task *
 590 GNUNET_SCHEDULER_add_at (struct GNUNET_TIME_Absolute at,
 591                          GNUNET_SCHEDULER_TaskCallback task,
 592                          void *task_cls);
 593
 594
 595 /**
 596  * Schedule a new task to be run with a specified delay.  The task
 597  * will be scheduled for execution once the delay has expired.
 598  *
 599  * @param delay when should this operation time out?
 600  * @param priority priority to use for the task
 601  * @param task main function of the task
 602  * @param task_cls closure of @a task
 603  * @return unique task identifier for the job
 604  *         only valid until @a task is started!
 605  */
 606 struct GNUNET_SCHEDULER_Task *
 607 GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay,
 608                                             enum GNUNET_SCHEDULER_Priority priority,
 609                                             GNUNET_SCHEDULER_TaskCallback task,
 610                                             void *task_cls);
 611
 612
 613 /**
 614  * Schedule a new task to be run at the specified time.  The task
 615  * will be scheduled for execution at time @a at.
 616  *
 617  * @param at time when the operation should run
 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_at_with_priority (struct GNUNET_TIME_Absolute at,
 626                                        enum GNUNET_SCHEDULER_Priority priority,
 627                                        GNUNET_SCHEDULER_TaskCallback task,
 628                                        void *task_cls);
 629
 630
 631 /**
 632  * Schedule a new task to be run with a specified delay or when the
 633  * specified file descriptor is ready for reading.  The delay can be
 634  * 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
 636  * socket operation is ready.  It will be run with the DEFAULT priority.
 637  *
 638  * @param delay when should this operation time out?
 639  * @param rfd read file-descriptor
 640  * @param task main function of the task
 641  * @param task_cls closure of @a task
 642  * @return unique task identifier for the job
 643  *         only valid until @a task is started!
 644  */
 645 struct GNUNET_SCHEDULER_Task *
 646 GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay,
 647                                struct GNUNET_NETWORK_Handle *rfd,
 648                                GNUNET_SCHEDULER_TaskCallback task,
 649                                void *task_cls);
 650
 651
 652 /**
 653  * Schedule a new task to be run with a specified priority and to be
 654  * run after the specified delay or when the specified file descriptor
 655  * is ready for reading.  The delay can be used as a timeout on the
 656  * socket being ready.  The task will be scheduled for execution once
 657  * either the delay has expired or the socket operation is ready.  It
 658  * will be run with the DEFAULT priority.
 659  *
 660  * @param delay when should this operation time out?
 661  * @param priority priority to use for the task
 662  * @param rfd read file-descriptor
 663  * @param task main function of the task
 664  * @param task_cls closure of @a task
 665  * @return unique task identifier for the job
 666  *         only valid until @a task is started!
 667  */
 668 struct GNUNET_SCHEDULER_Task *
 669 GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay,
 670                                              enum GNUNET_SCHEDULER_Priority priority,
 671                                              struct GNUNET_NETWORK_Handle *rfd,
 672                                              GNUNET_SCHEDULER_TaskCallback task,
 673                                              void *task_cls);
 674
 675
 676 /**
 677  * Schedule a new task to be run with a specified delay or when the
 678  * 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
 680  * scheduled for execution once either the delay has expired or the
 681  * socket operation is ready.  It will be run with the DEFAULT priority.
 682  *
 683  * * @param delay when should this operation time out?
 684  * @param wfd write file-descriptor
 685  * @param task main function of the task
 686  * @param task_cls closure of @a task
 687  * @return unique task identifier for the job
 688  *         only valid until @a task is started!
 689  */
 690 struct GNUNET_SCHEDULER_Task *
 691 GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay,
 692                                 struct GNUNET_NETWORK_Handle *wfd,
 693                                 GNUNET_SCHEDULER_TaskCallback task,
 694                                 void *task_cls);
 695
 696
 697 /**
 698  * Schedule a new task to be run with a specified delay or when the
 699  * specified file descriptor is ready.  The delay can be
 700  * 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
 702  * socket operation is ready.
 703  *
 704  * @param delay when should this operation time out?
 705  * @param priority priority of the task
 706  * @param fd file-descriptor
 707  * @param on_read whether to poll the file-descriptor for readability
 708  * @param on_write whether to poll the file-descriptor for writability
 709  * @param task main function of the task
 710  * @param task_cls closure of @a task
 711  * @return unique task identifier for the job
 712  *         only valid until "task" is started!
 713  */
 714 struct GNUNET_SCHEDULER_Task *
 715 GNUNET_SCHEDULER_add_net_with_priority  (struct GNUNET_TIME_Relative delay,
 716                                          enum GNUNET_SCHEDULER_Priority priority,
 717                                          struct GNUNET_NETWORK_Handle *fd,
 718                                          int on_read,
 719                                          int on_write,
 720                                          GNUNET_SCHEDULER_TaskCallback task,
 721                                          void *task_cls);
 722
 723 /**
 724  * 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
 726  * 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
 728  * socket operation is ready. It will be run with the DEFAULT priority.
 729  *
 730  * * @param delay when should this operation time out?
 731  * @param rfd read file-descriptor
 732  * @param task main function of the task
 733  * @param task_cls closure of @a task
 734  * @return unique task identifier for the job
 735  *         only valid until "task" is started!
 736  */
 737 struct GNUNET_SCHEDULER_Task *
 738 GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay,
 739                                 const struct GNUNET_DISK_FileHandle *rfd,
 740                                 GNUNET_SCHEDULER_TaskCallback task,
 741                                 void *task_cls);
 742
 743
 744 /**
 745  * Schedule a new task to be run with a specified delay or when the
 746  * specified file descriptor is ready for writing.  The delay can be
 747  * 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
 749  * socket operation is ready. It will be run with the DEFAULT priority.
 750  *
 751  * * @param delay when should this operation time out?
 752  * @param wfd write file-descriptor
 753  * @param task main function of the task
 754  * @param task_cls closure of @a task
 755  * @return unique task identifier for the job
 756  *         only valid until @a task is started!
 757  */
 758 struct GNUNET_SCHEDULER_Task *
 759 GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay,
 760                                  const struct GNUNET_DISK_FileHandle *wfd,
 761                                  GNUNET_SCHEDULER_TaskCallback task,
 762                                  void *task_cls);
 763
 764
 765 /**
 766  * Schedule a new task to be run with a specified delay or when the
 767  * specified file descriptor is ready.  The delay can be
 768  * 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
 770  * socket operation is ready.
 771  *
 772  * @param delay when should this operation time out?
 773  * @param priority priority of the task
 774  * @param fd file-descriptor
 775  * @param on_read whether to poll the file-descriptor for readability
 776  * @param on_write whether to poll the file-descriptor for writability
 777  * @param task main function of the task
 778  * @param task_cls closure of @a task
 779  * @return unique task identifier for the job
 780  *         only valid until @a task is started!
 781  */
 782 struct GNUNET_SCHEDULER_Task *
 783 GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay,
 784                                          enum GNUNET_SCHEDULER_Priority priority,
 785                                          const struct GNUNET_DISK_FileHandle *fd,
 786                                          int on_read, int on_write,
 787                                          GNUNET_SCHEDULER_TaskCallback task,
 788                                          void *task_cls);
 789
 790
 791 /**
 792  * Schedule a new task to be run with a specified delay or when any of
 793  * the specified file descriptor sets is ready.  The delay can be used
 794  * as a timeout on the socket(s) being ready.  The task will be
 795  * scheduled for execution once either the delay has expired or any of
 796  * the socket operations is ready.  This is the most general
 797  * function of the "add" family.  Note that the "prerequisite_task"
 798  * must be satisfied in addition to any of the other conditions.  In
 799  * other words, the task will be started when
 800  * <code>
 801  * (prerequisite-run)
 802  * && (delay-ready
 803  *     || any-rs-ready
 804  *     || any-ws-ready)
 805  * </code>
 806  *
 807  * @param prio how important is this task?
 808  * @param delay how long should we wait?
 809  * @param rs set of file descriptors we want to read (can be NULL)
 810  * @param ws set of file descriptors we want to write (can be NULL)
 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 "task" is started!
 815  */
 816 struct GNUNET_SCHEDULER_Task *
 817 GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio,
 818                              struct GNUNET_TIME_Relative delay,
 819                              const struct GNUNET_NETWORK_FDSet *rs,
 820                              const struct GNUNET_NETWORK_FDSet *ws,
 821                              GNUNET_SCHEDULER_TaskCallback task,
 822                              void *task_cls);
 823
 824 /**
 825  * Sets the select function to use in the scheduler (scheduler_select).
 826  *
 827  * @param new_select new select function to use (NULL to reset to default)
 828  * @param new_select_cls closure for @a new_select
 829  */
 830 void
 831 GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select,
 832                              void *new_select_cls);
 833
 834
 835 #if 0                           /* keep Emacsens' auto-indent happy */
 836 {
 837 #endif
 838 #ifdef __cplusplus
 839 }
 840 #endif
 841
 842 #endif
 843
 844 /** @} */ /* end of group scheduler */