From e2064401d33c24e6a2fa07f6d1c52b76ca34bff3 Mon Sep 17 00:00:00 2001 From: Donald Sharp Date: Wed, 18 Jan 2017 19:04:40 -0500 Subject: lib: Add some documentation to wheel.h Add some hopefully useful documentation to the timer wheel.h code. Signed-off-by: Donald Sharp --- lib/wheel.h | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) (limited to 'lib/wheel.h') diff --git a/lib/wheel.h b/lib/wheel.h index ddb79988b..79d21e124 100644 --- a/lib/wheel.h +++ b/lib/wheel.h @@ -40,9 +40,49 @@ struct timer_wheel void (*slot_run) (void *); }; +/* + * Creates a timer wheel + * + * master - Thread master structure for the process + * period - The Time in seconds that the timer wheel will + * take before it starts issuing commands again + * for items in each slot + * slots - The number of slots to have in this particular + * timer wheel + * slot_key - A hashing function of some sort that will allow + * the timer wheel to put items into individual slots + * slot_run - The function to run over each item in a particular slot + * + * Creates a timer wheel that will wake up 'slots' times over the entire + * wheel. Each time the timer wheel wakes up it will iterate through + * and run the slot_run function for each item stored in that particular + * slot. + * + * The timer code is 'intelligent' in that it notices if anything is + * in a particular slot and can schedule the next timer to skip + * the empty slot. + * + * The general purpose of a timer wheel is to reduce events in a system. + * A perfect example of usage for this is say hello packets that need + * to be sent out to all your neighbors. Suppose a large routing protocol + * has to send keepalive packets every Y seconds to each of it's peers. + * At scale we can have a very large number of peers, X. + * This means that we will have X timing events every Y seconds. + * If you replace these events with a timer wheel that has Z slots + * you will have at most Y/Z timer events if each slot has a work item + * in it. + * + * When X is large the number of events in a system can quickly escalate + * and cause significant amount of time handling thread events instead + * of running your code. + */ struct timer_wheel *wheel_init (struct thread_master *master, int period, size_t slots, unsigned int (*slot_key) (void *), void (*slot_run) (void *)); + +/* + * Delete the specified timer wheel created + */ void wheel_delete (struct timer_wheel *); /* @@ -51,17 +91,25 @@ void wheel_delete (struct timer_wheel *); int wheel_stop (struct timer_wheel *wheel); /* - * Start the wheel from running again + * Start the wheel running again */ int wheel_start (struct timer_wheel *wheel); /* + * wheel - The Timer wheel being modified + * item - The generic data structure that will be handed + * to the slot_run function. + * * Add item to a slot setup by the slot_key, * possibly change next time pop. */ int wheel_add_item (struct timer_wheel *wheel, void *item); /* + * wheel - The Timer wheel being modified. + * item - The item to remove from one of the slots in + * the timer wheel. + * * Remove a item to a slot setup by the slot_key, * possibly change next time pop. */ -- cgit v1.2.3