scheduler.h 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218
  1. /* * Copyright (c) 2017-2018, The Tor Project, Inc. */
  2. /* See LICENSE for licensing information */
  3. /**
  4. * \file scheduler.h
  5. * \brief Header file for scheduler*.c
  6. **/
  7. #ifndef TOR_SCHEDULER_H
  8. #define TOR_SCHEDULER_H
  9. #include "or/or.h"
  10. #include "or/channel.h"
  11. #include "lib/testsupport/testsupport.h"
  12. /** Scheduler type, we build an ordered list with those values from the
  13. * parsed strings in Schedulers. The reason to do such a thing is so we can
  14. * quickly and without parsing strings select the scheduler at anytime. */
  15. typedef enum {
  16. SCHEDULER_NONE = -1,
  17. SCHEDULER_VANILLA = 1,
  18. SCHEDULER_KIST = 2,
  19. SCHEDULER_KIST_LITE = 3,
  20. } scheduler_types_t;
  21. /**
  22. * A scheduler implementation is a collection of function pointers. If you
  23. * would like to add a new scheduler called foo, create scheduler_foo.c,
  24. * implement at least the mandatory ones, and implement get_foo_scheduler()
  25. * that returns a complete scheduler_t for your foo scheduler. See
  26. * scheduler_kist.c for an example.
  27. *
  28. * These function pointers SHOULD NOT be used anywhere outside of the
  29. * scheduling source files. The rest of Tor should communicate with the
  30. * scheduling system through the functions near the bottom of this file, and
  31. * those functions will call into the current scheduler implementation as
  32. * necessary.
  33. *
  34. * If your scheduler doesn't need to implement something (for example: it
  35. * doesn't create any state for itself, thus it has nothing to free when Tor
  36. * is shutting down), then set that function pointer to NULL.
  37. */
  38. typedef struct scheduler_s {
  39. /* Scheduler type. This is used for logging when the scheduler is switched
  40. * during runtime. */
  41. scheduler_types_t type;
  42. /* (Optional) To be called when we want to prepare a scheduler for use.
  43. * Perhaps Tor just started and we are the lucky chosen scheduler, or
  44. * perhaps Tor is switching to this scheduler. No matter the case, this is
  45. * where we would prepare any state and initialize parameters. You might
  46. * think of this as the opposite of free_all(). */
  47. void (*init)(void);
  48. /* (Optional) To be called when we want to tell the scheduler to delete all
  49. * of its state (if any). Perhaps Tor is shutting down or perhaps we are
  50. * switching schedulers. */
  51. void (*free_all)(void);
  52. /* (Mandatory) Libevent controls the main event loop in Tor, and this is
  53. * where we register with libevent the next execution of run_sched_ev [which
  54. * ultimately calls run()]. */
  55. void (*schedule)(void);
  56. /* (Mandatory) This is the heart of a scheduler! This is where the
  57. * excitement happens! Here libevent has given us the chance to execute, and
  58. * we should do whatever we need to do in order to move some cells from
  59. * their circuit queues to output buffers in an intelligent manner. We
  60. * should do this quickly. When we are done, we'll try to schedule() ourself
  61. * if more work needs to be done to setup the next scheduling run. */
  62. void (*run)(void);
  63. /*
  64. * External event not related to the scheduler but that can influence it.
  65. */
  66. /* (Optional) To be called whenever Tor finds out about a new consensus.
  67. * First the scheduling system as a whole will react to the new consensus
  68. * and change the scheduler if needed. After that, the current scheduler
  69. * (which might be new) will call this so it has the chance to react to the
  70. * new consensus too. If there's a consensus parameter that your scheduler
  71. * wants to keep an eye on, this is where you should check for it. */
  72. void (*on_new_consensus)(void);
  73. /* (Optional) To be called when a channel is being freed. Sometimes channels
  74. * go away (for example: the relay on the other end is shutting down). If
  75. * the scheduler keeps any channel-specific state and has memory to free
  76. * when channels go away, implement this and free it here. */
  77. void (*on_channel_free)(const channel_t *);
  78. /* (Optional) To be called whenever Tor is reloading configuration options.
  79. * For example: SIGHUP was issued and Tor is rereading its torrc. A
  80. * scheduler should use this as an opportunity to parse and cache torrc
  81. * options so that it doesn't have to call get_options() all the time. */
  82. void (*on_new_options)(void);
  83. } scheduler_t;
  84. /*****************************************************************************
  85. * Globally visible scheduler variables/values
  86. *
  87. * These are variables/constants that all of Tor should be able to see.
  88. *****************************************************************************/
  89. /* Default interval that KIST runs (in ms). */
  90. #define KIST_SCHED_RUN_INTERVAL_DEFAULT 10
  91. /* Minimum interval that KIST runs. This value disables KIST. */
  92. #define KIST_SCHED_RUN_INTERVAL_MIN 0
  93. /* Maximum interval that KIST runs (in ms). */
  94. #define KIST_SCHED_RUN_INTERVAL_MAX 100
  95. /*****************************************************************************
  96. * Globally visible scheduler functions
  97. *
  98. * These functions are how the rest of Tor communicates with the scheduling
  99. * system.
  100. *****************************************************************************/
  101. void scheduler_init(void);
  102. void scheduler_free_all(void);
  103. void scheduler_conf_changed(void);
  104. void scheduler_notify_networkstatus_changed(void);
  105. MOCK_DECL(void, scheduler_release_channel, (channel_t *chan));
  106. /*
  107. * Ways for a channel to interact with the scheduling system. A channel only
  108. * really knows (i) whether or not it has cells it wants to send, and
  109. * (ii) whether or not it would like to write.
  110. */
  111. void scheduler_channel_wants_writes(channel_t *chan);
  112. MOCK_DECL(void, scheduler_channel_doesnt_want_writes, (channel_t *chan));
  113. MOCK_DECL(void, scheduler_channel_has_waiting_cells, (channel_t *chan));
  114. /*****************************************************************************
  115. * Private scheduler functions
  116. *
  117. * These functions are only visible to the scheduling system, the current
  118. * scheduler implementation, and tests.
  119. *****************************************************************************/
  120. #ifdef SCHEDULER_PRIVATE_
  121. /*********************************
  122. * Defined in scheduler.c
  123. *********************************/
  124. void scheduler_set_channel_state(channel_t *chan, int new_state);
  125. const char *get_scheduler_state_string(int scheduler_state);
  126. /* Triggers a BUG() and extra information with chan if available. */
  127. #define SCHED_BUG(cond, chan) \
  128. (PREDICT_UNLIKELY(cond) ? \
  129. ((BUG(cond)) ? (scheduler_bug_occurred(chan), 1) : 0) : 0)
  130. void scheduler_bug_occurred(const channel_t *chan);
  131. smartlist_t *get_channels_pending(void);
  132. MOCK_DECL(int, scheduler_compare_channels,
  133. (const void *c1_v, const void *c2_v));
  134. void scheduler_ev_active(void);
  135. void scheduler_ev_add(const struct timeval *next_run);
  136. #ifdef TOR_UNIT_TESTS
  137. extern smartlist_t *channels_pending;
  138. extern struct mainloop_event_t *run_sched_ev;
  139. extern const scheduler_t *the_scheduler;
  140. void scheduler_touch_channel(channel_t *chan);
  141. #endif /* defined(TOR_UNIT_TESTS) */
  142. /*********************************
  143. * Defined in scheduler_kist.c
  144. *********************************/
  145. #ifdef SCHEDULER_KIST_PRIVATE
  146. /* Socket table entry which holds information of a channel's socket and kernel
  147. * TCP information. Only used by KIST. */
  148. typedef struct socket_table_ent_s {
  149. HT_ENTRY(socket_table_ent_s) node;
  150. const channel_t *chan;
  151. /* Amount written this scheduling run */
  152. uint64_t written;
  153. /* Amount that can be written this scheduling run */
  154. uint64_t limit;
  155. /* TCP info from the kernel */
  156. uint32_t cwnd;
  157. uint32_t unacked;
  158. uint32_t mss;
  159. uint32_t notsent;
  160. } socket_table_ent_t;
  161. typedef HT_HEAD(outbuf_table_s, outbuf_table_ent_s) outbuf_table_t;
  162. MOCK_DECL(int, channel_should_write_to_kernel,
  163. (outbuf_table_t *table, channel_t *chan));
  164. MOCK_DECL(void, channel_write_to_kernel, (channel_t *chan));
  165. MOCK_DECL(void, update_socket_info_impl, (socket_table_ent_t *ent));
  166. int scheduler_can_use_kist(void);
  167. void scheduler_kist_set_full_mode(void);
  168. void scheduler_kist_set_lite_mode(void);
  169. scheduler_t *get_kist_scheduler(void);
  170. int kist_scheduler_run_interval(void);
  171. #ifdef TOR_UNIT_TESTS
  172. extern int32_t sched_run_interval;
  173. #endif /* TOR_UNIT_TESTS */
  174. #endif /* defined(SCHEDULER_KIST_PRIVATE) */
  175. /*********************************
  176. * Defined in scheduler_vanilla.c
  177. *********************************/
  178. scheduler_t *get_vanilla_scheduler(void);
  179. #endif /* defined(SCHEDULER_PRIVATE_) */
  180. #endif /* !defined(TOR_SCHEDULER_H) */