svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
timeout(9)
typedef void timeout_t (void *); struct callout_handle handle =
CALLOUT_HANDLE_INITIALIZER(&handle); The API is used to schedule
a call to an arbitrary function at a specific time in the future.
Consumers of this API are required to allocate a callout struc‐
ture for each pending function invocation. This structure stores
state about the pending function invocation including the func‐
tion to be called and the time at which the function should be
invoked. Pending function calls can be cancelled or rescheduled
to a different time. In addition, a callout structure may be
reused to schedule a new function call after a scheduled call is
completed. Callouts only provide a single-shot mode. If a con‐
sumer requires a periodic timer, it must explicitly reschedule
each function call. This is normally done by rescheduling the
subsequent call within the called function. Callout functions
must not sleep. They may not acquire sleepable locks, wait on
condition variables, perform blocking allocation requests, or in‐
voke any other action that might sleep. Each callout structure
must be initialized by or before it is passed to any of the other
callout functions. The function initializes a callout structure
in that is not associated with a specific lock. If the argument
is zero, the callout structure is not considered to be and the
Giant lock will be acquired before calling the callout function
and released when the callout function returns. The and func‐
tions initialize a callout structure in that is associated with a
specific lock. The lock is specified by the or parameter. The
associated lock must be held while stopping or rescheduling the
callout. The callout subsystem acquires the associated lock be‐
fore calling the callout function and releases it after the func‐
tion returns. If the callout was cancelled while the callout
subsystem waited for the associated lock, the callout function is
not called, and the associated lock is released. This ensures
that stopping or rescheduling the callout will abort any previ‐
ously scheduled invocation. Only regular mutexes may be used
with spin mutexes are not supported. A sleepable read-mostly
lock one initialized with the flag may not be used with Simi‐
larly, other sleepable lock types such as and cannot be used with
callouts because sleeping is not permitted in the callout subsys‐
tem. These may be specified for or The callout function will re‐
lease the associated lock itself, so the callout subsystem should
not attempt to unlock it after the callout function returns. The
lock is only acquired in read mode when running the callout han‐
dler. This flag is ignored by The function cancels a callout if
it is currently pending. If the callout is pending and success‐
fully stopped, then returns a value of one. If the callout is
not set, or has already been serviced, then negative one is re‐
turned. If the callout is currently being serviced and cannot be
stopped, then zero will be returned. If the callout is currently
being serviced and cannot be stopped, and at the same time a next
invocation of the same callout is also scheduled, then unsched‐
ules the next run and returns zero. If the callout has an asso‐
ciated lock, then that lock must be held when this function is
called. The function is identical to with one difference. When
returns zero it will arrange for the function to be called using
the same argument given to the function. If the callout has an
associated lock, then that lock must be held when this function
is called. Note that when stopping multiple callouts that use
the same lock it is possible to get multiple return's of zero and
multiple calls to the function, depending upon which CPU's the
callouts are running. The function itself is called from the
context of the completing callout i.e. softclock or hardclock,
just like a callout itself. The function is identical to except
that it will wait for the callout to complete if it is already in
progress. This function MUST NOT be called while holding any
locks on which the callout might block, or deadlock will result.
Note that if the callout subsystem has already begun processing
this callout, then the callout function may be invoked before re‐
turns. However, the callout subsystem does guarantee that the
callout will be fully stopped before returns. The and function
families schedule a future function invocation for callout If al‐
ready has a pending callout, it is cancelled before the new invo‐
cation is scheduled. These functions return a value of one if a
pending callout was cancelled and zero if there was no pending
callout. If the callout has an associated lock, then that lock
must be held when any of these functions are called. The time at
which the callout function will be invoked is determined by ei‐
ther the argument or the and arguments. When is used, the call‐
out is scheduled to execute after seconds. Non-positive values
of are silently converted to the value The and arguments provide
more control over the scheduled time including support for higher
resolution times, specifying the precision of the scheduled time,
and setting an absolute deadline instead of a relative timeout.
The callout is scheduled to execute in a time window which begins
at the time specified in and extends for the amount of time spec‐
ified in If specifies a time in the past, the window is adjusted
to start at the current time. A non-zero value for allows the
callout subsystem to coalesce callouts scheduled close to each
other into fewer timer interrupts, reducing processing overhead
and power consumption. These may be specified to adjust the in‐
terpretation of and Handle the argument as an absolute time since
boot. By default, is treated as a relative amount of time, simi‐
lar to Run the handler directly from hardware interrupt context
instead of from the softclock thread. This reduces latency and
overhead, but puts more constraints on the callout function.
Callout functions run in this context may use only spin mutexes
for locking and should be as small as possible because they run
with absolute priority. Specifies relative event time precision
as binary logarithm of time interval divided by acceptable time
deviation: 1 -- 1/2, 2 -- 1/4, etc. Note that the larger of or
this value is used as the length of the time window. Smaller
values allow the callout subsystem to aggregate more events in
one timer interrupt. The argument specifies the absolute time at
which the callout should be run, and the argument specifies the
requested precision, which will not be adjusted during the sched‐
uling process. The and values should be calculated by an earlier
call to which uses the user-supplied and values. Align the time‐
outs to calls if possible. The functions accept a argument which
identifies the function to be called when the time expires. It
must be a pointer to a function that takes a single argument.
Upon invocation, will receive as its only argument. The func‐
tions reuse the and arguments from the previous callout. Note
that one of the functions must always be called to initialize and
before one of the functions can be used. The callout subsystem
provides a softclock thread for each CPU in the system. Callouts
are assigned to a single CPU and are executed by the softclock
thread for that CPU. Initially, callouts are assigned to CPU 0.
The and functions assign the callout to CPU The and functions as‐
sign the callout to the current CPU. The and functions schedule
the callout to execute in the softclock thread of the CPU to
which it is currently assigned. Softclock threads are not pinned
to their respective CPUs by default. The softclock thread for
CPU 0 can be pinned to CPU 0 by setting the loader tunable to a
non-zero value. Softclock threads for CPUs other than zero can
be pinned to their respective CPUs by setting the loader tunable
to a non-zero value. The macros and provide access to the cur‐
rent state of the callout. The macro checks whether a callout is
a callout is considered when a timeout has been set but the time
has not yet arrived. Note that once the timeout time arrives and
the callout subsystem starts to process this callout, will return
even though the callout function may not have finished executing.
The macro checks whether a callout is marked as and the macro
clears the callout's flag. The callout subsystem marks a callout
as when a timeout is set and it clears the flag in and but it
clear it when a callout expires normally via the execution of the
callout function. The function may be used to pre-calculate the
absolute time at which the timeout should be run and the preci‐
sion of the scheduled run time according to the required time
precision and additional adjustments requested by the argument.
Flags accepted by the function are the same as flags for the
function. The resulting time is assigned to the variable pointed
to by the argument, and the resulting precision is assigned to
When passing the results to add the flag to to avoid incorrect
re-adjustment. The function is intended for situations where
precise time of the callout run should be known in advance, since
trying to read this time from the callout structure itself after
a call is racy. The callout subsystem invokes callout functions
from its own thread context. Without some kind of synchroniza‐
tion, it is possible that a callout function will be invoked con‐
currently with an attempt to stop or reset the callout by another
thread. In particular, since callout functions typically acquire
a lock as their first action, the callout function may have al‐
ready been invoked, but is blocked waiting for that lock at the
time that another thread tries to reset or stop the callout.
There are three main techniques for addressing these synchroniza‐
tion concerns. The first approach is preferred as it is the sim‐
plest: Callouts can be associated with a specific lock when they
are initialized by or When a callout is associated with a lock,
the callout subsystem acquires the lock before the callout func‐
tion is invoked. This allows the callout subsystem to transpar‐
ently handle races between callout cancellation, scheduling, and
execution. Note that the associated lock must be acquired before
calling or one of the or functions to provide this safety. A
callout initialized via with set to zero is implicitly associated
with the mutex. If is held when cancelling or rescheduling the
callout, then its use will prevent races with the callout func‐
tion. The return value from or the and function families indi‐
cates whether or not the callout was removed. If it is known
that the callout was set and the callout function has not yet ex‐
ecuted, then a return value of indicates that the callout func‐
tion is about to be called. For example: if (sc->sc_flags &
SCFLG_CALLOUT_RUNNING) { if (callout_stop(&sc->sc_call‐
out)) { sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING;
/* successfully stopped */ } else {
/* * callout has expired and
callout * function is about to be executed
*/ } } The and macros can be used to‐
gether to work around the race conditions. When a callout's
timeout is set, the callout subsystem marks the callout as both
and When the timeout time arrives, the callout subsystem begins
processing the callout by first clearing the flag. It then in‐
vokes the callout function without changing the flag, and does
not clear the flag even after the callout function returns. The
mechanism described here requires the callout function itself to
clear the flag using the macro. The and functions always clear
both the and flags before returning. The callout function should
first check the flag and return without action if returns This
indicates that the callout was rescheduled using just before the
callout function was invoked. If returns then the callout func‐
tion should also return without action. This indicates that the
callout has been stopped. Finally, the callout function should
call to clear the flag. For example: mtx_lock(&sc->sc_mtx); if
(callout_pending(&sc->sc_callout)) { /* callout was reset
*/ mtx_unlock(&sc->sc_mtx); return; } if (!call‐
out_active(&sc->sc_callout)) { /* callout was stopped */
mtx_unlock(&sc->sc_mtx); return; } callout_deac‐
tivate(&sc->sc_callout); /* rest of callout function */ Together
with appropriate synchronization, such as the mutex used above,
this approach permits the and functions to be used at any time
without races. For example: mtx_lock(&sc->sc_mtx); call‐
out_stop(&sc->sc_callout); /* The callout is effectively stopped
now. */ If the callout is still pending then these functions op‐
erate normally, but if processing of the callout has already be‐
gun then the tests in the callout function cause it to return
without further action. Synchronization between the callout
function and other code ensures that stopping or resetting the
callout will never be attempted while the callout function is
past the call. The above technique additionally ensures that the
flag always reflects whether the callout is effectively enabled
or disabled. If returns false, then the callout is effectively
disabled, since even if the callout subsystem is actually just
about to invoke the callout function, the callout function will
return without action. There is one final race condition that
must be considered when a callout is being stopped for the last
time. In this case it may not be safe to let the callout func‐
tion itself detect that the callout was stopped, since it may
need to access data objects that have already been destroyed or
recycled. To ensure that the callout is completely finished, a
call to should be used. In particular, a callout should always
be drained prior to destroying its associated lock or releasing
the storage for the callout structure. The functions below are a
legacy API that will be removed in a future release. New code
should not use these routines. The function schedules a call to
the function given by the argument to take place after seconds.
Non-positive values of are silently converted to the value should
be a pointer to a function that takes a argument. Upon invoca‐
tion, will receive as its only argument. The return value from
is a which can be used in conjunction with the function to re‐
quest that a scheduled timeout be canceled. The function can be
used to initialize a handle to a state which will cause any calls
to with that handle to return with no side effects. Assigning a
callout handle the value of performs the same function as and is
provided for use on statically declared or global callout han‐
dles. The function cancels the timeout associated with using the
and arguments to validate the handle. If the handle does not
correspond to a timeout with the function taking the argument no
action is taken. must be initialized by a previous call to or
assigned the value of before being passed to The behavior of
calling with an uninitialized handle is undefined. As handles
are recycled by the system, it is possible (although unlikely)
that a handle from one invocation of may match the handle of an‐
other invocation of if both calls used the same function pointer
and argument, and the first timeout is expired or canceled before
the second call. The timeout facility offers O(1) running time
for and Timeouts are executed from with the lock held. Thus they
are protected from re-entrancy. The macro returns the state of a
callout's flag. The macro returns the state of a callout's flag.
The and function families return a value of one if the callout
was pending before the new function invocation was scheduled.
The and functions return a value of one if the callout was still
pending when it was called, a zero if the callout could not be
stopped and a negative one is it was either not running or has
already completed. The function returns a that can be passed to
The current timeout and untimeout routines are based on the work
of and published in a technical report entitled and modified
slightly for inclusion in by The original work on the data struc‐
tures used in this implementation was published by and in the pa‐
per in the The current implementation replaces the long standing
linked list callout mechanism which offered O(n) insertion and
removal running time but did not generate or require handles for
untimeout operations.