src/include/gnunet_scheduler_lib.h

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