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    * (regardless of timeout, etc.).
  70    */
  71   GNUNET_SCHEDULER_REASON_SHUTDOWN = 2,
  72
  73   /**
  74    * The specified timeout has expired.
  75    * (also set if the delay given was 0).
  76    */
  77   GNUNET_SCHEDULER_REASON_TIMEOUT = 4,
  78
  79   /**
  80    * The reading socket is ready.
  81    */
  82   GNUNET_SCHEDULER_REASON_READ_READY = 8,
  83
  84   /**
  85    * The writing socket is ready.
  86    */
  87   GNUNET_SCHEDULER_REASON_WRITE_READY = 16,
  88
  89   /**
  90    * The prerequisite task is done.
  91    */
  92   GNUNET_SCHEDULER_REASON_PREREQ_DONE = 32
  93 };
  94
  95
  96 #include "gnunet_time_lib.h"
  97 #include "gnunet_network_lib.h"
  98
  99
 100 /**
 101  * Context information passed to each scheduler task.
 102  */
 103 struct GNUNET_SCHEDULER_TaskContext
 104 {
 105   /**
 106    * Reason why the task is run now
 107    */
 108   enum GNUNET_SCHEDULER_Reason reason;
 109
 110   /**
 111    * Set of file descriptors ready for reading;
 112    * note that additional bits may be set
 113    * that were not in the original request
 114    */
 115   const struct GNUNET_NETWORK_FDSet *read_ready;
 116
 117   /**
 118    * Set of file descriptors ready for writing;
 119    * note that additional bits may be set
 120    * that were not in the original request.
 121    */
 122   const struct GNUNET_NETWORK_FDSet *write_ready;
 123
 124 };
 125
 126
 127 /**
 128  * Signature of the main function of a task.
 129  *
 130  * @param cls closure
 131  * @param tc context information (why was this task triggered now)
 132  */
 133 typedef void
 134 (*GNUNET_SCHEDULER_TaskCallback) (void *cls);
 135
 136
 137 /**
 138  * Signature of the select function used by the scheduler.
 139  * #GNUNET_NETWORK_socket_select matches it.
 140  *
 141  * @param cls closure
 142  * @param rfds set of sockets to be checked for readability
 143  * @param wfds set of sockets to be checked for writability
 144  * @param efds set of sockets to be checked for exceptions
 145  * @param timeout relative value when to return
 146  * @return number of selected sockets, #GNUNET_SYSERR on error
 147  */
 148 typedef int
 149 (*GNUNET_SCHEDULER_select) (void *cls,
 150                             struct GNUNET_NETWORK_FDSet *rfds,
 151                             struct GNUNET_NETWORK_FDSet *wfds,
 152                             struct GNUNET_NETWORK_FDSet *efds,
 153                             struct GNUNET_TIME_Relative timeout);
 154
 155
 156 /**
 157  * Initialize and run scheduler.  This function will return when all
 158  * tasks have completed.  On systems with signals, receiving a SIGTERM
 159  * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
 160  * to be run after the active task is complete.  As a result, SIGTERM
 161  * causes all active tasks to be scheduled with reason
 162  * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
 163  * afterwards will execute normally!).  Note that any particular
 164  * signal will only shut down one scheduler; applications should
 165  * always only create a single scheduler.
 166  *
 167  * @param task task to run first (and immediately)
 168  * @param task_cls closure of @a task
 169  */
 170 void
 171 GNUNET_SCHEDULER_run (GNUNET_SCHEDULER_TaskCallback task,
 172                       void *task_cls);
 173
 174
 175 /**
 176  * Request the shutdown of the scheduler.  Marks all currently
 177  * pending tasks as ready because of shutdown.  This will
 178  * cause all tasks to run (as soon as possible, respecting
 179  * priorities and prerequisite tasks).  Note that tasks
 180  * scheduled AFTER this call may still be delayed arbitrarily.
 181  */
 182 void
 183 GNUNET_SCHEDULER_shutdown (void);
 184
 185
 186 /**
 187  * Get information about the current load of this scheduler.  Use this
 188  * function to determine if an elective task should be added or simply
 189  * dropped (if the decision should be made based on the number of
 190  * tasks ready to run).
 191  *
 192  * @param p priority-level to query, use KEEP to query the level
 193  *          of the current task, use COUNT to get the sum over
 194  *          all priority levels
 195  * @return number of tasks pending right now
 196  */
 197 unsigned int
 198 GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p);
 199
 200
 201 /**
 202  * Obtain the reasoning why the current task was
 203  * started.
 204  *
 205  * @return task context with information why the current task is run
 206  */
 207 const struct GNUNET_SCHEDULER_TaskContext *
 208 GNUNET_SCHEDULER_get_task_context (void);
 209
 210
 211 /**
 212  * Cancel the task with the specified identifier.
 213  * The task must not yet have run.
 214  *
 215  * @param task id of the task to cancel
 216  * @return the closure of the callback of the cancelled task
 217  */
 218 void *
 219 GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task);
 220
 221
 222 /**
 223  * Continue the current execution with the given function.  This is
 224  * similar to the other "add" functions except that there is no delay
 225  * and the reason code can be specified.
 226  *
 227  * @param task main function of the task
 228  * @param task_cls closure for @a task
 229  * @param reason reason for task invocation
 230  * @param priority priority to use for the task
 231  */
 232 void
 233 GNUNET_SCHEDULER_add_with_reason_and_priority (GNUNET_SCHEDULER_TaskCallback task,
 234                                                void *task_cls,
 235                                                enum GNUNET_SCHEDULER_Reason reason,
 236                                                enum GNUNET_SCHEDULER_Priority priority);
 237
 238
 239 /**
 240  * Schedule a new task to be run with a specified priority.
 241  *
 242  * @param prio how important is the new task?
 243  * @param task main function of the task
 244  * @param task_cls closure of @a task
 245  * @return unique task identifier for the job
 246  *         only valid until @a task is started!
 247  */
 248 struct GNUNET_SCHEDULER_Task *
 249 GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio,
 250                                     GNUNET_SCHEDULER_TaskCallback task,
 251                                     void *task_cls);
 252
 253
 254 /**
 255  * Schedule a new task to be run as soon as possible. Note that this
 256  * does not guarantee that this will be the next task that is being
 257  * run, as other tasks with higher priority (or that are already ready
 258  * to run) might get to run first.  Just as with delays, clients must
 259  * not rely on any particular order of execution between tasks
 260  * scheduled concurrently.
 261  *
 262  * The task will be run with the DEFAULT priority.
 263  *
 264  * @param task main function of the task
 265  * @param task_cls closure of @a task
 266  * @return unique task identifier for the job
 267  *         only valid until @a task is started!
 268  */
 269 struct GNUNET_SCHEDULER_Task *
 270 GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_TaskCallback task,
 271                           void *task_cls);
 272
 273
 274 /**
 275  * Schedule a new task to be run as soon as possible with the
 276  * (transitive) ignore-shutdown flag either explicitly set or
 277  * explicitly enabled.  This task (and all tasks created from it,
 278  * other than by another call to this function) will either count or
 279  * not count for the 'lifeness' of the process.  This API is only
 280  * useful in a few special cases.
 281  *
 282  * @param lifeness #GNUNET_YES if the task counts for lifeness, #GNUNET_NO if not.
 283  * @param task main function of the task
 284  * @param task_cls closure of @a task
 285  * @return unique task identifier for the job
 286  *         only valid until @a task is started!
 287  */
 288 struct GNUNET_SCHEDULER_Task *
 289 GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness,
 290                                         GNUNET_SCHEDULER_TaskCallback task,
 291                                         void *task_cls);
 292
 293
 294 /**
 295  * Schedule a new task to be run with a specified delay.  The task
 296  * will be scheduled for execution once the delay has expired. It
 297  * will be run with the DEFAULT priority.
 298  *
 299  * * @param delay when should this operation time out? Use
 300  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 301  * @param task main function of the task
 302  * @param task_cls closure of @a task
 303  * @return unique task identifier for the job
 304  *         only valid until @a task is started!
 305  */
 306 struct GNUNET_SCHEDULER_Task *
 307 GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay,
 308                               GNUNET_SCHEDULER_TaskCallback task,
 309                               void *task_cls);
 310
 311
 312 /**
 313  * Schedule a new task to be run with a specified delay.  The task
 314  * will be scheduled for execution once the delay has expired.
 315  *
 316  * @param delay when should this operation time out? Use
 317  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 318  * @param priority priority to use for the task
 319  * @param task main function of the task
 320  * @param task_cls closure of @a task
 321  * @return unique task identifier for the job
 322  *         only valid until @a task is started!
 323  */
 324 struct GNUNET_SCHEDULER_Task *
 325 GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay,
 326                                             enum GNUNET_SCHEDULER_Priority priority,
 327                                             GNUNET_SCHEDULER_TaskCallback task,
 328                                             void *task_cls);
 329
 330
 331 /**
 332  * Schedule a new task to be run with a specified delay or when the
 333  * specified file descriptor is ready for reading.  The delay can be
 334  * used as a timeout on the socket being ready.  The task will be
 335  * scheduled for execution once either the delay has expired or the
 336  * socket operation is ready.  It will be run with the DEFAULT priority.
 337  *
 338  * * @param delay when should this operation time out? Use
 339  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 340  * @param rfd read file-descriptor
 341  * @param task main function of the task
 342  * @param task_cls closure of @a task
 343  * @return unique task identifier for the job
 344  *         only valid until @a task is started!
 345  */
 346 struct GNUNET_SCHEDULER_Task *
 347 GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay,
 348                                struct GNUNET_NETWORK_Handle *rfd,
 349                                GNUNET_SCHEDULER_TaskCallback task,
 350                                void *task_cls);
 351
 352
 353 /**
 354  * Schedule a new task to be run with a specified priority and to be
 355  * run after the specified delay or when the specified file descriptor
 356  * is ready for reading.  The delay can be used as a timeout on the
 357  * socket being ready.  The task will be scheduled for execution once
 358  * either the delay has expired or the socket operation is ready.  It
 359  * will be run with the DEFAULT priority.
 360  *
 361  * @param delay when should this operation time out? Use
 362  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 363  * @param priority priority to use for the task
 364  * @param rfd read file-descriptor
 365  * @param task main function of the task
 366  * @param task_cls closure of @a task
 367  * @return unique task identifier for the job
 368  *         only valid until @a task is started!
 369  */
 370 struct GNUNET_SCHEDULER_Task *
 371 GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay,
 372                                              enum GNUNET_SCHEDULER_Priority priority,
 373                                              struct GNUNET_NETWORK_Handle *rfd,
 374                                              GNUNET_SCHEDULER_TaskCallback task,
 375                                              void *task_cls);
 376
 377
 378 /**
 379  * Schedule a new task to be run with a specified delay or when the
 380  * specified file descriptor is ready for writing.  The delay can be
 381  * used as a timeout on the socket being ready.  The task will be
 382  * scheduled for execution once either the delay has expired or the
 383  * socket operation is ready.  It will be run with the DEFAULT priority.
 384  *
 385  * * @param delay when should this operation time out? Use
 386  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 387  * @param wfd write file-descriptor
 388  * @param task main function of the task
 389  * @param task_cls closure of @a task
 390  * @return unique task identifier for the job
 391  *         only valid until @a task is started!
 392  */
 393 struct GNUNET_SCHEDULER_Task *
 394 GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay,
 395                                 struct GNUNET_NETWORK_Handle *wfd,
 396                                 GNUNET_SCHEDULER_TaskCallback task,
 397                                 void *task_cls);
 398
 399
 400 /**
 401  * Schedule a new task to be run with a specified delay or when the
 402  * specified file descriptor is ready.  The delay can be
 403  * used as a timeout on the socket being ready.  The task will be
 404  * scheduled for execution once either the delay has expired or the
 405  * socket operation is ready.
 406  *
 407  * @param delay when should this operation time out? Use
 408  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 409  * @param priority priority of the task
 410  * @param fd file-descriptor
 411  * @param on_read whether to poll the file-descriptor for readability
 412  * @param on_write whether to poll the file-descriptor for writability
 413  * @param task main function of the task
 414  * @param task_cls closure of @a task
 415  * @return unique task identifier for the job
 416  *         only valid until "task" is started!
 417  */
 418 struct GNUNET_SCHEDULER_Task *
 419 GNUNET_SCHEDULER_add_net_with_priority  (struct GNUNET_TIME_Relative delay,
 420                                          enum GNUNET_SCHEDULER_Priority priority,
 421                                          struct GNUNET_NETWORK_Handle *fd,
 422                                          int on_read,
 423                                          int on_write,
 424                                          GNUNET_SCHEDULER_TaskCallback task,
 425                                          void *task_cls);
 426
 427 /**
 428  * Schedule a new task to be run with a specified delay or when the
 429  * specified file descriptor is ready for reading.  The delay can be
 430  * used as a timeout on the socket being ready.  The task will be
 431  * scheduled for execution once either the delay has expired or the
 432  * socket operation is ready. It will be run with the DEFAULT priority.
 433  *
 434  * * @param delay when should this operation time out? Use
 435  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 436  * @param rfd read file-descriptor
 437  * @param task main function of the task
 438  * @param task_cls closure of @a task
 439  * @return unique task identifier for the job
 440  *         only valid until "task" is started!
 441  */
 442 struct GNUNET_SCHEDULER_Task *
 443 GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay,
 444                                 const struct GNUNET_DISK_FileHandle *rfd,
 445                                 GNUNET_SCHEDULER_TaskCallback task,
 446                                 void *task_cls);
 447
 448
 449 /**
 450  * Schedule a new task to be run with a specified delay or when the
 451  * specified file descriptor is ready for writing.  The delay can be
 452  * used as a timeout on the socket being ready.  The task will be
 453  * scheduled for execution once either the delay has expired or the
 454  * socket operation is ready. It will be run with the DEFAULT priority.
 455  *
 456  * * @param delay when should this operation time out? Use
 457  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 458  * @param wfd write file-descriptor
 459  * @param task main function of the task
 460  * @param task_cls closure of @a task
 461  * @return unique task identifier for the job
 462  *         only valid until @a task is started!
 463  */
 464 struct GNUNET_SCHEDULER_Task *
 465 GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay,
 466                                  const struct GNUNET_DISK_FileHandle *wfd,
 467                                  GNUNET_SCHEDULER_TaskCallback task,
 468                                  void *task_cls);
 469
 470
 471 /**
 472  * Schedule a new task to be run with a specified delay or when the
 473  * specified file descriptor is ready.  The delay can be
 474  * used as a timeout on the socket being ready.  The task will be
 475  * scheduled for execution once either the delay has expired or the
 476  * socket operation is ready.
 477  *
 478  * @param delay when should this operation time out? Use
 479  *        #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown"
 480  * @param priority priority of the task
 481  * @param fd file-descriptor
 482  * @param on_read whether to poll the file-descriptor for readability
 483  * @param on_write whether to poll the file-descriptor for writability
 484  * @param task main function of the task
 485  * @param task_cls closure of @a task
 486  * @return unique task identifier for the job
 487  *         only valid until @a task is started!
 488  */
 489 struct GNUNET_SCHEDULER_Task *
 490 GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay,
 491                                          enum GNUNET_SCHEDULER_Priority priority,
 492                                          const struct GNUNET_DISK_FileHandle *fd,
 493                                          int on_read, int on_write,
 494                                          GNUNET_SCHEDULER_TaskCallback task,
 495                                          void *task_cls);
 496
 497
 498 /**
 499  * Schedule a new task to be run with a specified delay or when any of
 500  * the specified file descriptor sets is ready.  The delay can be used
 501  * as a timeout on the socket(s) being ready.  The task will be
 502  * scheduled for execution once either the delay has expired or any of
 503  * the socket operations is ready.  This is the most general
 504  * function of the "add" family.  Note that the "prerequisite_task"
 505  * must be satisfied in addition to any of the other conditions.  In
 506  * other words, the task will be started when
 507  * <code>
 508  * (prerequisite-run)
 509  * && (delay-ready
 510  *     || any-rs-ready
 511  *     || any-ws-ready
 512  *     || shutdown-active)
 513  * </code>
 514  *
 515  * @param prio how important is this task?
 516  * @param delay how long should we wait? Use #GNUNET_TIME_UNIT_FOREVER_REL for "forever",
 517  *        which means that the task will only be run after we receive SIGTERM
 518  * @param rs set of file descriptors we want to read (can be NULL)
 519  * @param ws set of file descriptors we want to write (can be NULL)
 520  * @param task main function of the task
 521  * @param task_cls closure of @a task
 522  * @return unique task identifier for the job
 523  *         only valid until "task" is started!
 524  */
 525 struct GNUNET_SCHEDULER_Task *
 526 GNUNET_SCHEDULER_add_select (enum GNUNET_SCHEDULER_Priority prio,
 527                              struct GNUNET_TIME_Relative delay,
 528                              const struct GNUNET_NETWORK_FDSet *rs,
 529                              const struct GNUNET_NETWORK_FDSet *ws,
 530                              GNUNET_SCHEDULER_TaskCallback task,
 531                              void *task_cls);
 532
 533 /**
 534  * Sets the select function to use in the scheduler (scheduler_select).
 535  *
 536  * @param new_select new select function to use (NULL to reset to default)
 537  * @param new_select_cls closure for 'new_select'
 538  */
 539 void
 540 GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select,
 541                              void *new_select_cls);
 542
 543
 544 #if 0                           /* keep Emacsens' auto-indent happy */
 545 {
 546 #endif
 547 #ifdef __cplusplus
 548 }
 549 #endif
 550
 551 #endif
 552
 553 /** @} */ /* end of group scheduler */