1.\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd July 27, 2016 33.Dt TIMEOUT 9 34.Os 35.Sh NAME 36.Nm callout_active , 37.Nm callout_deactivate , 38.Nm callout_async_drain , 39.Nm callout_drain , 40.Nm callout_handle_init , 41.Nm callout_init , 42.Nm callout_init_mtx , 43.Nm callout_init_rm , 44.Nm callout_init_rw , 45.Nm callout_pending , 46.Nm callout_reset , 47.Nm callout_reset_curcpu , 48.Nm callout_reset_on , 49.Nm callout_reset_sbt , 50.Nm callout_reset_sbt_curcpu , 51.Nm callout_reset_sbt_on , 52.Nm callout_schedule , 53.Nm callout_schedule_curcpu , 54.Nm callout_schedule_on , 55.Nm callout_schedule_sbt , 56.Nm callout_schedule_sbt_curcpu , 57.Nm callout_schedule_sbt_on , 58.Nm callout_stop , 59.Nm callout_when , 60.Nm timeout , 61.Nm untimeout 62.Nd execute a function after a specified length of time 63.Sh SYNOPSIS 64.In sys/types.h 65.In sys/systm.h 66.Bd -literal 67typedef void timeout_t (void *); 68.Ed 69.Ft int 70.Fn callout_active "struct callout *c" 71.Ft void 72.Fn callout_deactivate "struct callout *c" 73.Ft int 74.Fn callout_async_drain "struct callout *c" "timeout_t *drain" 75.Ft int 76.Fn callout_drain "struct callout *c" 77.Ft void 78.Fn callout_handle_init "struct callout_handle *handle" 79.Bd -literal 80struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle); 81.Ed 82.Ft void 83.Fn callout_init "struct callout *c" "int mpsafe" 84.Ft void 85.Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags" 86.Ft void 87.Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags" 88.Ft void 89.Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags" 90.Ft int 91.Fn callout_pending "struct callout *c" 92.Ft int 93.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" 94.Ft int 95.Fo callout_reset_curcpu 96.Fa "struct callout *c" 97.Fa "int ticks" 98.Fa "timeout_t *func" 99.Fa "void *arg" 100.Fc 101.Ft int 102.Fo callout_reset_on 103.Fa "struct callout *c" 104.Fa "int ticks" 105.Fa "timeout_t *func" 106.Fa "void *arg" 107.Fa "int cpu" 108.Fc 109.Ft int 110.Fo callout_reset_sbt 111.Fa "struct callout *c" 112.Fa "sbintime_t sbt" 113.Fa "sbintime_t pr" 114.Fa "timeout_t *func" 115.Fa "void *arg" 116.Fa "int flags" 117.Fc 118.Ft int 119.Fo callout_reset_sbt_curcpu 120.Fa "struct callout *c" 121.Fa "sbintime_t sbt" 122.Fa "sbintime_t pr" 123.Fa "timeout_t *func" 124.Fa "void *arg" 125.Fa "int flags" 126.Fc 127.Ft int 128.Fo callout_reset_sbt_on 129.Fa "struct callout *c" 130.Fa "sbintime_t sbt" 131.Fa "sbintime_t pr" 132.Fa "timeout_t *func" 133.Fa "void *arg" 134.Fa "int cpu" 135.Fa "int flags" 136.Fc 137.Ft int 138.Fn callout_schedule "struct callout *c" "int ticks" 139.Ft int 140.Fn callout_schedule_curcpu "struct callout *c" "int ticks" 141.Ft int 142.Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu" 143.Ft int 144.Fo callout_schedule_sbt 145.Fa "struct callout *c" 146.Fa "sbintime_t sbt" 147.Fa "sbintime_t pr" 148.Fa "int flags" 149.Fc 150.Ft int 151.Fo callout_schedule_sbt_curcpu 152.Fa "struct callout *c" 153.Fa "sbintime_t sbt" 154.Fa "sbintime_t pr" 155.Fa "int flags" 156.Fc 157.Ft int 158.Fo callout_schedule_sbt_on 159.Fa "struct callout *c" 160.Fa "sbintime_t sbt" 161.Fa "sbintime_t pr" 162.Fa "int cpu" 163.Fa "int flags" 164.Fc 165.Ft int 166.Fn callout_stop "struct callout *c" 167.Ft sbintime_t 168.Fo callout_when 169.Fa "sbintime_t sbt" 170.Fa "sbintime_t precision" 171.Fa "int flags" 172.Fa "sbintime_t *sbt_res" 173.Fa "sbintime_t *precision_res" 174.Fc 175.Ft struct callout_handle 176.Fn timeout "timeout_t *func" "void *arg" "int ticks" 177.Ft void 178.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle" 179.Sh DESCRIPTION 180The 181.Nm callout 182API is used to schedule a call to an arbitrary function at a specific 183time in the future. 184Consumers of this API are required to allocate a callout structure 185.Pq struct callout 186for each pending function invocation. 187This structure stores state about the pending function invocation including 188the function to be called and the time at which the function should be invoked. 189Pending function calls can be cancelled or rescheduled to a different time. 190In addition, 191a callout structure may be reused to schedule a new function call after a 192scheduled call is completed. 193.Pp 194Callouts only provide a single-shot mode. 195If a consumer requires a periodic timer, 196it must explicitly reschedule each function call. 197This is normally done by rescheduling the subsequent call within the called 198function. 199.Pp 200Callout functions must not sleep. 201They may not acquire sleepable locks, 202wait on condition variables, 203perform blocking allocation requests, 204or invoke any other action that might sleep. 205.Pp 206Each callout structure must be initialized by 207.Fn callout_init , 208.Fn callout_init_mtx , 209.Fn callout_init_rm , 210or 211.Fn callout_init_rw 212before it is passed to any of the other callout functions. 213The 214.Fn callout_init 215function initializes a callout structure in 216.Fa c 217that is not associated with a specific lock. 218If the 219.Fa mpsafe 220argument is zero, 221the callout structure is not considered to be 222.Dq multi-processor safe ; 223and the Giant lock will be acquired before calling the callout function 224and released when the callout function returns. 225.Pp 226The 227.Fn callout_init_mtx , 228.Fn callout_init_rm , 229and 230.Fn callout_init_rw 231functions initialize a callout structure in 232.Fa c 233that is associated with a specific lock. 234The lock is specified by the 235.Fa mtx , 236.Fa rm , 237or 238.Fa rw 239parameter. 240The associated lock must be held while stopping or rescheduling the 241callout. 242The callout subsystem acquires the associated lock before calling the 243callout function and releases it after the function returns. 244If the callout was cancelled while the callout subsystem waited for the 245associated lock, 246the callout function is not called, 247and the associated lock is released. 248This ensures that stopping or rescheduling the callout will abort any 249previously scheduled invocation. 250.Pp 251Only regular mutexes may be used with 252.Fn callout_init_mtx ; 253spin mutexes are not supported. 254A sleepable read-mostly lock 255.Po 256one initialized with the 257.Dv RM_SLEEPABLE 258flag 259.Pc 260may not be used with 261.Fn callout_init_rm . 262Similarly, other sleepable lock types such as 263.Xr sx 9 264and 265.Xr lockmgr 9 266cannot be used with callouts because sleeping is not permitted in 267the callout subsystem. 268.Pp 269These 270.Fa flags 271may be specified for 272.Fn callout_init_mtx , 273.Fn callout_init_rm , 274or 275.Fn callout_init_rw : 276.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED" 277.It Dv CALLOUT_RETURNUNLOCKED 278The callout function will release the associated lock itself, 279so the callout subsystem should not attempt to unlock it 280after the callout function returns. 281.It Dv CALLOUT_SHAREDLOCK 282The lock is only acquired in read mode when running the callout handler. 283This flag is ignored by 284.Fn callout_init_mtx . 285.El 286.Pp 287The function 288.Fn callout_stop 289cancels a callout 290.Fa c 291if it is currently pending. 292If the callout is pending and successfully stopped, then 293.Fn callout_stop 294returns a value of one. 295If the callout is not set, or 296has already been serviced, then 297negative one is returned. 298If the callout is currently being serviced and cannot be stopped, 299then zero will be returned. 300If the callout is currently being serviced and cannot be stopped, and at the 301same time a next invocation of the same callout is also scheduled, then 302.Fn callout_stop 303unschedules the next run and returns zero. 304If the callout has an associated lock, 305then that lock must be held when this function is called. 306.Pp 307The function 308.Fn callout_async_drain 309is identical to 310.Fn callout_stop 311with one difference. 312When 313.Fn callout_async_drain 314returns zero it will arrange for the function 315.Fa drain 316to be called using the same argument given to the 317.Fn callout_reset 318function. 319.Fn callout_async_drain 320If the callout has an associated lock, 321then that lock must be held when this function is called. 322Note that when stopping multiple callouts that use the same lock it is possible 323to get multiple return's of zero and multiple calls to the 324.Fa drain 325function, depending upon which CPU's the callouts are running. 326The 327.Fa drain 328function itself is called from the context of the completing callout 329i.e. softclock or hardclock, just like a callout itself. 330.Pp 331The function 332.Fn callout_drain 333is identical to 334.Fn callout_stop 335except that it will wait for the callout 336.Fa c 337to complete if it is already in progress. 338This function MUST NOT be called while holding any 339locks on which the callout might block, or deadlock will result. 340Note that if the callout subsystem has already begun processing this 341callout, then the callout function may be invoked before 342.Fn callout_drain 343returns. 344However, the callout subsystem does guarantee that the callout will be 345fully stopped before 346.Fn callout_drain 347returns. 348.Pp 349The 350.Fn callout_reset 351and 352.Fn callout_schedule 353function families schedule a future function invocation for callout 354.Fa c . 355If 356.Fa c 357already has a pending callout, 358it is cancelled before the new invocation is scheduled. 359These functions return a value of one if a pending callout was cancelled 360and zero if there was no pending callout. 361If the callout has an associated lock, 362then that lock must be held when any of these functions are called. 363.Pp 364The time at which the callout function will be invoked is determined by 365either the 366.Fa ticks 367argument or the 368.Fa sbt , 369.Fa pr , 370and 371.Fa flags 372arguments. 373When 374.Fa ticks 375is used, 376the callout is scheduled to execute after 377.Fa ticks Ns No /hz 378seconds. 379Non-positive values of 380.Fa ticks 381are silently converted to the value 382.Sq 1 . 383.Pp 384The 385.Fa sbt , 386.Fa pr , 387and 388.Fa flags 389arguments provide more control over the scheduled time including 390support for higher resolution times, 391specifying the precision of the scheduled time, 392and setting an absolute deadline instead of a relative timeout. 393The callout is scheduled to execute in a time window which begins at 394the time specified in 395.Fa sbt 396and extends for the amount of time specified in 397.Fa pr . 398If 399.Fa sbt 400specifies a time in the past, 401the window is adjusted to start at the current time. 402A non-zero value for 403.Fa pr 404allows the callout subsystem to coalesce callouts scheduled close to each 405other into fewer timer interrupts, 406reducing processing overhead and power consumption. 407These 408.Fa flags 409may be specified to adjust the interpretation of 410.Fa sbt 411and 412.Fa pr : 413.Bl -tag -width ".Dv C_DIRECT_EXEC" 414.It Dv C_ABSOLUTE 415Handle the 416.Fa sbt 417argument as an absolute time since boot. 418By default, 419.Fa sbt 420is treated as a relative amount of time, 421similar to 422.Fa ticks . 423.It Dv C_DIRECT_EXEC 424Run the handler directly from hardware interrupt context instead of from the 425softclock thread. 426This reduces latency and overhead, but puts more constraints on the callout 427function. 428Callout functions run in this context may use only spin mutexes for locking 429and should be as small as possible because they run with absolute priority. 430.It Fn C_PREL 431Specifies relative event time precision as binary logarithm of time interval 432divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc. 433Note that the larger of 434.Fa pr 435or this value is used as the length of the time window. 436Smaller values 437.Pq which result in larger time intervals 438allow the callout subsystem to aggregate more events in one timer interrupt. 439.It Dv C_PRECALC 440The 441.Fa sbt 442argument specifies the absolute time at which the callout should be run, 443and the 444.Fa pr 445argument specifies the requested precision, which will not be 446adjusted during the scheduling process. 447The 448.Fa sbt 449and 450.Fa pr 451values should be calculated by an earlier call to 452.Fn callout_when 453which uses the user-supplied 454.Fa sbt , 455.Fa pr , 456and 457.Fa flags 458values. 459.It Dv C_HARDCLOCK 460Align the timeouts to 461.Fn hardclock 462calls if possible. 463.El 464.Pp 465The 466.Fn callout_reset 467functions accept a 468.Fa func 469argument which identifies the function to be called when the time expires. 470It must be a pointer to a function that takes a single 471.Fa void * 472argument. 473Upon invocation, 474.Fa func 475will receive 476.Fa arg 477as its only argument. 478The 479.Fn callout_schedule 480functions reuse the 481.Fa func 482and 483.Fa arg 484arguments from the previous callout. 485Note that one of the 486.Fn callout_reset 487functions must always be called to initialize 488.Fa func 489and 490.Fa arg 491before one of the 492.Fn callout_schedule 493functions can be used. 494.Pp 495The callout subsystem provides a softclock thread for each CPU in the system. 496Callouts are assigned to a single CPU and are executed by the softclock thread 497for that CPU. 498Initially, 499callouts are assigned to CPU 0. 500The 501.Fn callout_reset_on , 502.Fn callout_reset_sbt_on , 503.Fn callout_schedule_on 504and 505.Fn callout_schedule_sbt_on 506functions assign the callout to CPU 507.Fa cpu . 508The 509.Fn callout_reset_curcpu , 510.Fn callout_reset_sbt_curpu , 511.Fn callout_schedule_curcpu 512and 513.Fn callout_schedule_sbt_curcpu 514functions assign the callout to the current CPU. 515The 516.Fn callout_reset , 517.Fn callout_reset_sbt , 518.Fn callout_schedule 519and 520.Fn callout_schedule_sbt 521functions schedule the callout to execute in the softclock thread of the CPU 522to which it is currently assigned. 523.Pp 524Softclock threads are not pinned to their respective CPUs by default. 525The softclock thread for CPU 0 can be pinned to CPU 0 by setting the 526.Va kern.pin_default_swi 527loader tunable to a non-zero value. 528Softclock threads for CPUs other than zero can be pinned to their 529respective CPUs by setting the 530.Va kern.pin_pcpu_swi 531loader tunable to a non-zero value. 532.Pp 533The macros 534.Fn callout_pending , 535.Fn callout_active 536and 537.Fn callout_deactivate 538provide access to the current state of the callout. 539The 540.Fn callout_pending 541macro checks whether a callout is 542.Em pending ; 543a callout is considered 544.Em pending 545when a timeout has been set but the time has not yet arrived. 546Note that once the timeout time arrives and the callout subsystem 547starts to process this callout, 548.Fn callout_pending 549will return 550.Dv FALSE 551even though the callout function may not have finished 552.Pq or even begun 553executing. 554The 555.Fn callout_active 556macro checks whether a callout is marked as 557.Em active , 558and the 559.Fn callout_deactivate 560macro clears the callout's 561.Em active 562flag. 563The callout subsystem marks a callout as 564.Em active 565when a timeout is set and it clears the 566.Em active 567flag in 568.Fn callout_stop 569and 570.Fn callout_drain , 571but it 572.Em does not 573clear it when a callout expires normally via the execution of the 574callout function. 575.Pp 576The 577.Fn callout_when 578function may be used to pre-calculate the absolute time at which the 579timeout should be run and the precision of the scheduled run time 580according to the required time 581.Fa sbt , 582precision 583.Fa precision , 584and additional adjustments requested by the 585.Fa flags 586argument. 587Flags accepted by the 588.Fn callout_when 589function are the same as flags for the 590.Fn callout_reset 591function. 592The resulting time is assigned to the variable pointed to by the 593.Fa sbt_res 594argument, and the resulting precision is assigned to 595.Fa *precision_res . 596When passing the results to 597.Fa callout_reset , 598add the 599.Va C_PRECALC 600flag to 601.Fa flags , 602to avoid incorrect re-adjustment. 603The function is intended for situations where precise time of the callout 604run should be known in advance, since 605trying to read this time from the callout structure itself after a 606.Fn callout_reset 607call is racy. 608.Ss "Avoiding Race Conditions" 609The callout subsystem invokes callout functions from its own thread 610context. 611Without some kind of synchronization, 612it is possible that a callout 613function will be invoked concurrently with an attempt to stop or reset 614the callout by another thread. 615In particular, since callout functions typically acquire a lock as 616their first action, the callout function may have already been invoked, 617but is blocked waiting for that lock at the time that another thread 618tries to reset or stop the callout. 619.Pp 620There are three main techniques for addressing these 621synchronization concerns. 622The first approach is preferred as it is the simplest: 623.Bl -enum -offset indent 624.It 625Callouts can be associated with a specific lock when they are initialized 626by 627.Fn callout_init_mtx , 628.Fn callout_init_rm , 629or 630.Fn callout_init_rw . 631When a callout is associated with a lock, 632the callout subsystem acquires the lock before the callout function is 633invoked. 634This allows the callout subsystem to transparently handle races between 635callout cancellation, 636scheduling, 637and execution. 638Note that the associated lock must be acquired before calling 639.Fn callout_stop 640or one of the 641.Fn callout_reset 642or 643.Fn callout_schedule 644functions to provide this safety. 645.Pp 646A callout initialized via 647.Fn callout_init 648with 649.Fa mpsafe 650set to zero is implicitly associated with the 651.Va Giant 652mutex. 653If 654.Va Giant 655is held when cancelling or rescheduling the callout, 656then its use will prevent races with the callout function. 657.It 658The return value from 659.Fn callout_stop 660.Po 661or the 662.Fn callout_reset 663and 664.Fn callout_schedule 665function families 666.Pc 667indicates whether or not the callout was removed. 668If it is known that the callout was set and the callout function has 669not yet executed, then a return value of 670.Dv FALSE 671indicates that the callout function is about to be called. 672For example: 673.Bd -literal -offset indent 674if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) { 675 if (callout_stop(&sc->sc_callout)) { 676 sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING; 677 /* successfully stopped */ 678 } else { 679 /* 680 * callout has expired and callout 681 * function is about to be executed 682 */ 683 } 684} 685.Ed 686.It 687The 688.Fn callout_pending , 689.Fn callout_active 690and 691.Fn callout_deactivate 692macros can be used together to work around the race conditions. 693When a callout's timeout is set, the callout subsystem marks the 694callout as both 695.Em active 696and 697.Em pending . 698When the timeout time arrives, the callout subsystem begins processing 699the callout by first clearing the 700.Em pending 701flag. 702It then invokes the callout function without changing the 703.Em active 704flag, and does not clear the 705.Em active 706flag even after the callout function returns. 707The mechanism described here requires the callout function itself to 708clear the 709.Em active 710flag using the 711.Fn callout_deactivate 712macro. 713The 714.Fn callout_stop 715and 716.Fn callout_drain 717functions always clear both the 718.Em active 719and 720.Em pending 721flags before returning. 722.Pp 723The callout function should first check the 724.Em pending 725flag and return without action if 726.Fn callout_pending 727returns 728.Dv TRUE . 729This indicates that the callout was rescheduled using 730.Fn callout_reset 731just before the callout function was invoked. 732If 733.Fn callout_active 734returns 735.Dv FALSE 736then the callout function should also return without action. 737This indicates that the callout has been stopped. 738Finally, the callout function should call 739.Fn callout_deactivate 740to clear the 741.Em active 742flag. 743For example: 744.Bd -literal -offset indent 745mtx_lock(&sc->sc_mtx); 746if (callout_pending(&sc->sc_callout)) { 747 /* callout was reset */ 748 mtx_unlock(&sc->sc_mtx); 749 return; 750} 751if (!callout_active(&sc->sc_callout)) { 752 /* callout was stopped */ 753 mtx_unlock(&sc->sc_mtx); 754 return; 755} 756callout_deactivate(&sc->sc_callout); 757/* rest of callout function */ 758.Ed 759.Pp 760Together with appropriate synchronization, such as the mutex used above, 761this approach permits the 762.Fn callout_stop 763and 764.Fn callout_reset 765functions to be used at any time without races. 766For example: 767.Bd -literal -offset indent 768mtx_lock(&sc->sc_mtx); 769callout_stop(&sc->sc_callout); 770/* The callout is effectively stopped now. */ 771.Ed 772.Pp 773If the callout is still pending then these functions operate normally, 774but if processing of the callout has already begun then the tests in 775the callout function cause it to return without further action. 776Synchronization between the callout function and other code ensures that 777stopping or resetting the callout will never be attempted while the 778callout function is past the 779.Fn callout_deactivate 780call. 781.Pp 782The above technique additionally ensures that the 783.Em active 784flag always reflects whether the callout is effectively enabled or 785disabled. 786If 787.Fn callout_active 788returns false, then the callout is effectively disabled, since even if 789the callout subsystem is actually just about to invoke the callout 790function, the callout function will return without action. 791.El 792.Pp 793There is one final race condition that must be considered when a 794callout is being stopped for the last time. 795In this case it may not be safe to let the callout function itself 796detect that the callout was stopped, since it may need to access 797data objects that have already been destroyed or recycled. 798To ensure that the callout is completely finished, a call to 799.Fn callout_drain 800should be used. 801In particular, 802a callout should always be drained prior to destroying its associated lock 803or releasing the storage for the callout structure. 804.Sh LEGACY API 805.Bf Sy 806The functions below are a legacy API that will be removed in a future release. 807New code should not use these routines. 808.Ef 809.Pp 810The function 811.Fn timeout 812schedules a call to the function given by the argument 813.Fa func 814to take place after 815.Fa ticks Ns No /hz 816seconds. 817Non-positive values of 818.Fa ticks 819are silently converted to the value 820.Sq 1 . 821.Fa func 822should be a pointer to a function that takes a 823.Fa void * 824argument. 825Upon invocation, 826.Fa func 827will receive 828.Fa arg 829as its only argument. 830The return value from 831.Fn timeout 832is a 833.Ft struct callout_handle 834which can be used in conjunction with the 835.Fn untimeout 836function to request that a scheduled timeout be canceled. 837.Pp 838The function 839.Fn callout_handle_init 840can be used to initialize a handle to a state which will cause 841any calls to 842.Fn untimeout 843with that handle to return with no side 844effects. 845.Pp 846Assigning a callout handle the value of 847.Fn CALLOUT_HANDLE_INITIALIZER 848performs the same function as 849.Fn callout_handle_init 850and is provided for use on statically declared or global callout handles. 851.Pp 852The function 853.Fn untimeout 854cancels the timeout associated with 855.Fa handle 856using the 857.Fa func 858and 859.Fa arg 860arguments to validate the handle. 861If the handle does not correspond to a timeout with 862the function 863.Fa func 864taking the argument 865.Fa arg 866no action is taken. 867.Fa handle 868must be initialized by a previous call to 869.Fn timeout , 870.Fn callout_handle_init , 871or assigned the value of 872.Fn CALLOUT_HANDLE_INITIALIZER "&handle" 873before being passed to 874.Fn untimeout . 875The behavior of calling 876.Fn untimeout 877with an uninitialized handle 878is undefined. 879.Pp 880As handles are recycled by the system, it is possible (although unlikely) 881that a handle from one invocation of 882.Fn timeout 883may match the handle of another invocation of 884.Fn timeout 885if both calls used the same function pointer and argument, and the first 886timeout is expired or canceled before the second call. 887The timeout facility offers O(1) running time for 888.Fn timeout 889and 890.Fn untimeout . 891Timeouts are executed from 892.Fn softclock 893with the 894.Va Giant 895lock held. 896Thus they are protected from re-entrancy. 897.Sh RETURN VALUES 898The 899.Fn callout_active 900macro returns the state of a callout's 901.Em active 902flag. 903.Pp 904The 905.Fn callout_pending 906macro returns the state of a callout's 907.Em pending 908flag. 909.Pp 910The 911.Fn callout_reset 912and 913.Fn callout_schedule 914function families return a value of one if the callout was pending before the new 915function invocation was scheduled. 916.Pp 917The 918.Fn callout_stop 919and 920.Fn callout_drain 921functions return a value of one if the callout was still pending when it was 922called, a zero if the callout could not be stopped and a negative one is it 923was either not running or has already completed. 924The 925.Fn timeout 926function returns a 927.Ft struct callout_handle 928that can be passed to 929.Fn untimeout . 930.Sh HISTORY 931The current timeout and untimeout routines are based on the work of 932.An Adam M. Costello 933and 934.An George Varghese , 935published in a technical report entitled 936.%T "Redesigning the BSD Callout and Timer Facilities" 937and modified slightly for inclusion in 938.Fx 939by 940.An Justin T. Gibbs . 941The original work on the data structures used in this implementation 942was published by 943.An G. Varghese 944and 945.An A. Lauck 946in the paper 947.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" 948in the 949.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . 950The current implementation replaces the long standing 951.Bx 952linked list 953callout mechanism which offered O(n) insertion and removal running time 954but did not generate or require handles for untimeout operations. 955