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   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   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 of type @a et.
 220  *
 221  * This function will then queue the task to notify the application
 222  * that the task is ready (with the respective priority).
 223  *
 224  * @param task the task that is ready
 225  * @param et information about why the task is ready
 226  */
 227 void
 228 GNUNET_SCHEDULER_task_ready (struct GNUNET_SCHEDULER_Task *task,
 229                              enum GNUNET_SCHEDULER_EventType et);
 230
 231
 232 /**
 233  * Handle to the scheduler's state to be used by the driver.
 234  */
 235 struct GNUNET_SCHEDULER_Handle;
 236
 237
 238 /**
 239  * Function called by the driver to tell the scheduler to run some of
 240  * the tasks that are ready.  This function may return even though
 241  * there are tasks left to run just to give other tasks a chance as
 242  * well.  If we return #GNUNET_YES, the driver should call this
 243  * function again as soon as possible, while if we return #GNUNET_NO
 244  * it must block until the operating system has more work as the
 245  * scheduler has no more work to do right now.
 246  *
 247  * @param sh scheduler handle that was given to the `loop`
 248  * @return #GNUNET_OK if there are more tasks that are ready,
 249  *          and thus we would like to run more (yield to avoid
 250  *          blocking other activities for too long)
 251  *         #GNUNET_NO if we are done running tasks (yield to block)
 252  *         #GNUNET_SYSERR on error
 253  */
 254 int
 255 GNUNET_SCHEDULER_run_from_driver (struct GNUNET_SCHEDULER_Handle *sh);
 256
 257
 258 /**
 259  * API a driver has to implement for
 260  * #GNUNET_SCHEDULER_run_with_driver().
 261  */
 262 struct GNUNET_SCHEDULER_Driver
 263 {
 264
 265   /**
 266    * Closure to pass to the functions in this struct.
 267    */
 268   void *cls;
 269
 270   /**
 271    * Add a @a task to be run if the conditions given
 272    * in @a fdi are satisfied.
 273    *
 274    * @param cls closure
 275    * @param task task to add
 276    * @param fdi conditions to watch for
 277    * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 278    *   (i.e. @a fdi too high or invalid)
 279    */
 280   int
 281   (*add)(void *cls,
 282          struct GNUNET_SCHEDULER_Task *task,
 283          struct GNUNET_SCHEDULER_FdInfo *fdi);
 284
 285   /**
 286    * Delete a @a task from the set of tasks to be run.
 287    *
 288    * @param cls closure
 289    * @param task task to delete
 290    * @param fdi conditions to watch for (must match @e add call)
 291    * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 292    *   (i.e. @a task or @a fdi do not match prior @e add call)
 293    */
 294   int
 295   (*del)(void *cls,
 296          struct GNUNET_SCHEDULER_Task *task,
 297          const struct GNUNET_SCHEDULER_FdInfo *fdi);
 298
 299   /**
 300    * Set time at which we definitively want to get a wakeup call.
 301    *
 302    * @param cls closure
 303    * @param dt time when we want to wake up next
 304    */
 305   void
 306   (*set_wakeup)(void *cls,
 307                 struct GNUNET_TIME_Absolute dt);
 308
 309   /**
 310    * Event loop's "main" function, to be called from
 311    * #GNUNET_SCHEDULER_run_with_driver() to actually
 312    * launch the loop.
 313    *
 314    * @param cls closure
 315    * @param sh scheduler handle to pass to
 316    *     #GNUNET_SCHEDULER_run_from_driver()
 317    * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 318    */
 319   int
 320   (*loop)(void *cls,
 321           struct GNUNET_SCHEDULER_Handle *sh);
 322
 323 };
 324
 325
 326 /**
 327  * Signature of the main function of a task.
 328  *
 329  * @param cls closure
 330  */
 331 typedef void
 332 (*GNUNET_SCHEDULER_TaskCallback) (void *cls);
 333
 334
 335 /**
 336  * Initialize and run scheduler.  This function will return when all
 337  * tasks have completed.  On systems with signals, receiving a SIGTERM
 338  * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
 339  * to be run after the active task is complete.  As a result, SIGTERM
 340  * causes all shutdown tasks to be scheduled with reason
 341  * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
 342  * afterwards will execute normally!).  Note that any particular
 343  * signal will only shut down one scheduler; applications should
 344  * always only create a single scheduler.
 345  *
 346  * @param driver drive to use for the event loop
 347  * @param task task to run first (and immediately)
 348  * @param task_cls closure of @a task
 349  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 350  */
 351 int
 352 GNUNET_SCHEDULER_run_with_driver (const struct GNUNET_SCHEDULER_Driver *driver,
 353                                   GNUNET_SCHEDULER_TaskCallback task,
 354                                   void *task_cls);
 355
 356
 357 /**
 358  * Obtain the driver for using select() as the event loop.
 359  *
 360  * @return NULL on error
 361  */
 362 const struct GNUNET_SCHEDULER_Driver *
 363 GNUNET_SCHEDULER_driver_select (void);
 364
 365
 366 /**
 367  * Signature of the select function used by the scheduler.
 368  * #GNUNET_NETWORK_socket_select matches it.
 369  *
 370  * @param cls closure
 371  * @param rfds set of sockets to be checked for readability
 372  * @param wfds set of sockets to be checked for writability
 373  * @param efds set of sockets to be checked for exceptions
 374  * @param timeout relative value when to return
 375  * @return number of selected sockets, #GNUNET_SYSERR on error
 376  */
 377 typedef int
 378 (*GNUNET_SCHEDULER_select) (void *cls,
 379                             struct GNUNET_NETWORK_FDSet *rfds,
 380                             struct GNUNET_NETWORK_FDSet *wfds,
 381                             struct GNUNET_NETWORK_FDSet *efds,
 382                             struct GNUNET_TIME_Relative timeout);
 383
 384
 385 /**
 386  * Initialize and run scheduler.  This function will return when all
 387  * tasks have completed.  On systems with signals, receiving a SIGTERM
 388  * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
 389  * to be run after the active task is complete.  As a result, SIGTERM
 390  * causes all shutdown tasks to be scheduled with reason
 391  * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
 392  * afterwards will execute normally!).  Note that any particular
 393  * signal will only shut down one scheduler; applications should
 394  * always only create a single scheduler.
 395  *
 396  * @param task task to run first (and immediately)
 397  * @param task_cls closure of @a task
 398  */
 399 void
 400 GNUNET_SCHEDULER_run (GNUNET_SCHEDULER_TaskCallback task,
 401                       void *task_cls);
 402
 403 /**
 404  * Initialize and run scheduler.  This function will return when all
 405  * tasks have completed.  When @ install_signals is GNUNET_YES, then
 406  * this function behaves in the same was as GNUNET_SCHEDULER_run does.
 407  * If @ install_signals is GNUNET_NO then no signal handlers are
 408  * installed.
 409  *
 410  * @param install_signals whether to install signals (GNUNET_YES/NO)
 411  * @param task task to run first (and immediately)
 412  * @param task_cls closure of @a task
 413  */
 414 void
 415 GNUNET_SCHEDULER_run_with_optional_signals (int install_signals,
 416                                             GNUNET_SCHEDULER_TaskCallback task,
 417                                             void *task_cls);
 418
 419
 420 /**
 421  * Request the shutdown of a scheduler.  Marks all tasks
 422  * awaiting shutdown as ready. Note that tasks
 423  * scheduled with #GNUNET_SCHEDULER_add_shutdown() AFTER this call
 424  * will be delayed until the next shutdown signal.
 425  */
 426 void
 427 GNUNET_SCHEDULER_shutdown (void);
 428
 429
 430 /**
 431  * Get information about the current load of this scheduler.  Use this
 432  * function to determine if an elective task should be added or simply
 433  * dropped (if the decision should be made based on the number of
 434  * tasks ready to run).
 435  *
 436  * @param p priority-level to query, use KEEP to query the level
 437  *          of the current task, use COUNT to get the sum over
 438  *          all priority levels
 439  * @return number of tasks pending right now
 440  */
 441 unsigned int
 442 GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p);
 443
 444
 445 /**
 446  * Obtain the reasoning why the current task was
 447  * started.
 448  *
 449  * @return task context with information why the current task is run
 450  */
 451 const struct GNUNET_SCHEDULER_TaskContext *
 452 GNUNET_SCHEDULER_get_task_context (void);
 453
 454
 455 /**
 456  * Cancel the task with the specified identifier.
 457  * The task must not yet have run.
 458  *
 459  * @param task id of the task to cancel
 460  * @return the closure of the callback of the cancelled task
 461  */
 462 void *
 463 GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task);
 464
 465
 466 /**
 467  * Continue the current execution with the given function.  This is
 468  * similar to the other "add" functions except that there is no delay
 469  * and the reason code can be specified.
 470  *
 471  * @param task main function of the task
 472  * @param task_cls closure for @a task
 473  * @param reason reason for task invocation
 474  * @param priority priority to use for the task
 475  */
 476 void
 477 GNUNET_SCHEDULER_add_with_reason_and_priority (GNUNET_SCHEDULER_TaskCallback task,
 478                                                void *task_cls,
 479                                                enum GNUNET_SCHEDULER_Reason reason,
 480                                                enum GNUNET_SCHEDULER_Priority priority);
 481
 482
 483 /**
 484  * Schedule a new task to be run with a specified priority.
 485  *
 486  * @param prio how important is the new task?
 487  * @param task main function of the task
 488  * @param task_cls closure of @a task
 489  * @return unique task identifier for the job
 490  *         only valid until @a task is started!
 491  */
 492 struct GNUNET_SCHEDULER_Task *
 493 GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio,
 494                                     GNUNET_SCHEDULER_TaskCallback task,
 495                                     void *task_cls);
 496
 497
 498 /**
 499  * Schedule a new task to be run as soon as possible. Note that this
 500  * does not guarantee that this will be the next task that is being
 501  * run, as other tasks with higher priority (or that are already ready
 502  * to run) might get to run first.  Just as with delays, clients must
 503  * not rely on any particular order of execution between tasks
 504  * scheduled concurrently.
 505  *
 506  * The task will be run with the DEFAULT priority.
 507  *
 508  * @param task main function of the task
 509  * @param task_cls closure of @a task
 510  * @return unique task identifier for the job
 511  *         only valid until @a task is started!
 512  */
 513 struct GNUNET_SCHEDULER_Task *
 514 GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_TaskCallback task,
 515                           void *task_cls);
 516
 517
 518 /**
 519  * Schedule a new task to be run on shutdown, that is when a CTRL-C
 520  * signal is received, or when #GNUNET_SCHEDULER_shutdown() is being
 521  * invoked.
 522  *
 523  * @param task main function of the task
 524  * @param task_cls closure of @a task
 525  * @return unique task identifier for the job
 526  *         only valid until @a task is started!
 527  */
 528 struct GNUNET_SCHEDULER_Task *
 529 GNUNET_SCHEDULER_add_shutdown (GNUNET_SCHEDULER_TaskCallback task,
 530                                void *task_cls);
 531
 532
 533 /**
 534  * Schedule a new task to be run as soon as possible with the
 535  * (transitive) ignore-shutdown flag either explicitly set or
 536  * explicitly enabled.  This task (and all tasks created from it,
 537  * other than by another call to this function) will either count or
 538  * not count for the 'lifeness' of the process.  This API is only
 539  * useful in a few special cases.
 540  *
 541  * @param lifeness #GNUNET_YES if the task counts for lifeness, #GNUNET_NO if not.
 542  * @param task main function of the task
 543  * @param task_cls closure of @a task
 544  * @return unique task identifier for the job
 545  *         only valid until @a task is started!
 546  */
 547 struct GNUNET_SCHEDULER_Task *
 548 GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness,
 549                                         GNUNET_SCHEDULER_TaskCallback task,
 550                                         void *task_cls);
 551
 552
 553 /**
 554  * Schedule a new task to be run with a specified delay.  The task
 555  * will be scheduled for execution once the delay has expired. It
 556  * will be run with the DEFAULT priority.
 557  *
 558  * @param delay with which the operation should be run
 559  * @param task main function of the task
 560  * @param task_cls closure of @a task
 561  * @return unique task identifier for the job
 562  *         only valid until @a task is started!
 563  */
 564 struct GNUNET_SCHEDULER_Task *
 565 GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay,
 566                               GNUNET_SCHEDULER_TaskCallback task,
 567                               void *task_cls);
 568
 569
 570 /**
 571  * Schedule a new task to be run at the specified time.  The task
 572  * will be scheduled for execution once specified time has been
 573  * reached. It will be run with the DEFAULT priority.
 574  *
 575  * @param at time at which this operation should run
 576  * @param task main function of the task
 577  * @param task_cls closure of @a task
 578  * @return unique task identifier for the job
 579  *         only valid until @a task is started!
 580  */
 581 struct GNUNET_SCHEDULER_Task *
 582 GNUNET_SCHEDULER_add_at (struct GNUNET_TIME_Absolute at,
 583                          GNUNET_SCHEDULER_TaskCallback task,
 584                          void *task_cls);
 585
 586
 587 /**
 588  * Schedule a new task to be run with a specified delay.  The task
 589  * will be scheduled for execution once the delay has expired.
 590  *
 591  * @param delay when should this operation time out?
 592  * @param priority priority to use for the task
 593  * @param task main function of the task
 594  * @param task_cls closure of @a task
 595  * @return unique task identifier for the job
 596  *         only valid until @a task is started!
 597  */
 598 struct GNUNET_SCHEDULER_Task *
 599 GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay,
 600                                             enum GNUNET_SCHEDULER_Priority priority,
 601                                             GNUNET_SCHEDULER_TaskCallback task,
 602                                             void *task_cls);
 603
 604
 605 /**
 606  * Schedule a new task to be run at the specified time.  The task
 607  * will be scheduled for execution at time @a at.
 608  *
 609  * @param at time when the operation should run
 610  * @param priority priority to use for the task
 611  * @param task main function of the task
 612  * @param task_cls closure of @a task
 613  * @return unique task identifier for the job
 614  *         only valid until @a task is started!
 615  */
 616 struct GNUNET_SCHEDULER_Task *
 617 GNUNET_SCHEDULER_add_at_with_priority (struct GNUNET_TIME_Absolute at,
 618                                        enum GNUNET_SCHEDULER_Priority priority,
 619                                        GNUNET_SCHEDULER_TaskCallback task,
 620                                        void *task_cls);
 621
 622
 623 /**
 624  * Schedule a new task to be run with a specified delay or when the
 625  * specified file descriptor is ready for reading.  The delay can be
 626  * used as a timeout on the socket being ready.  The task will be
 627  * scheduled for execution once either the delay has expired or the
 628  * socket operation is ready.  It will be run with the DEFAULT priority.
 629  *
 630  * @param delay when should this operation time out?
 631  * @param rfd read file-descriptor
 632  * @param task main function of the task
 633  * @param task_cls closure of @a task
 634  * @return unique task identifier for the job
 635  *         only valid until @a task is started!
 636  */
 637 struct GNUNET_SCHEDULER_Task *
 638 GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay,
 639                                struct GNUNET_NETWORK_Handle *rfd,
 640                                GNUNET_SCHEDULER_TaskCallback task,
 641                                void *task_cls);
 642
 643
 644 /**
 645  * Schedule a new task to be run with a specified priority and to be
 646  * run after the specified delay or when the specified file descriptor
 647  * is ready for reading.  The delay can be used as a timeout on the
 648  * socket being ready.  The task will be scheduled for execution once
 649  * either the delay has expired or the socket operation is ready.  It
 650  * will be run with the DEFAULT priority.
 651  *
 652  * @param delay when should this operation time out?
 653  * @param priority priority to use for the task
 654  * @param rfd read file-descriptor
 655  * @param task main function of the task
 656  * @param task_cls closure of @a task
 657  * @return unique task identifier for the job
 658  *         only valid until @a task is started!
 659  */
 660 struct GNUNET_SCHEDULER_Task *
 661 GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay,
 662                                              enum GNUNET_SCHEDULER_Priority priority,
 663                                              struct GNUNET_NETWORK_Handle *rfd,
 664                                              GNUNET_SCHEDULER_TaskCallback task,
 665                                              void *task_cls);
 666
 667
 668 /**
 669  * Schedule a new task to be run with a specified delay or when the
 670  * specified file descriptor is ready for writing.  The delay can be
 671  * used as a timeout on the socket being ready.  The task will be
 672  * scheduled for execution once either the delay has expired or the
 673  * socket operation is ready.  It will be run with the DEFAULT priority.
 674  *
 675  * * @param delay when should this operation time out?
 676  * @param wfd write file-descriptor
 677  * @param task main function of the task
 678  * @param task_cls closure of @a task
 679  * @return unique task identifier for the job
 680  *         only valid until @a task is started!
 681  */
 682 struct GNUNET_SCHEDULER_Task *
 683 GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay,
 684                                 struct GNUNET_NETWORK_Handle *wfd,
 685                                 GNUNET_SCHEDULER_TaskCallback task,
 686                                 void *task_cls);
 687
 688
 689 /**
 690  * Schedule a new task to be run with a specified delay or when the
 691  * specified file descriptor is ready.  The delay can be
 692  * used as a timeout on the socket being ready.  The task will be
 693  * scheduled for execution once either the delay has expired or the
 694  * socket operation is ready.
 695  *
 696  * @param delay when should this operation time out?
 697  * @param priority priority of the task
 698  * @param fd file-descriptor
 699  * @param on_read whether to poll the file-descriptor for readability
 700  * @param on_write whether to poll the file-descriptor for writability
 701  * @param task main function of the task
 702  * @param task_cls closure of @a task
 703  * @return unique task identifier for the job
 704  *         only valid until "task" is started!
 705  */
 706 struct GNUNET_SCHEDULER_Task *
 707 GNUNET_SCHEDULER_add_net_with_priority  (struct GNUNET_TIME_Relative delay,
 708                                          enum GNUNET_SCHEDULER_Priority priority,
 709                                          struct GNUNET_NETWORK_Handle *fd,
 710                                          int on_read,
 711                                          int on_write,
 712                                          GNUNET_SCHEDULER_TaskCallback task,
 713                                          void *task_cls);
 714
 715 /**
 716  * Schedule a new task to be run with a specified delay or when the
 717  * specified file descriptor is ready for reading.  The delay can be
 718  * used as a timeout on the socket being ready.  The task will be
 719  * scheduled for execution once either the delay has expired or the
 720  * socket operation is ready. It will be run with the DEFAULT priority.
 721  *
 722  * * @param delay when should this operation time out?
 723  * @param rfd read 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 "task" is started!
 728  */
 729 struct GNUNET_SCHEDULER_Task *
 730 GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay,
 731                                 const struct GNUNET_DISK_FileHandle *rfd,
 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 for writing.  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. It will be run with the DEFAULT priority.
 742  *
 743  * * @param delay when should this operation time out?
 744  * @param wfd write file-descriptor
 745  * @param task main function of the task
 746  * @param task_cls closure of @a task
 747  * @return unique task identifier for the job
 748  *         only valid until @a task is started!
 749  */
 750 struct GNUNET_SCHEDULER_Task *
 751 GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay,
 752                                  const struct GNUNET_DISK_FileHandle *wfd,
 753                                  GNUNET_SCHEDULER_TaskCallback task,
 754                                  void *task_cls);
 755
 756
 757 /**
 758  * Schedule a new task to be run with a specified delay or when the
 759  * specified file descriptor is ready.  The delay can be
 760  * used as a timeout on the socket being ready.  The task will be
 761  * scheduled for execution once either the delay has expired or the
 762  * socket operation is ready.
 763  *
 764  * @param delay when should this operation time out?
 765  * @param priority priority of the task
 766  * @param fd file-descriptor
 767  * @param on_read whether to poll the file-descriptor for readability
 768  * @param on_write whether to poll the file-descriptor for writability
 769  * @param task main function of the task
 770  * @param task_cls closure of @a task
 771  * @return unique task identifier for the job
 772  *         only valid until @a task is started!
 773  */
 774 struct GNUNET_SCHEDULER_Task *
 775 GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay,
 776                                          enum GNUNET_SCHEDULER_Priority priority,
 777                                          const struct GNUNET_DISK_FileHandle *fd,
 778                                          int on_read, int on_write,
 779                                          GNUNET_SCHEDULER_TaskCallback task,
 780                                          void *task_cls);
 781
 782
 783 /**
 784  * Schedule a new task to be run with a specified delay or when any of
 785  * the specified file descriptor sets is ready.  The delay can be used
 786  * as a timeout on the socket(s) being ready.  The task will be
 787  * scheduled for execution once either the delay has expired or any of
 788  * the socket operations is ready.  This is the most general
 789  * function of the "add" family.  Note that the "prerequisite_task"
 790  * must be satisfied in addition to any of the other conditions.  In
 791  * other words, the task will be started when
 792  * <code>
 793  * (prerequisite-run)
 794  * && (delay-ready
 795  *     || any-rs-ready
 796  *     || any-ws-ready)
 797  * </code>
 798  *
 799  * @param prio how important is this task?
 800  * @param delay how long should we wait?
 801  * @param rs set of file descriptors we want to read (can be NULL)
 802  * @param ws set of file descriptors we want to write (can be NULL)
 803  * @param task main function of the task
 804  * @param task_cls closure of @a task
 805  * @return unique task identifier for the job
 806  *         only valid until "task" is started!
 807  */
 808 struct GNUNET_SCHEDULER_Task *
 809 GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio,
 810                              struct GNUNET_TIME_Relative delay,
 811                              const struct GNUNET_NETWORK_FDSet *rs,
 812                              const struct GNUNET_NETWORK_FDSet *ws,
 813                              GNUNET_SCHEDULER_TaskCallback task,
 814                              void *task_cls);
 815
 816 /**
 817  * Sets the select function to use in the scheduler (scheduler_select).
 818  *
 819  * @param new_select new select function to use (NULL to reset to default)
 820  * @param new_select_cls closure for @a new_select
 821  */
 822 void
 823 GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select,
 824                              void *new_select_cls);
 825
 826
 827 #if 0                           /* keep Emacsens' auto-indent happy */
 828 {
 829 #endif
 830 #ifdef __cplusplus
 831 }
 832 #endif
 833
 834 #endif
 835
 836 /** @} */ /* end of group scheduler */