ahf/nickm_event.txt

## nickm_event.txt
Where the timed events are

After tor starts, it never leaves run_main_loop_until_done() in main.c until it is ready to stop.  That function just calls run_main_loop_once() over and over.

run_main_loop_until_done() calls scheduled events in a few different ways.

* Some events are run once every time the main loop is visited; see connection_ap_attach_pending() for one example.  These are generally things that need to happen right away in response to any events, or once per second at the slowest.

* Some events are created as libevent timed events.  These are ones that are added when event_add()'s second argument is non-NULL.

* Some events are created with periodic timers, from compat_libevent.c.  These are implemented internally as libevent timed events.  Look for periodic_timer_new() to find these.
  * One important periodic event is second_timer, which runs second_elapsed_timeout(), which in turn runs run_scheduled_events().  These functions call many other things that are invoked once a second.

* Some events are run at adaptable schedules, from periodic.c.  These are all installed in main.c, and are listed in the table called periodic_events[].  These are easy to confuse with the periodic timers above.  They are also based on libevent events.

* Some events are lightweight countdown events that are implemented using a high-performance hierarchical timing wheel backend.  These are implemented in timers.c.  They prefer to use monotonic time and do not correspond 1:1 to the libevent timer backend.  Right now, only channel padding uses these.

* Some timed events are invoked when a frequently called function checks a timeout and notices it has expired.  For an example, have a look at time_to_expire_and_reset in circuit_expire_old_circuits_as_needed().  This is not a very good pattern. "git grep 'static time_t'" will find a bunch of these.
	Where the timed events are

	After tor starts, it never leaves run_main_loop_until_done() in main.c until it is ready to stop. That function just calls run_main_loop_once() over and over.

	run_main_loop_until_done() calls scheduled events in a few different ways.

	* Some events are run once every time the main loop is visited; see connection_ap_attach_pending() for one example. These are generally things that need to happen right away in response to any events, or once per second at the slowest.

	* Some events are created as libevent timed events. These are ones that are added when event_add()'s second argument is non-NULL.

	* Some events are created with periodic timers, from compat_libevent.c. These are implemented internally as libevent timed events. Look for periodic_timer_new() to find these.
	* One important periodic event is second_timer, which runs second_elapsed_timeout(), which in turn runs run_scheduled_events(). These functions call many other things that are invoked once a second.

	* Some events are run at adaptable schedules, from periodic.c. These are all installed in main.c, and are listed in the table called periodic_events[]. These are easy to confuse with the periodic timers above. They are also based on libevent events.

	* Some events are lightweight countdown events that are implemented using a high-performance hierarchical timing wheel backend. These are implemented in timers.c. They prefer to use monotonic time and do not correspond 1:1 to the libevent timer backend. Right now, only channel padding uses these.

	* Some timed events are invoked when a frequently called function checks a timeout and notices it has expired. For an example, have a look at time_to_expire_and_reset in circuit_expire_old_circuits_as_needed(). This is not a very good pattern. "git grep 'static time_t'" will find a bunch of these.