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