src/core/mainloop/periodic.h

   1 /* Copyright (c) 2015-2021, The Tor Project, Inc. */
   2 /* See LICENSE for licensing information */
   3
   4 /**
   5  * @file periodic.h
   6  * @brief Header for periodic.c
   7  **/
   8
   9 #ifndef TOR_PERIODIC_H
  10 #define TOR_PERIODIC_H
  11
  12 #define PERIODIC_EVENT_NO_UPDATE (-1)
  13
  14 /* Tor roles for which a periodic event item is for. An event can be for
  15  * multiple roles, they can be combined. */
  16 #define PERIODIC_EVENT_ROLE_CLIENT      (1U << 0)
  17 #define PERIODIC_EVENT_ROLE_RELAY       (1U << 1)
  18 #define PERIODIC_EVENT_ROLE_BRIDGE      (1U << 2)
  19 #define PERIODIC_EVENT_ROLE_DIRAUTH     (1U << 3)
  20 #define PERIODIC_EVENT_ROLE_BRIDGEAUTH  (1U << 4)
  21 #define PERIODIC_EVENT_ROLE_HS_SERVICE  (1U << 5)
  22 #define PERIODIC_EVENT_ROLE_DIRSERVER   (1U << 6)
  23 #define PERIODIC_EVENT_ROLE_CONTROLEV   (1U << 7)
  24
  25 #define PERIODIC_EVENT_ROLE_NET_PARTICIPANT (1U << 8)
  26 #define PERIODIC_EVENT_ROLE_ALL         (1U << 9)
  27
  28 /* Helper macro to make it a bit less annoying to defined groups of roles that
  29  * are often used. */
  30
  31 /* Router that is a Bridge or Relay. */
  32 #define PERIODIC_EVENT_ROLE_ROUTER \
  33   (PERIODIC_EVENT_ROLE_BRIDGE | PERIODIC_EVENT_ROLE_RELAY)
  34 /* Authorities that is both bridge and directory. */
  35 #define PERIODIC_EVENT_ROLE_AUTHORITIES \
  36   (PERIODIC_EVENT_ROLE_BRIDGEAUTH | PERIODIC_EVENT_ROLE_DIRAUTH)
  37
  38 /*
  39  * Event flags which can change the behavior of an event.
  40  */
  41
  42 /* Indicate that the event needs the network meaning that if we are in
  43  * DisableNetwork or hibernation mode, the event won't be enabled. This obey
  44  * the net_is_disabled() check. */
  45 #define PERIODIC_EVENT_FLAG_NEED_NET  (1U << 0)
  46
  47 /* Indicate that if the event is enabled, it needs to be run once before
  48  * it becomes disabled.
  49  */
  50 #define PERIODIC_EVENT_FLAG_RUN_ON_DISABLE  (1U << 1)
  51
  52 /** Callback function for a periodic event to take action.  The return value
  53 * influences the next time the function will get called.  Return
  54 * PERIODIC_EVENT_NO_UPDATE to not update <b>last_action_time</b> and be polled
  55 * again in the next second. If a positive value is returned it will update the
  56 * interval time. */
  57 typedef int (*periodic_event_helper_t)(time_t now,
  58                                       const or_options_t *options);
  59
  60 struct mainloop_event_t;
  61
  62 /** A single item for the periodic-events-function table. */
  63 typedef struct periodic_event_item_t {
  64   periodic_event_helper_t fn; /**< The function to run the event */
  65   time_t last_action_time; /**< The last time the function did something */
  66   struct mainloop_event_t *ev; /**< Libevent callback we're using to implement
  67                                 * this */
  68   const char *name; /**< Name of the function -- for debug */
  69
  70   /* Bitmask of roles define above for which this event applies. */
  71   uint32_t roles;
  72   /* Bitmask of flags which can change the behavior of the event. */
  73   uint32_t flags;
  74   /* Indicate that this event has been enabled that is scheduled. */
  75   unsigned int enabled : 1;
  76 } periodic_event_item_t;
  77
  78 /** events will get their interval from first execution */
  79 #ifndef COCCI
  80 #define PERIODIC_EVENT(fn, r, f) { fn##_callback, 0, NULL, #fn, r, f, 0 }
  81 #define END_OF_PERIODIC_EVENTS { NULL, 0, NULL, NULL, 0, 0, 0 }
  82 #endif
  83
  84 /* Return true iff the given event was setup before thus is enabled to be
  85  * scheduled. */
  86 static inline int
  87 periodic_event_is_enabled(const periodic_event_item_t *item)
  88 {
  89   return item->enabled;
  90 }
  91
  92 void periodic_event_launch(periodic_event_item_t *event);
  93 void periodic_event_connect(periodic_event_item_t *event);
  94 //void periodic_event_disconnect(periodic_event_item_t *event);
  95 void periodic_event_reschedule(periodic_event_item_t *event);
  96 void periodic_event_enable(periodic_event_item_t *event);
  97 void periodic_event_disable(periodic_event_item_t *event);
  98 void periodic_event_schedule_and_disable(periodic_event_item_t *event);
  99
 100 void periodic_events_register(periodic_event_item_t *item);
 101 void periodic_events_connect_all(void);
 102 void periodic_events_reset_all(void);
 103 periodic_event_item_t *periodic_events_find(const char *name);
 104 void periodic_events_rescan_by_roles(int roles, bool net_disabled);
 105 void periodic_events_disconnect_all(void);
 106
 107 int safe_timer_diff(time_t now, time_t next);
 108
 109 #endif /* !defined(TOR_PERIODIC_H) */