src/include/gnunet_scheduler_lib.h

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