INTRO (9) NetBSD Kernel Developer's Manual INTRO (9) NAME ...

CALLOUT (9) NetBSD Kernel Developer’s Manual CALLOUT (9)execute at the newly specified time. Once the timer is started, the callout handle is marked as PENDING.Once the timer expires, the handle is marked as EXPIRED and INVOKING, and the PENDING status iscleared.The callout_setfunc() function sets the function and argument of the callout handle c to func andarg respectively. The callout handle must already be initialized. If a callout will always be used with thesame function and argument, then callout_setfunc() used in conjunction withcallout_schedule() is slightly more efficient than using callout_reset().The callout_stop() function stops the timer associated the callout handle c. The PENDING andEXPIRED status for the callout handle is cleared. It is safe to call callout_stop() on a callout handlethat is not pending, so long as it is initialized. callout_stop() will return a non-zero value if the calloutwas EXPIRED.SEE ALSOhz(9)The callout_pending() function tests the PENDING status of the callout handle c. A PENDING calloutis one that has been started and whose function has not yet been called. Note that it is possible for a callout’stimer to have expired without its function being called if interrupt level has not dropped low enough tolet softclock interrupts through. Note that it is only safe to test PENDING status when at softclock interruptlevel orhigher.The callout_expired() function tests to see if the callout’s timer has expired and its function called.The callout_active() function returns true if a timer has been started but not explicitly stopped, even ifit has already fired. callout_active(foo) is logically the same as callout_pending(foo) ||callout_expired(foo); it is implemented as a separate function for compatibility with FreeBSD and forthe special case of TCP_TIMER_ISARMED(). Its use is not recommended.The callout_invoking() function tests the INVOKING status of the callout handle c. This flag is setjust before a callout’s function is being called. Since the priority level islowered prior to invocation of thecallout function, other pending higher-priority code may run before the callout function is allowed to run.This may create a race condition if this higher-priority code deallocates storage containing one or more calloutstructures whose callout functions are about to be run. In such cases, one technique to prevent referencesto deallocated storage would be to test whether any callout functions are in the INVOKING state usingcallout_invoking(), and if so, to mark the data structure and defer storage deallocation until the calloutfunction is allowed to run. For this handshake protocol to work, the callout function will have to use thecallout_ack() function to clear this flag.The callout_ack() function clears the INVOKING state in the callout handle c. This is used in situationswhere it is necessary to protect against the race condition described under callout_invoking().HISTORYThe callout facility was implemented by Artur Grabowski and Thomas Nordin, based on the work of G.Varghese and A. Lauck, described in the paper Hashed and Hierarchical Timing Wheels: Data Structures forthe Efficient Implementation of a Timer Facility in the Proceedings of the 11th ACM Annual Symposium onOperating System Principles, Austin, Texas, November 1987. It was adapted to the NetBSD kernel by JasonR. Thorpe.NetBSD 3.0 December 29, 2007 2