src/include/gnunet_scheduler_lib.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2009-2013 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file include/gnunet_scheduler_lib.h
  23  * @brief API to schedule computations using continuation passing style
  24  * @author Christian Grothoff
  25  * @defgroup scheduler Event loop (scheduler)
  26  * @{
  27  */
  28
  29 #ifndef GNUNET_SCHEDULER_LIB_H
  30 #define GNUNET_SCHEDULER_LIB_H
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 /**
  41  * Opaque reference to a task.
  42  */
  43 struct GNUNET_SCHEDULER_Task;
  44
  45 /**
  46  * Reasons why the schedule may have triggered
  47  * the task now.
  48  */
  49 enum GNUNET_SCHEDULER_Reason
  50 {
  51   /**
  52    * This task is not ready.
  53    */
  54   GNUNET_SCHEDULER_REASON_NONE = 0,
  55
  56   /**
  57    * This is the very first task run during startup.
  58    */
  59   GNUNET_SCHEDULER_REASON_STARTUP = 1,
  60
  61   /**
  62    * We are shutting down and are running all shutdown-related tasks
  63    * (regardless of timeout, etc.).
  64    */
  65   GNUNET_SCHEDULER_REASON_SHUTDOWN = 2,
  66
  67   /**
  68    * The specified timeout has expired.
  69    * (also set if the delay given was 0).
  70    */
  71   GNUNET_SCHEDULER_REASON_TIMEOUT = 4,
  72
  73   /**
  74    * The reading socket is ready.
  75    */
  76   GNUNET_SCHEDULER_REASON_READ_READY = 8,
  77
  78   /**
  79    * The writing socket is ready.
  80    */
  81   GNUNET_SCHEDULER_REASON_WRITE_READY = 16,
  82
  83   /**
  84    * The prerequisite task is done.
  85    */
  86   GNUNET_SCHEDULER_REASON_PREREQ_DONE = 32
  87 };
  88
  89
  90 /**
  91  * Valid task priorities.  Use these, do not
  92  * pass random integers!
  93  */
  94 enum GNUNET_SCHEDULER_Priority
  95 {
  96   /**
  97    * Run with the same priority as the current job.
  98    */
  99   GNUNET_SCHEDULER_PRIORITY_KEEP = 0,
 100
 101   /**
 102    * Run when otherwise idle.
 103    */
 104   GNUNET_SCHEDULER_PRIORITY_IDLE = 1,
 105
 106   /**
 107    * Run as background job (higher than idle,
 108    * lower than default).
 109    */
 110   GNUNET_SCHEDULER_PRIORITY_BACKGROUND = 2,
 111
 112   /**
 113    * Run with the default priority (normal
 114    * P2P operations).  Any task that is scheduled
 115    * without an explicit priority being specified
 116    * will run with this priority.
 117    */
 118   GNUNET_SCHEDULER_PRIORITY_DEFAULT = 3,
 119
 120   /**
 121    * Run with high priority (important requests).
 122    * Higher than DEFAULT.
 123    */
 124   GNUNET_SCHEDULER_PRIORITY_HIGH = 4,
 125
 126   /**
 127    * Run with priority for interactive tasks.
 128    * Higher than "HIGH".
 129    */
 130   GNUNET_SCHEDULER_PRIORITY_UI = 5,
 131
 132   /**
 133    * Run with priority for urgent tasks.  Use
 134    * for things like aborts and shutdowns that
 135    * need to preempt "UI"-level tasks.
 136    * Higher than "UI".
 137    */
 138   GNUNET_SCHEDULER_PRIORITY_URGENT = 6,
 139
 140   /**
 141    * This is an internal priority level that is only used for tasks
 142    * that are being triggered due to shutdown (they have automatically
 143    * highest priority).  User code must not use this priority level
 144    * directly.  Tasks run with this priority level that internally
 145    * schedule other tasks will see their original priority level
 146    * be inherited (unless otherwise specified).
 147    */
 148   GNUNET_SCHEDULER_PRIORITY_SHUTDOWN = 7,
 149
 150   /**
 151    * Number of priorities (must be the last priority).
 152    * This priority must not be used by clients.
 153    */
 154   GNUNET_SCHEDULER_PRIORITY_COUNT = 8
 155 };
 156
 157 #include "gnunet_time_lib.h"
 158 #include "gnunet_network_lib.h"
 159
 160
 161 /**
 162  * Context information passed to each scheduler task.
 163  */
 164 struct GNUNET_SCHEDULER_TaskContext
 165 {
 166   /**
 167    * Reason why the task is run now
 168    */
 169   enum GNUNET_SCHEDULER_Reason reason;
 170
 171   /**
 172    * Set of file descriptors ready for reading;
 173    * note that additional bits may be set
 174    * that were not in the original request
 175    */
 176   const struct GNUNET_NETWORK_FDSet *read_ready;
 177
 178   /**
 179    * Set of file descriptors ready for writing;
 180    * note that additional bits may be set
 181    * that were not in the original request.
 182    */
 183   const struct GNUNET_NETWORK_FDSet *write_ready;
 184
 185 };
 186
 187
 188 /**
 189  * Signature of the main function of a task.
 190  *
 191  * @param cls closure
 192  * @param tc context information (why was this task triggered now)
 193  */
 194 typedef void
 195 (*GNUNET_SCHEDULER_TaskCallback) (void *cls,
 196                                   const struct GNUNET_SCHEDULER_TaskContext *tc);
 197
 198
 199 /**
 200  * Signature of the select function used by the scheduler.
 201  * #GNUNET_NETWORK_socket_select matches it.
 202  *
 203  * @param cls closure
 204  * @param rfds set of sockets to be checked for readability
 205  * @param wfds set of sockets to be checked for writability
 206  * @param efds set of sockets to be checked for exceptions
 207  * @param timeout relative value when to return
 208  * @return number of selected sockets, #GNUNET_SYSERR on error
 209  */
 210 typedef int
 211 (*GNUNET_SCHEDULER_select) (void *cls,
 212                             struct GNUNET_NETWORK_FDSet *rfds,
 213                             struct GNUNET_NETWORK_FDSet *wfds,
 214                             struct GNUNET_NETWORK_FDSet *efds,
 215                             struct GNUNET_TIME_Relative timeout);
 216
 217
 218 /**
 219  * Initialize and run scheduler.  This function will return when all
 220  * tasks have completed.  On systems with signals, receiving a SIGTERM
 221  * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
 222  * to be run after the active task is complete.  As a result, SIGTERM
 223  * causes all active tasks to be scheduled with reason
 224  * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
 225  * afterwards will execute normally!).  Note that any particular
 226  * signal will only shut down one scheduler; applications should
 227  * always only create a single scheduler.
 228  *
 229  * @param task task to run first (and immediately)
 230  * @param task_cls closure of task
 231  */
 232 void
 233 GNUNET_SCHEDULER_run (GNUNET_SCHEDULER_TaskCallback task,
 234                       void *task_cls);
 235
 236
 237 /**
 238  * Request the shutdown of the scheduler.  Marks all currently
 239  * pending tasks as ready because of shutdown.  This will
 240  * cause all tasks to run (as soon as possible, respecting
 241  * priorities and prerequisite tasks).  Note that tasks
 242  * scheduled AFTER this call may still be delayed arbitrarily.
 243  */
 244 void
 245 GNUNET_SCHEDULER_shutdown (void);
 246
 247
 248 /**
 249  * Get information about the current load of this scheduler.  Use this
 250  * function to determine if an elective task should be added or simply
 251  * dropped (if the decision should be made based on the number of
 252  * tasks ready to run).
 253  *
 254  * @param p priority-level to query, use KEEP to query the level
 255  *          of the current task, use COUNT to get the sum over
 256  *          all priority levels
 257  * @return number of tasks pending right now
 258  */
 259 unsigned int
 260 GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p);
 261
 262
 263 /**
 264  * Obtain the reason code for why the current task was
 265  * started.  Will return the same value as
 266  * the GNUNET_SCHEDULER_TaskContext's reason field.
 267  *
 268  * @return reason(s) why the current task is run
 269  */
 270 enum GNUNET_SCHEDULER_Reason
 271 GNUNET_SCHEDULER_get_reason (void);
 272
 273
 274 /**
 275  * Cancel the task with the specified identifier.
 276  * The task must not yet have run.
 277  *
 278  * @param task id of the task to cancel
 279  * @return the closure of the callback of the cancelled task
 280  */
 281 void *
 282 GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task);
 283
 284
 285 /**
 286  * Continue the current execution with the given function.  This is
 287  * similar to the other "add" functions except that there is no delay
 288  * and the reason code can be specified.
 289  *
 290  * @param task main function of the task
 291  * @param task_cls closure of task
 292  * @param reason reason for task invocation
 293  */
 294 void
 295 GNUNET_SCHEDULER_add_continuation (GNUNET_SCHEDULER_TaskCallback task,
 296                                    void *task_cls,
 297                                    enum GNUNET_SCHEDULER_Reason reason);
 298
 299
 300 /**
 301  * Continue the current execution with the given function.  This is
 302  * similar to the other "add" functions except that there is no delay
 303  * and the reason code can be specified.
 304  *
 305  * @param task main function of the task
 306  * @param task_cls closure for @a task
 307  * @param reason reason for task invocation
 308  * @param priority priority to use for the task
 309  */
 310 void
 311 GNUNET_SCHEDULER_add_continuation_with_priority (GNUNET_SCHEDULER_TaskCallback task,
 312                                                  void *task_cls,
 313                                                  enum GNUNET_SCHEDULER_Reason reason,
 314                                                  enum GNUNET_SCHEDULER_Priority priority);
 315
 316
 317 /**
 318  * Schedule a new task to be run with a specified priority.
 319  *
 320  * @param prio how important is the new task?
 321  * @param task main function of the task
 322  * @param task_cls closure of @a task
 323  * @return unique task identifier for the job
 324  *         only valid until @a task is started!
 325  */
 326 struct GNUNET_SCHEDULER_Task *
 327 GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio,
 328                                     GNUNET_SCHEDULER_TaskCallback task,
 329                                     void *task_cls);
 330
 331
 332 /**
 333  * Schedule a new task to be run as soon as possible. Note that this
 334  * does not guarantee that this will be the next task that is being
 335  * run, as other tasks with higher priority (or that are already ready
 336  * to run) might get to run first.  Just as with delays, clients must
 337  * not rely on any particular order of execution between tasks
 338  * scheduled concurrently.
 339  *
 340  * The task will be run with the DEFAULT priority.
 341  *
 342  * @param task main function of the task
 343  * @param task_cls closure of @a task
 344  * @return unique task identifier for the job
 345  *         only valid until @a task is started!
 346  */
 347 struct GNUNET_SCHEDULER_Task *
 348 GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_TaskCallback task,
 349                           void *task_cls);
 350
 351
 352 /**
 353  * Schedule a new task to be run as soon as possible with the
 354  * (transitive) ignore-shutdown flag either explicitly set or
 355  * explicitly enabled.  This task (and all tasks created from it,
 356  * other than by another call to this function) will either count or
 357  * not count for the 'lifeness' of the process.  This API is only
 358  * useful in a few special cases.
 359  *
 360  * @param lifeness #GNUNET_YES if the task counts for lifeness, #GNUNET_NO if not.
 361  * @param task main function of the task
 362  * @param task_cls closure of @a task
 363  * @return unique task identifier for the job
 364  *         only valid until @a task is started!
 365  */
 366 struct GNUNET_SCHEDULER_Task *
 367 GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness,
 368                                         GNUNET_SCHEDULER_TaskCallback task,
 369                                         void *task_cls);
 370
 371
 372 /**
 373  * Schedule a new task to be run with a specified delay.  The task
 374  * will be scheduled for execution once the delay has expired. It
 375  * will be run with the DEFAULT priority.
 376  *
 377  * * @param delay when should this operation time out? Use
 378  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 379  * @param task main function of the task
 380  * @param task_cls closure of @a task
 381  * @return unique task identifier for the job
 382  *         only valid until @a task is started!
 383  */
 384 struct GNUNET_SCHEDULER_Task *
 385 GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay,
 386                               GNUNET_SCHEDULER_TaskCallback task,
 387                               void *task_cls);
 388
 389
 390 /**
 391  * Schedule a new task to be run with a specified delay.  The task
 392  * will be scheduled for execution once the delay has expired.
 393  *
 394  * @param delay when should this operation time out? Use
 395  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 396  * @param priority priority to use for the task
 397  * @param task main function of the task
 398  * @param task_cls closure of @a task
 399  * @return unique task identifier for the job
 400  *         only valid until @a task is started!
 401  */
 402 struct GNUNET_SCHEDULER_Task *
 403 GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay,
 404                                             enum GNUNET_SCHEDULER_Priority priority,
 405                                             GNUNET_SCHEDULER_TaskCallback task,
 406                                             void *task_cls);
 407
 408
 409 /**
 410  * Schedule a new task to be run with a specified delay or when the
 411  * specified file descriptor is ready for reading.  The delay can be
 412  * used as a timeout on the socket being ready.  The task will be
 413  * scheduled for execution once either the delay has expired or the
 414  * socket operation is ready.  It will be run with the DEFAULT priority.
 415  *
 416  * * @param delay when should this operation time out? Use
 417  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 418  * @param rfd read file-descriptor
 419  * @param task main function of the task
 420  * @param task_cls closure of @a task
 421  * @return unique task identifier for the job
 422  *         only valid until @a task is started!
 423  */
 424 struct GNUNET_SCHEDULER_Task *
 425 GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay,
 426                                struct GNUNET_NETWORK_Handle *rfd,
 427                                GNUNET_SCHEDULER_TaskCallback task,
 428                                void *task_cls);
 429
 430
 431 /**
 432  * Schedule a new task to be run with a specified priority and to be
 433  * run after the specified delay or when the specified file descriptor
 434  * is ready for reading.  The delay can be used as a timeout on the
 435  * socket being ready.  The task will be scheduled for execution once
 436  * either the delay has expired or the socket operation is ready.  It
 437  * will be run with the DEFAULT priority.
 438  *
 439  * @param delay when should this operation time out? Use
 440  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 441  * @param priority priority to use for the task
 442  * @param rfd read file-descriptor
 443  * @param task main function of the task
 444  * @param task_cls closure of @a task
 445  * @return unique task identifier for the job
 446  *         only valid until @a task is started!
 447  */
 448 struct GNUNET_SCHEDULER_Task *
 449 GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay,
 450                                              enum GNUNET_SCHEDULER_Priority priority,
 451                                              struct GNUNET_NETWORK_Handle *rfd,
 452                                              GNUNET_SCHEDULER_TaskCallback task,
 453                                              void *task_cls);
 454
 455
 456 /**
 457  * Schedule a new task to be run with a specified delay or when the
 458  * specified file descriptor is ready for writing.  The delay can be
 459  * used as a timeout on the socket being ready.  The task will be
 460  * scheduled for execution once either the delay has expired or the
 461  * socket operation is ready.  It will be run with the DEFAULT priority.
 462  *
 463  * * @param delay when should this operation time out? Use
 464  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 465  * @param wfd write file-descriptor
 466  * @param task main function of the task
 467  * @param task_cls closure of @a task
 468  * @return unique task identifier for the job
 469  *         only valid until @a task is started!
 470  */
 471 struct GNUNET_SCHEDULER_Task *
 472 GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay,
 473                                 struct GNUNET_NETWORK_Handle *wfd,
 474                                 GNUNET_SCHEDULER_TaskCallback task,
 475                                 void *task_cls);
 476
 477
 478 /**
 479  * Schedule a new task to be run with a specified delay or when the
 480  * specified file descriptor is ready.  The delay can be
 481  * used as a timeout on the socket being ready.  The task will be
 482  * scheduled for execution once either the delay has expired or the
 483  * socket operation is ready.
 484  *
 485  * @param delay when should this operation time out? Use
 486  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 487  * @param priority priority of the task
 488  * @param fd file-descriptor
 489  * @param on_read whether to poll the file-descriptor for readability
 490  * @param on_write whether to poll the file-descriptor for writability
 491  * @param task main function of the task
 492  * @param task_cls closure of @a task
 493  * @return unique task identifier for the job
 494  *         only valid until "task" is started!
 495  */
 496 struct GNUNET_SCHEDULER_Task *
 497 GNUNET_SCHEDULER_add_net_with_priority  (struct GNUNET_TIME_Relative delay,
 498                                          enum GNUNET_SCHEDULER_Priority priority,
 499                                          struct GNUNET_NETWORK_Handle *fd,
 500                                          int on_read,
 501                                          int on_write,
 502                                          GNUNET_SCHEDULER_TaskCallback task,
 503                                          void *task_cls);
 504
 505 /**
 506  * Schedule a new task to be run with a specified delay or when the
 507  * specified file descriptor is ready for reading.  The delay can be
 508  * used as a timeout on the socket being ready.  The task will be
 509  * scheduled for execution once either the delay has expired or the
 510  * socket operation is ready. It will be run with the DEFAULT priority.
 511  *
 512  * * @param delay when should this operation time out? Use
 513  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 514  * @param rfd read file-descriptor
 515  * @param task main function of the task
 516  * @param task_cls closure of @a task
 517  * @return unique task identifier for the job
 518  *         only valid until "task" is started!
 519  */
 520 struct GNUNET_SCHEDULER_Task *
 521 GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay,
 522                                 const struct GNUNET_DISK_FileHandle *rfd,
 523                                 GNUNET_SCHEDULER_TaskCallback task,
 524                                 void *task_cls);
 525
 526
 527 /**
 528  * Schedule a new task to be run with a specified delay or when the
 529  * specified file descriptor is ready for writing.  The delay can be
 530  * used as a timeout on the socket being ready.  The task will be
 531  * scheduled for execution once either the delay has expired or the
 532  * socket operation is ready. It will be run with the DEFAULT priority.
 533  *
 534  * * @param delay when should this operation time out? Use
 535  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 536  * @param wfd write file-descriptor
 537  * @param task main function of the task
 538  * @param task_cls closure of @a task
 539  * @return unique task identifier for the job
 540  *         only valid until @a task is started!
 541  */
 542 struct GNUNET_SCHEDULER_Task *
 543 GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay,
 544                                  const struct GNUNET_DISK_FileHandle *wfd,
 545                                  GNUNET_SCHEDULER_TaskCallback task,
 546                                  void *task_cls);
 547
 548
 549 /**
 550  * Schedule a new task to be run with a specified delay or when the
 551  * specified file descriptor is ready.  The delay can be
 552  * used as a timeout on the socket being ready.  The task will be
 553  * scheduled for execution once either the delay has expired or the
 554  * socket operation is ready.
 555  *
 556  * @param delay when should this operation time out? Use
 557  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 558  * @param priority priority of the task
 559  * @param fd file-descriptor
 560  * @param on_read whether to poll the file-descriptor for readability
 561  * @param on_write whether to poll the file-descriptor for writability
 562  * @param task main function of the task
 563  * @param task_cls closure of @a task
 564  * @return unique task identifier for the job
 565  *         only valid until @a task is started!
 566  */
 567 struct GNUNET_SCHEDULER_Task *
 568 GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay,
 569                                          enum GNUNET_SCHEDULER_Priority priority,
 570                                          const struct GNUNET_DISK_FileHandle *fd,
 571                                          int on_read, int on_write,
 572                                          GNUNET_SCHEDULER_TaskCallback task,
 573                                          void *task_cls);
 574
 575
 576 /**
 577  * Schedule a new task to be run with a specified delay or when any of
 578  * the specified file descriptor sets is ready.  The delay can be used
 579  * as a timeout on the socket(s) being ready.  The task will be
 580  * scheduled for execution once either the delay has expired or any of
 581  * the socket operations is ready.  This is the most general
 582  * function of the "add" family.  Note that the "prerequisite_task"
 583  * must be satisfied in addition to any of the other conditions.  In
 584  * other words, the task will be started when
 585  * <code>
 586  * (prerequisite-run)
 587  * && (delay-ready
 588  *     || any-rs-ready
 589  *     || any-ws-ready
 590  *     || shutdown-active)
 591  * </code>
 592  *
 593  * @param prio how important is this task?
 594  * @param delay how long should we wait? Use #GNUNET_TIME_UNIT_FOREVER_REL for "forever",
 595  *        which means that the task will only be run after we receive SIGTERM
 596  * @param rs set of file descriptors we want to read (can be NULL)
 597  * @param ws set of file descriptors we want to write (can be NULL)
 598  * @param task main function of the task
 599  * @param task_cls closure of @a task
 600  * @return unique task identifier for the job
 601  *         only valid until "task" is started!
 602  */
 603 struct GNUNET_SCHEDULER_Task *
 604 GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio,
 605                              struct GNUNET_TIME_Relative delay,
 606                              const struct GNUNET_NETWORK_FDSet *rs,
 607                              const struct GNUNET_NETWORK_FDSet *ws,
 608                              GNUNET_SCHEDULER_TaskCallback task,
 609                              void *task_cls);
 610
 611 /**
 612  * Sets the select function to use in the scheduler (scheduler_select).
 613  *
 614  * @param new_select new select function to use (NULL to reset to default)
 615  * @param new_select_cls closure for 'new_select'
 616  */
 617 void
 618 GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select,
 619                              void *new_select_cls);
 620
 621
 622 /** @} */ /* end of group scheduler */
 623
 624 #if 0                           /* keep Emacsens' auto-indent happy */
 625 {
 626 #endif
 627 #ifdef __cplusplus
 628 }
 629 #endif
 630
 631 #endif