proxmox-mirrors/mirror_frr
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_frr synced 2025-10-31 09:04:27 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

lib: Add some documentation to wheel.h

Browse Source 
Add some hopefully useful documentation to the
timer wheel.h code.

Signed-off-by: Donald Sharp <sharpd@cumulusnetworks.com>
This commit is contained in:
Donald Sharp 2017-01-18 19:04:40 -05:00
parent 9bf7536273
commit e2064401d3
1 changed files with 49 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
lib/wheel.h
View File

@ -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.
*/