tor  0.4.2.0-alpha-dev
scheduler.c
Go to the documentation of this file.
1 /* Copyright (c) 2013-2019, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
3 
4 #include "core/or/or.h"
5 #include "app/config/config.h"
6 
8 #define SCHEDULER_PRIVATE_
9 #define SCHEDULER_KIST_PRIVATE
10 #include "core/or/scheduler.h"
11 #include "core/mainloop/mainloop.h"
12 #include "lib/buf/buffers.h"
13 #define TOR_CHANNEL_INTERNAL_
14 #include "core/or/channeltls.h"
16 
17 #include "core/or/or_connection_st.h"
18 
150 /*****************************************************************************
151  * Scheduling system state
152  *
153  * State that can be accessed from any scheduler implementation (but not
154  * outside the scheduling system)
155  *****************************************************************************/
156 
159 
168 
173 STATIC struct mainloop_event_t *run_sched_ev = NULL;
174 
175 static int have_logged_kist_suddenly_disabled = 0;
176 
177 /*****************************************************************************
178  * Scheduling system static function definitions
179  *
180  * Functions that can only be accessed from this file.
181  *****************************************************************************/
182 
184 static const char *
186 {
187  switch (type) {
188  case SCHEDULER_VANILLA:
189  return "Vanilla";
190  case SCHEDULER_KIST:
191  return "KIST";
192  case SCHEDULER_KIST_LITE:
193  return "KISTLite";
194  case SCHEDULER_NONE:
195  /* fallthrough */
196  default:
197  tor_assert_unreached();
198  return "(N/A)";
199  }
200 }
201 
206 static void
208 {
209  (void) event;
210  (void) arg;
211 
212  log_debug(LD_SCHED, "Scheduler event callback called");
213 
214  /* Run the scheduler. This is a mandatory function. */
215 
216  /* We might as well assert on this. If this function doesn't exist, no cells
217  * are getting scheduled. Things are very broken. scheduler_t says the run()
218  * function is mandatory. */
220  the_scheduler->run();
221 
222  /* Schedule itself back in if it has more work. */
223 
224  /* Again, might as well assert on this mandatory scheduler_t function. If it
225  * doesn't exist, there's no way to tell libevent to run the scheduler again
226  * in the future. */
227  tor_assert(the_scheduler->schedule);
228  the_scheduler->schedule();
229 }
230 
232 static void
234 {
235  scheduler_t *new_scheduler = NULL;
236 
237 #ifdef TOR_UNIT_TESTS
238  /* This is hella annoying to set in the options for every test that passes
239  * through the scheduler and there are many so if we don't explicitly have
240  * a list of types set, just put the vanilla one. */
241  if (get_options()->SchedulerTypes_ == NULL) {
242  the_scheduler = get_vanilla_scheduler();
243  return;
244  }
245 #endif /* defined(TOR_UNIT_TESTS) */
246 
247  /* This list is ordered that is first entry has the first priority. Thus, as
248  * soon as we find a scheduler type that we can use, we use it and stop. */
249  SMARTLIST_FOREACH_BEGIN(get_options()->SchedulerTypes_, int *, type) {
250  switch (*type) {
251  case SCHEDULER_VANILLA:
252  new_scheduler = get_vanilla_scheduler();
253  goto end;
254  case SCHEDULER_KIST:
255  if (!scheduler_can_use_kist()) {
256 #ifdef HAVE_KIST_SUPPORT
257  if (!have_logged_kist_suddenly_disabled) {
258  /* We should only log this once in most cases. If it was the kernel
259  * losing support for kist that caused scheduler_can_use_kist() to
260  * return false, then this flag makes sure we only log this message
261  * once. If it was the consensus that switched from "yes use kist"
262  * to "no don't use kist", then we still set the flag so we log
263  * once, but we unset the flag elsewhere if we ever can_use_kist()
264  * again.
265  */
266  have_logged_kist_suddenly_disabled = 1;
267  log_notice(LD_SCHED, "Scheduler type KIST has been disabled by "
268  "the consensus or no kernel support.");
269  }
270 #else /* !(defined(HAVE_KIST_SUPPORT)) */
271  log_info(LD_SCHED, "Scheduler type KIST not built in");
272 #endif /* defined(HAVE_KIST_SUPPORT) */
273  continue;
274  }
275  /* This flag will only get set in one of two cases:
276  * 1 - the kernel lost support for kist. In that case, we don't expect to
277  * ever end up here
278  * 2 - the consensus went from "yes use kist" to "no don't use kist".
279  * We might end up here if the consensus changes back to "yes", in which
280  * case we might want to warn the user again if it goes back to "no"
281  * yet again. Thus we unset the flag */
282  have_logged_kist_suddenly_disabled = 0;
283  new_scheduler = get_kist_scheduler();
284  scheduler_kist_set_full_mode();
285  goto end;
286  case SCHEDULER_KIST_LITE:
287  new_scheduler = get_kist_scheduler();
288  scheduler_kist_set_lite_mode();
289  goto end;
290  case SCHEDULER_NONE:
291  /* fallthrough */
292  default:
293  /* Our option validation should have caught this. */
294  tor_assert_unreached();
295  }
296  } SMARTLIST_FOREACH_END(type);
297 
298  end:
299  if (new_scheduler == NULL) {
300  log_err(LD_SCHED, "Tor was unable to select a scheduler type. Please "
301  "make sure Schedulers is correctly configured with "
302  "what Tor does support.");
303  /* We weren't able to choose a scheduler which means that none of the ones
304  * set in Schedulers are supported or usable. We will respect the user
305  * wishes of using what it has been configured and don't do a sneaky
306  * fallback. Because this can be changed at runtime, we have to stop tor
307  * right now. */
308  exit(1); // XXXX bad exit
309  }
310 
311  /* Set the chosen scheduler. */
312  the_scheduler = new_scheduler;
313 }
314 
320 static void
322 {
323  const scheduler_t *old_scheduler = the_scheduler;
324  scheduler_types_t old_scheduler_type = SCHEDULER_NONE;
325 
326  /* We keep track of the type in order to log only if the type switched. We
327  * can't just use the scheduler pointers because KIST and KISTLite share the
328  * same object. */
329  if (the_scheduler) {
330  old_scheduler_type = the_scheduler->type;
331  }
332 
333  /* From the options, select the scheduler type to set. */
336 
337  /* We look at the pointer difference in case the old sched and new sched
338  * share the same scheduler object, as is the case with KIST and KISTLite. */
339  if (old_scheduler != the_scheduler) {
340  /* Allow the old scheduler to clean up, if needed. */
341  if (old_scheduler && old_scheduler->free_all) {
342  old_scheduler->free_all();
343  }
344 
345  /* Initialize the new scheduler. */
346  if (the_scheduler->init) {
347  the_scheduler->init();
348  }
349  }
350 
351  /* Finally we notice log if we switched schedulers. We use the type in case
352  * two schedulers share a scheduler object. */
353  if (old_scheduler_type != the_scheduler->type) {
354  log_info(LD_CONFIG, "Scheduler type %s has been enabled.",
356  }
357 }
358 
359 /*****************************************************************************
360  * Scheduling system private function definitions
361  *
362  * Functions that can only be accessed from scheduler*.c
363  *****************************************************************************/
364 
366 const char *
367 get_scheduler_state_string(int scheduler_state)
368 {
369  switch (scheduler_state) {
370  case SCHED_CHAN_IDLE:
371  return "IDLE";
372  case SCHED_CHAN_WAITING_FOR_CELLS:
373  return "WAITING_FOR_CELLS";
374  case SCHED_CHAN_WAITING_TO_WRITE:
375  return "WAITING_TO_WRITE";
376  case SCHED_CHAN_PENDING:
377  return "PENDING";
378  default:
379  return "(invalid)";
380  }
381 }
382 
385 void
387 {
388  log_debug(LD_SCHED, "chan %" PRIu64 " changed from scheduler state %s to %s",
389  chan->global_identifier,
391  get_scheduler_state_string(new_state));
392  chan->scheduler_state = new_state;
393 }
394 
396 smartlist_t *
398 {
399  return channels_pending;
400 }
401 
404 scheduler_compare_channels, (const void *c1_v, const void *c2_v))
405 {
406  const channel_t *c1 = NULL, *c2 = NULL;
407  /* These are a workaround for -Wbad-function-cast throwing a fit */
408  const circuitmux_policy_t *p1, *p2;
409  uintptr_t p1_i, p2_i;
410 
411  tor_assert(c1_v);
412  tor_assert(c2_v);
413 
414  c1 = (const channel_t *)(c1_v);
415  c2 = (const channel_t *)(c2_v);
416 
417  if (c1 != c2) {
418  if (circuitmux_get_policy(c1->cmux) ==
419  circuitmux_get_policy(c2->cmux)) {
420  /* Same cmux policy, so use the mux comparison */
421  return circuitmux_compare_muxes(c1->cmux, c2->cmux);
422  } else {
423  /*
424  * Different policies; not important to get this edge case perfect
425  * because the current code never actually gives different channels
426  * different cmux policies anyway. Just use this arbitrary but
427  * definite choice.
428  */
429  p1 = circuitmux_get_policy(c1->cmux);
430  p2 = circuitmux_get_policy(c2->cmux);
431  p1_i = (uintptr_t)p1;
432  p2_i = (uintptr_t)p2;
433 
434  return (p1_i < p2_i) ? -1 : 1;
435  }
436  } else {
437  /* c1 == c2, so always equal */
438  return 0;
439  }
440 }
441 
442 /*****************************************************************************
443  * Scheduling system global functions
444  *
445  * Functions that can be accessed from anywhere in Tor.
446  *****************************************************************************/
447 
452 void
454 {
455  /* Let the scheduler decide what it should do. */
456  set_scheduler();
457 
458  /* Then tell the (possibly new) scheduler that we have new options. */
459  if (the_scheduler->on_new_options) {
460  the_scheduler->on_new_options();
461  }
462 }
463 
467 void
469 {
470  /* Maybe the consensus param made us change the scheduler. */
471  set_scheduler();
472 
473  /* Then tell the (possibly new) scheduler that we have a new consensus */
474  if (the_scheduler->on_new_consensus) {
475  the_scheduler->on_new_consensus();
476  }
477 }
478 
484 void
486 {
487  log_debug(LD_SCHED, "Shutting down scheduler");
488 
489  if (run_sched_ev) {
490  mainloop_event_free(run_sched_ev);
491  run_sched_ev = NULL;
492  }
493 
494  if (channels_pending) {
495  /* We don't have ownership of the objects in this list. */
496  smartlist_free(channels_pending);
497  channels_pending = NULL;
498  }
499 
500  if (the_scheduler && the_scheduler->free_all) {
501  the_scheduler->free_all();
502  }
503  the_scheduler = NULL;
504 }
505 
508 scheduler_channel_doesnt_want_writes,(channel_t *chan))
509 {
510  IF_BUG_ONCE(!chan) {
511  return;
512  }
514  return;
515  }
516 
517  /* If it's already in pending, we can put it in waiting_to_write */
518  if (chan->scheduler_state == SCHED_CHAN_PENDING) {
519  /*
520  * It's in channels_pending, so it shouldn't be in any of
521  * the other lists. It can't write any more, so it goes to
522  * channels_waiting_to_write.
523  */
525  scheduler_compare_channels,
526  offsetof(channel_t, sched_heap_idx),
527  chan);
528  scheduler_set_channel_state(chan, SCHED_CHAN_WAITING_TO_WRITE);
529  } else {
530  /*
531  * It's not in pending, so it can't become waiting_to_write; it's
532  * either not in any of the lists (nothing to do) or it's already in
533  * waiting_for_cells (remove it, can't write any more).
534  */
535  if (chan->scheduler_state == SCHED_CHAN_WAITING_FOR_CELLS) {
536  scheduler_set_channel_state(chan, SCHED_CHAN_IDLE);
537  }
538  }
539 }
540 
543 scheduler_channel_has_waiting_cells,(channel_t *chan))
544 {
545  IF_BUG_ONCE(!chan) {
546  return;
547  }
549  return;
550  }
551 
552  /* First, check if it's also writeable */
553  if (chan->scheduler_state == SCHED_CHAN_WAITING_FOR_CELLS) {
554  /*
555  * It's in channels_waiting_for_cells, so it shouldn't be in any of
556  * the other lists. It has waiting cells now, so it goes to
557  * channels_pending.
558  */
559  scheduler_set_channel_state(chan, SCHED_CHAN_PENDING);
560  if (!SCHED_BUG(chan->sched_heap_idx != -1, chan)) {
562  scheduler_compare_channels,
563  offsetof(channel_t, sched_heap_idx),
564  chan);
565  }
566  /* If we made a channel pending, we potentially have scheduling work to
567  * do. */
568  the_scheduler->schedule();
569  } else {
570  /*
571  * It's not in waiting_for_cells, so it can't become pending; it's
572  * either not in any of the lists (we add it to waiting_to_write)
573  * or it's already in waiting_to_write or pending (we do nothing)
574  */
575  if (!(chan->scheduler_state == SCHED_CHAN_WAITING_TO_WRITE ||
576  chan->scheduler_state == SCHED_CHAN_PENDING)) {
577  scheduler_set_channel_state(chan, SCHED_CHAN_WAITING_TO_WRITE);
578  }
579  }
580 }
581 
584 void
585 scheduler_ev_add(const struct timeval *next_run)
586 {
588  tor_assert(next_run);
589  if (BUG(mainloop_event_schedule(run_sched_ev, next_run) < 0)) {
590  log_warn(LD_SCHED, "Adding to libevent failed. Next run time was set to: "
591  "%ld.%06ld", next_run->tv_sec, (long)next_run->tv_usec);
592  return;
593  }
594 }
595 
597 void
599 {
602 }
603 
604 /*
605  * Initialize everything scheduling-related from config.c. Note this is only
606  * called when Tor is starting up, while scheduler_t->init() is called both
607  * when Tor is starting up and when we are switching schedulers.
608  */
609 void
610 scheduler_init(void)
611 {
612  log_debug(LD_SCHED, "Initting scheduler");
613 
614  // Two '!' because we really do want to check if the pointer is non-NULL
616  log_warn(LD_SCHED, "We should not already have a libevent scheduler event."
617  "I'll clean the old one up, but this is odd.");
618  mainloop_event_free(run_sched_ev);
619  run_sched_ev = NULL;
620  }
622  channels_pending = smartlist_new();
623 
624  set_scheduler();
625 }
626 
627 /*
628  * If a channel is going away, this is how the scheduling system is informed
629  * so it can do any freeing necessary. This ultimately calls
630  * scheduler_t->on_channel_free() so the current scheduler can release any
631  * state specific to this channel.
632  */
633 MOCK_IMPL(void,
634 scheduler_release_channel,(channel_t *chan))
635 {
636  IF_BUG_ONCE(!chan) {
637  return;
638  }
640  return;
641  }
642 
643  /* Try to remove the channel from the pending list regardless of its
644  * scheduler state. We can release a channel in many places in the tor code
645  * so we can't rely on the channel state (PENDING) to remove it from the
646  * list.
647  *
648  * For instance, the channel can change state from OPEN to CLOSING while
649  * being handled in the scheduler loop leading to the channel being in
650  * PENDING state but not in the pending list. Furthermore, we release the
651  * channel when it changes state to close and a second time when we free it.
652  * Not ideal at all but for now that is the way it is. */
653  if (chan->sched_heap_idx != -1) {
655  scheduler_compare_channels,
656  offsetof(channel_t, sched_heap_idx),
657  chan);
658  }
659 
660  if (the_scheduler->on_channel_free) {
661  the_scheduler->on_channel_free(chan);
662  }
663  scheduler_set_channel_state(chan, SCHED_CHAN_IDLE);
664 }
665 
668 void
670 {
671  IF_BUG_ONCE(!chan) {
672  return;
673  }
675  return;
676  }
677 
678  /* If it's already in waiting_to_write, we can put it in pending */
679  if (chan->scheduler_state == SCHED_CHAN_WAITING_TO_WRITE) {
680  /*
681  * It can write now, so it goes to channels_pending.
682  */
683  scheduler_set_channel_state(chan, SCHED_CHAN_PENDING);
684  if (!SCHED_BUG(chan->sched_heap_idx != -1, chan)) {
686  scheduler_compare_channels,
687  offsetof(channel_t, sched_heap_idx),
688  chan);
689  }
690  /* We just made a channel pending, we have scheduling work to do. */
691  the_scheduler->schedule();
692  } else {
693  /*
694  * It's not in SCHED_CHAN_WAITING_TO_WRITE, so it can't become pending;
695  * it's either idle and goes to WAITING_FOR_CELLS, or it's a no-op.
696  */
697  if (!(chan->scheduler_state == SCHED_CHAN_WAITING_FOR_CELLS ||
698  chan->scheduler_state == SCHED_CHAN_PENDING)) {
699  scheduler_set_channel_state(chan, SCHED_CHAN_WAITING_FOR_CELLS);
700  }
701  }
702 }
703 
704 /* Log warn the given channel and extra scheduler context as well. This is
705  * used by SCHED_BUG() in order to be able to extract as much information as
706  * we can when we hit a bug. Channel chan can be NULL. */
707 void
708 scheduler_bug_occurred(const channel_t *chan)
709 {
710  char buf[128];
711 
712  if (chan != NULL) {
713  const size_t outbuf_len =
714  buf_datalen(TO_CONN(BASE_CHAN_TO_TLS((channel_t *) chan)->conn)->outbuf);
715  tor_snprintf(buf, sizeof(buf),
716  "Channel %" PRIu64 " in state %s and scheduler state %s."
717  " Num cells on cmux: %d. Connection outbuf len: %lu.",
718  chan->global_identifier,
721  circuitmux_num_cells(chan->cmux),
722  (unsigned long)outbuf_len);
723  }
724 
725  {
726  char *msg;
727  /* Rate limit every 60 seconds. If we start seeing this every 60 sec, we
728  * know something is stuck/wrong. It *should* be loud but not too much. */
729  static ratelim_t rlimit = RATELIM_INIT(60);
730  if ((msg = rate_limit_log(&rlimit, approx_time()))) {
731  log_warn(LD_BUG, "%s Num pending channels: %d. "
732  "Channel in pending list: %s.%s",
733  (chan != NULL) ? buf : "No channel in bug context.",
734  smartlist_len(channels_pending),
735  (smartlist_pos(channels_pending, chan) == -1) ? "no" : "yes",
736  msg);
737  tor_free(msg);
738  }
739  }
740 }
741 
742 #ifdef TOR_UNIT_TESTS
743 
744 /*
745  * Notify scheduler that a channel's queue position may have changed.
746  */
747 void
748 scheduler_touch_channel(channel_t *chan)
749 {
750  IF_BUG_ONCE(!chan) {
751  return;
752  }
753 
754  if (chan->scheduler_state == SCHED_CHAN_PENDING) {
755  /* Remove and re-add it */
757  scheduler_compare_channels,
758  offsetof(channel_t, sched_heap_idx),
759  chan);
761  scheduler_compare_channels,
762  offsetof(channel_t, sched_heap_idx),
763  chan);
764  }
765  /* else no-op, since it isn't in the queue */
766 }
767 
768 #endif /* defined(TOR_UNIT_TESTS) */
#define LD_SCHED
Definition: log.h:105
channel_state_t state
Definition: channel.h:192
STATIC const scheduler_t * the_scheduler
Definition: scheduler.c:158
Header file for channeltls.c.
const char * get_scheduler_state_string(int scheduler_state)
Definition: scheduler.c:367
#define SMARTLIST_FOREACH_BEGIN(sl, type, var)
#define TO_CONN(c)
Definition: or.h:735
STATIC smartlist_t * channels_pending
Definition: scheduler.c:167
void scheduler_conf_changed(void)
Definition: scheduler.c:453
void scheduler_notify_networkstatus_changed(void)
Definition: scheduler.c:468
scheduler_types_t
Definition: scheduler.h:19
smartlist_t * get_channels_pending(void)
Definition: scheduler.c:397
char * rate_limit_log(ratelim_t *lim, time_t now)
Definition: ratelim.c:41
void smartlist_pqueue_add(smartlist_t *sl, int(*compare)(const void *a, const void *b), int idx_field_offset, void *item)
Definition: smartlist.c:726
Header file for config.c.
void scheduler_ev_active(void)
Definition: scheduler.c:598
const char * channel_state_to_string(channel_state_t state)
Definition: channel.c:315
#define tor_free(p)
Definition: malloc.h:52
Header file for mainloop.c.
void mainloop_event_activate(mainloop_event_t *event)
circuitmux_t * cmux
Definition: channel.h:403
STATIC struct mainloop_event_t * run_sched_ev
Definition: scheduler.c:173
Header file for scheduler*.c.
int sched_heap_idx
Definition: channel.h:292
static void set_scheduler(void)
Definition: scheduler.c:321
tor_assert(buffer)
static void select_scheduler(void)
Definition: scheduler.c:233
void scheduler_free_all(void)
Definition: scheduler.c:485
MOCK_IMPL(int, scheduler_compare_channels,(const void *c1_v, const void *c2_v))
Definition: scheduler.c:403
Master header file for Tor-specific functionality.
int smartlist_pos(const smartlist_t *sl, const void *element)
Definition: smartlist.c:119
int tor_snprintf(char *str, size_t size, const char *format,...)
Definition: printf.c:27
#define IF_BUG_ONCE(cond)
Definition: util_bug.h:234
static const char * get_scheduler_type_string(scheduler_types_t type)
Definition: scheduler.c:185
mainloop_event_t * mainloop_event_new(void(*cb)(mainloop_event_t *, void *), void *userdata)
void scheduler_ev_add(const struct timeval *next_run)
Definition: scheduler.c:585
static void scheduler_evt_callback(mainloop_event_t *event, void *arg)
Definition: scheduler.c:207
time_t approx_time(void)
Definition: approx_time.c:32
void scheduler_channel_wants_writes(channel_t *chan)
Definition: scheduler.c:669
Header file for buffers.c.
int mainloop_event_schedule(mainloop_event_t *event, const struct timeval *tv)
void scheduler_set_channel_state(channel_t *chan, int new_state)
Definition: scheduler.c:386
Header for compat_libevent.c.
enum channel_s::@10 scheduler_state
void smartlist_pqueue_remove(smartlist_t *sl, int(*compare)(const void *a, const void *b), int idx_field_offset, void *item)
Definition: smartlist.c:779
#define LD_BUG
Definition: log.h:84
#define LD_CONFIG
Definition: log.h:66
uint64_t global_identifier
Definition: channel.h:197