src/include/gnunet_scheduler_lib.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2009-2016 GNUnet e.V.
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18       Boston, MA 02110-1301, USA.
  19  */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * API to schedule computations using continuation passing style
  26  *
  27  * @defgroup scheduler  Scheduler library
  28  * Event loop (scheduler)
  29  *
  30  * Schedule computations using continuation passing style.
  31  *
  32  * @{
  33  */
  34
  35 #ifndef GNUNET_SCHEDULER_LIB_H
  36 #define GNUNET_SCHEDULER_LIB_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 /**
  47  * Opaque reference to a task.
  48  */
  49 struct GNUNET_SCHEDULER_Task;
  50
  51 /**
  52  * Reasons why the schedule may have triggered
  53  * the task now.
  54  */
  55 enum GNUNET_SCHEDULER_Reason
  56 {
  57   /**
  58    * This task is not ready.
  59    */
  60   GNUNET_SCHEDULER_REASON_NONE = 0,
  61
  62   /**
  63    * This is the very first task run during startup.
  64    */
  65   GNUNET_SCHEDULER_REASON_STARTUP = 1,
  66
  67   /**
  68    * We are shutting down and are running all shutdown-related tasks.
  69    */
  70   GNUNET_SCHEDULER_REASON_SHUTDOWN = 2,
  71
  72   /**
  73    * The specified timeout has expired.
  74    * (also set if the delay given was 0).
  75    */
  76   GNUNET_SCHEDULER_REASON_TIMEOUT = 4,
  77
  78   /**
  79    * The reading socket is ready.
  80    */
  81   GNUNET_SCHEDULER_REASON_READ_READY = 8,
  82
  83   /**
  84    * The writing socket is ready.
  85    */
  86   GNUNET_SCHEDULER_REASON_WRITE_READY = 16,
  87
  88   /**
  89    * The prerequisite task is done.
  90    */
  91   GNUNET_SCHEDULER_REASON_PREREQ_DONE = 32
  92 };
  93
  94
  95 #include "gnunet_time_lib.h"
  96 #include "gnunet_network_lib.h"
  97
  98
  99 /**
 100  * Context information passed to each scheduler task.
 101  */
 102 struct GNUNET_SCHEDULER_TaskContext
 103 {
 104   /**
 105    * Reason why the task is run now
 106    */
 107   enum GNUNET_SCHEDULER_Reason reason;
 108
 109   /**
 110    * Set of file descriptors ready for reading;
 111    * note that additional bits may be set
 112    * that were not in the original request
 113    */
 114   const struct GNUNET_NETWORK_FDSet *read_ready;
 115
 116   /**
 117    * Set of file descriptors ready for writing;
 118    * note that additional bits may be set
 119    * that were not in the original request.
 120    */
 121   const struct GNUNET_NETWORK_FDSet *write_ready;
 122
 123 };
 124
 125
 126 /**
 127  * Signature of the main function of a task.
 128  *
 129  * @param cls closure
 130  * @param tc context information (why was this task triggered now)
 131  */
 132 typedef void
 133 (*GNUNET_SCHEDULER_TaskCallback) (void *cls);
 134
 135
 136 /**
 137  * Signature of the select function used by the scheduler.
 138  * #GNUNET_NETWORK_socket_select matches it.
 139  *
 140  * @param cls closure
 141  * @param rfds set of sockets to be checked for readability
 142  * @param wfds set of sockets to be checked for writability
 143  * @param efds set of sockets to be checked for exceptions
 144  * @param timeout relative value when to return
 145  * @return number of selected sockets, #GNUNET_SYSERR on error
 146  */
 147 typedef int
 148 (*GNUNET_SCHEDULER_select) (void *cls,
 149                             struct GNUNET_NETWORK_FDSet *rfds,
 150                             struct GNUNET_NETWORK_FDSet *wfds,
 151                             struct GNUNET_NETWORK_FDSet *efds,
 152                             struct GNUNET_TIME_Relative timeout);
 153
 154
 155 /**
 156  * Initialize and run scheduler.  This function will return when all
 157  * tasks have completed.  On systems with signals, receiving a SIGTERM
 158  * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown
 159  * to be run after the active task is complete.  As a result, SIGTERM
 160  * causes all shutdown tasks to be scheduled with reason
 161  * #GNUNET_SCHEDULER_REASON_SHUTDOWN.  (However, tasks added
 162  * afterwards will execute normally!).  Note that any particular
 163  * signal will only shut down one scheduler; applications should
 164  * always only create a single scheduler.
 165  *
 166  * @param task task to run first (and immediately)
 167  * @param task_cls closure of @a task
 168  */
 169 void
 170 GNUNET_SCHEDULER_run (GNUNET_SCHEDULER_TaskCallback task,
 171                       void *task_cls);
 172
 173
 174 /**
 175  * Request the shutdown of a scheduler.  Marks all tasks
 176  * awaiting shutdown as ready. Note that tasks
 177  * scheduled with #GNUNET_SCHEDULER_add_shutdown() AFTER this call
 178  * will be delayed until the next shutdown signal.
 179  */
 180 void
 181 GNUNET_SCHEDULER_shutdown (void);
 182
 183
 184 /**
 185  * Get information about the current load of this scheduler.  Use this
 186  * function to determine if an elective task should be added or simply
 187  * dropped (if the decision should be made based on the number of
 188  * tasks ready to run).
 189  *
 190  * @param p priority-level to query, use KEEP to query the level
 191  *          of the current task, use COUNT to get the sum over
 192  *          all priority levels
 193  * @return number of tasks pending right now
 194  */
 195 unsigned int
 196 GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p);
 197
 198
 199 /**
 200  * Obtain the reasoning why the current task was
 201  * started.
 202  *
 203  * @return task context with information why the current task is run
 204  */
 205 const struct GNUNET_SCHEDULER_TaskContext *
 206 GNUNET_SCHEDULER_get_task_context (void);
 207
 208
 209 /**
 210  * Cancel the task with the specified identifier.
 211  * The task must not yet have run.
 212  *
 213  * @param task id of the task to cancel
 214  * @return the closure of the callback of the cancelled task
 215  */
 216 void *
 217 GNUNET_SCHEDULER_cancel (struct GNUNET_SCHEDULER_Task *task);
 218
 219
 220 /**
 221  * Continue the current execution with the given function.  This is
 222  * similar to the other "add" functions except that there is no delay
 223  * and the reason code can be specified.
 224  *
 225  * @param task main function of the task
 226  * @param task_cls closure for @a task
 227  * @param reason reason for task invocation
 228  * @param priority priority to use for the task
 229  */
 230 void
 231 GNUNET_SCHEDULER_add_with_reason_and_priority (GNUNET_SCHEDULER_TaskCallback task,
 232                                                void *task_cls,
 233                                                enum GNUNET_SCHEDULER_Reason reason,
 234                                                enum GNUNET_SCHEDULER_Priority priority);
 235
 236
 237 /**
 238  * Schedule a new task to be run with a specified priority.
 239  *
 240  * @param prio how important is the new task?
 241  * @param task main function of the task
 242  * @param task_cls closure of @a task
 243  * @return unique task identifier for the job
 244  *         only valid until @a task is started!
 245  */
 246 struct GNUNET_SCHEDULER_Task *
 247 GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio,
 248                                     GNUNET_SCHEDULER_TaskCallback task,
 249                                     void *task_cls);
 250
 251
 252 /**
 253  * Schedule a new task to be run as soon as possible. Note that this
 254  * does not guarantee that this will be the next task that is being
 255  * run, as other tasks with higher priority (or that are already ready
 256  * to run) might get to run first.  Just as with delays, clients must
 257  * not rely on any particular order of execution between tasks
 258  * scheduled concurrently.
 259  *
 260  * The task will be run with the DEFAULT priority.
 261  *
 262  * @param task main function of the task
 263  * @param task_cls closure of @a task
 264  * @return unique task identifier for the job
 265  *         only valid until @a task is started!
 266  */
 267 struct GNUNET_SCHEDULER_Task *
 268 GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_TaskCallback task,
 269                           void *task_cls);
 270
 271
 272 /**
 273  * Schedule a new task to be run on shutdown, that is when a CTRL-C
 274  * signal is received, or when #GNUNET_SCHEDULER_shutdown() is being
 275  * invoked.
 276  *
 277  * @param task main function of the task
 278  * @param task_cls closure of @a task
 279  * @return unique task identifier for the job
 280  *         only valid until @a task is started!
 281  */
 282 struct GNUNET_SCHEDULER_Task *
 283 GNUNET_SCHEDULER_add_shutdown (GNUNET_SCHEDULER_TaskCallback task,
 284                                void *task_cls);
 285
 286
 287 /**
 288  * Schedule a new task to be run as soon as possible with the
 289  * (transitive) ignore-shutdown flag either explicitly set or
 290  * explicitly enabled.  This task (and all tasks created from it,
 291  * other than by another call to this function) will either count or
 292  * not count for the 'lifeness' of the process.  This API is only
 293  * useful in a few special cases.
 294  *
 295  * @param lifeness #GNUNET_YES if the task counts for lifeness, #GNUNET_NO if not.
 296  * @param task main function of the task
 297  * @param task_cls closure of @a task
 298  * @return unique task identifier for the job
 299  *         only valid until @a task is started!
 300  */
 301 struct GNUNET_SCHEDULER_Task *
 302 GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness,
 303                                         GNUNET_SCHEDULER_TaskCallback task,
 304                                         void *task_cls);
 305
 306
 307 /**
 308  * Schedule a new task to be run with a specified delay.  The task
 309  * will be scheduled for execution once the delay has expired. It
 310  * will be run with the DEFAULT priority.
 311  *
 312  * @param delay when should this operation time out?
 313  * @param task main function of the task
 314  * @param task_cls closure of @a task
 315  * @return unique task identifier for the job
 316  *         only valid until @a task is started!
 317  */
 318 struct GNUNET_SCHEDULER_Task *
 319 GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay,
 320                               GNUNET_SCHEDULER_TaskCallback task,
 321                               void *task_cls);
 322
 323
 324 /**
 325  * Schedule a new task to be run with a specified delay.  The task
 326  * will be scheduled for execution once the delay has expired.
 327  *
 328  * @param delay when should this operation time out?
 329  * @param priority priority to use for the task
 330  * @param task main function of the task
 331  * @param task_cls closure of @a task
 332  * @return unique task identifier for the job
 333  *         only valid until @a task is started!
 334  */
 335 struct GNUNET_SCHEDULER_Task *
 336 GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay,
 337                                             enum GNUNET_SCHEDULER_Priority priority,
 338                                             GNUNET_SCHEDULER_TaskCallback task,
 339                                             void *task_cls);
 340
 341
 342 /**
 343  * Schedule a new task to be run with a specified delay or when the
 344  * specified file descriptor is ready for reading.  The delay can be
 345  * used as a timeout on the socket being ready.  The task will be
 346  * scheduled for execution once either the delay has expired or the
 347  * socket operation is ready.  It will be run with the DEFAULT priority.
 348  *
 349  * * @param delay when should this operation time out?
 350  * @param rfd read file-descriptor
 351  * @param task main function of the task
 352  * @param task_cls closure of @a task
 353  * @return unique task identifier for the job
 354  *         only valid until @a task is started!
 355  */
 356 struct GNUNET_SCHEDULER_Task *
 357 GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay,
 358                                struct GNUNET_NETWORK_Handle *rfd,
 359                                GNUNET_SCHEDULER_TaskCallback task,
 360                                void *task_cls);
 361
 362
 363 /**
 364  * Schedule a new task to be run with a specified priority and to be
 365  * run after the specified delay or when the specified file descriptor
 366  * is ready for reading.  The delay can be used as a timeout on the
 367  * socket being ready.  The task will be scheduled for execution once
 368  * either the delay has expired or the socket operation is ready.  It
 369  * will be run with the DEFAULT priority.
 370  *
 371  * @param delay when should this operation time out?
 372  * @param priority priority to use for the task
 373  * @param rfd read file-descriptor
 374  * @param task main function of the task
 375  * @param task_cls closure of @a task
 376  * @return unique task identifier for the job
 377  *         only valid until @a task is started!
 378  */
 379 struct GNUNET_SCHEDULER_Task *
 380 GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay,
 381                                              enum GNUNET_SCHEDULER_Priority priority,
 382                                              struct GNUNET_NETWORK_Handle *rfd,
 383                                              GNUNET_SCHEDULER_TaskCallback task,
 384                                              void *task_cls);
 385
 386
 387 /**
 388  * Schedule a new task to be run with a specified delay or when the
 389  * specified file descriptor is ready for writing.  The delay can be
 390  * used as a timeout on the socket being ready.  The task will be
 391  * scheduled for execution once either the delay has expired or the
 392  * socket operation is ready.  It will be run with the DEFAULT priority.
 393  *
 394  * * @param delay when should this operation time out?
 395  * @param wfd write file-descriptor
 396  * @param task main function of the task
 397  * @param task_cls closure of @a task
 398  * @return unique task identifier for the job
 399  *         only valid until @a task is started!
 400  */
 401 struct GNUNET_SCHEDULER_Task *
 402 GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay,
 403                                 struct GNUNET_NETWORK_Handle *wfd,
 404                                 GNUNET_SCHEDULER_TaskCallback task,
 405                                 void *task_cls);
 406
 407
 408 /**
 409  * Schedule a new task to be run with a specified delay or when the
 410  * specified file descriptor is ready.  The delay can be
 411  * used as a timeout on the socket being ready.  The task will be
 412  * scheduled for execution once either the delay has expired or the
 413  * socket operation is ready.
 414  *
 415  * @param delay when should this operation time out?
 416  * @param priority priority of the task
 417  * @param fd file-descriptor
 418  * @param on_read whether to poll the file-descriptor for readability
 419  * @param on_write whether to poll the file-descriptor for writability
 420  * @param task main function of the task
 421  * @param task_cls closure of @a task
 422  * @return unique task identifier for the job
 423  *         only valid until "task" is started!
 424  */
 425 struct GNUNET_SCHEDULER_Task *
 426 GNUNET_SCHEDULER_add_net_with_priority  (struct GNUNET_TIME_Relative delay,
 427                                          enum GNUNET_SCHEDULER_Priority priority,
 428                                          struct GNUNET_NETWORK_Handle *fd,
 429                                          int on_read,
 430                                          int on_write,
 431                                          GNUNET_SCHEDULER_TaskCallback task,
 432                                          void *task_cls);
 433
 434 /**
 435  * Schedule a new task to be run with a specified delay or when the
 436  * specified file descriptor is ready for reading.  The delay can be
 437  * used as a timeout on the socket being ready.  The task will be
 438  * scheduled for execution once either the delay has expired or the
 439  * socket operation is ready. It will be run with the DEFAULT priority.
 440  *
 441  * * @param delay when should this operation time out?
 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 "task" is started!
 447  */
 448 struct GNUNET_SCHEDULER_Task *
 449 GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay,
 450                                 const struct GNUNET_DISK_FileHandle *rfd,
 451                                 GNUNET_SCHEDULER_TaskCallback task,
 452                                 void *task_cls);
 453
 454
 455 /**
 456  * Schedule a new task to be run with a specified delay or when the
 457  * specified file descriptor is ready for writing.  The delay can be
 458  * used as a timeout on the socket being ready.  The task will be
 459  * scheduled for execution once either the delay has expired or the
 460  * socket operation is ready. It will be run with the DEFAULT priority.
 461  *
 462  * * @param delay when should this operation time out?
 463  * @param wfd write file-descriptor
 464  * @param task main function of the task
 465  * @param task_cls closure of @a task
 466  * @return unique task identifier for the job
 467  *         only valid until @a task is started!
 468  */
 469 struct GNUNET_SCHEDULER_Task *
 470 GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay,
 471                                  const struct GNUNET_DISK_FileHandle *wfd,
 472                                  GNUNET_SCHEDULER_TaskCallback task,
 473                                  void *task_cls);
 474
 475
 476 /**
 477  * Schedule a new task to be run with a specified delay or when the
 478  * specified file descriptor is ready.  The delay can be
 479  * used as a timeout on the socket being ready.  The task will be
 480  * scheduled for execution once either the delay has expired or the
 481  * socket operation is ready.
 482  *
 483  * @param delay when should this operation time out?
 484  * @param priority priority of the task
 485  * @param fd file-descriptor
 486  * @param on_read whether to poll the file-descriptor for readability
 487  * @param on_write whether to poll the file-descriptor for writability
 488  * @param task main function of the task
 489  * @param task_cls closure of @a task
 490  * @return unique task identifier for the job
 491  *         only valid until @a task is started!
 492  */
 493 struct GNUNET_SCHEDULER_Task *
 494 GNUNET_SCHEDULER_add_file_with_priority (struct GNUNET_TIME_Relative delay,
 495                                          enum GNUNET_SCHEDULER_Priority priority,
 496                                          const struct GNUNET_DISK_FileHandle *fd,
 497                                          int on_read, int on_write,
 498                                          GNUNET_SCHEDULER_TaskCallback task,
 499                                          void *task_cls);
 500
 501
 502 /**
 503  * Schedule a new task to be run with a specified delay or when any of
 504  * the specified file descriptor sets is ready.  The delay can be used
 505  * as a timeout on the socket(s) being ready.  The task will be
 506  * scheduled for execution once either the delay has expired or any of
 507  * the socket operations is ready.  This is the most general
 508  * function of the "add" family.  Note that the "prerequisite_task"
 509  * must be satisfied in addition to any of the other conditions.  In
 510  * other words, the task will be started when
 511  * <code>
 512  * (prerequisite-run)
 513  * && (delay-ready
 514  *     || any-rs-ready
 515  *     || any-ws-ready)
 516  * </code>
 517  *
 518  * @param prio how important is this task?
 519  * @param delay how long should we wait?
 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 */