svn commit: r277528 - in head: share/man/man9 sys/kern sys/ofed/include/linux sys/sys
Hans Petter Selasky
hselasky at FreeBSD.org
Thu Jan 22 11:12:43 UTC 2015
Author: hselasky
Date: Thu Jan 22 11:12:42 2015
New Revision: 277528
URL: https://svnweb.freebsd.org/changeset/base/277528
Log:
Revert for r277213:
FreeBSD developers need more time to review patches in the surrounding
areas like the TCP stack which are using MPSAFE callouts to restore
distribution of callouts on multiple CPUs.
Bump the __FreeBSD_version instead of reverting it.
Suggested by: kmacy, adrian, glebius and kib
Differential Revision: https://reviews.freebsd.org/D1438
Modified:
head/share/man/man9/Makefile
head/share/man/man9/timeout.9
head/sys/kern/init_main.c
head/sys/kern/kern_condvar.c
head/sys/kern/kern_lock.c
head/sys/kern/kern_switch.c
head/sys/kern/kern_synch.c
head/sys/kern/kern_thread.c
head/sys/kern/kern_timeout.c
head/sys/kern/subr_sleepqueue.c
head/sys/ofed/include/linux/completion.h
head/sys/sys/_callout.h
head/sys/sys/callout.h
head/sys/sys/param.h
head/sys/sys/proc.h
Modified: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile Thu Jan 22 09:25:31 2015 (r277527)
+++ head/share/man/man9/Makefile Thu Jan 22 11:12:42 2015 (r277528)
@@ -1570,7 +1570,6 @@ MLINKS+=timeout.9 callout.9 \
timeout.9 callout_active.9 \
timeout.9 callout_deactivate.9 \
timeout.9 callout_drain.9 \
- timeout.9 callout_drain_async.9 \
timeout.9 callout_handle_init.9 \
timeout.9 callout_init.9 \
timeout.9 callout_init_mtx.9 \
Modified: head/share/man/man9/timeout.9
==============================================================================
--- head/share/man/man9/timeout.9 Thu Jan 22 09:25:31 2015 (r277527)
+++ head/share/man/man9/timeout.9 Thu Jan 22 11:12:42 2015 (r277528)
@@ -29,14 +29,13 @@
.\"
.\" $FreeBSD$
.\"
-.Dd January 14, 2015
+.Dd October 8, 2014
.Dt TIMEOUT 9
.Os
.Sh NAME
.Nm callout_active ,
.Nm callout_deactivate ,
.Nm callout_drain ,
-.Nm callout_drain_async ,
.Nm callout_handle_init ,
.Nm callout_init ,
.Nm callout_init_mtx ,
@@ -64,232 +63,279 @@
.In sys/systm.h
.Bd -literal
typedef void timeout_t (void *);
-typedef void callout_func_t (void *);
.Ed
+.Ft int
+.Fn callout_active "struct callout *c"
+.Ft void
+.Fn callout_deactivate "struct callout *c"
+.Ft int
+.Fn callout_drain "struct callout *c"
+.Ft void
+.Fn callout_handle_init "struct callout_handle *handle"
+.Bd -literal
+struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
+.Ed
+.Ft void
+.Fn callout_init "struct callout *c" "int mpsafe"
+.Ft void
+.Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
+.Ft void
+.Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
+.Ft void
+.Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
+.Ft int
+.Fn callout_pending "struct callout *c"
+.Ft int
+.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
+.Ft int
+.Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \
+"void *arg"
+.Ft int
+.Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \
+"void *arg" "int cpu"
+.Ft int
+.Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \
+"sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
+.Ft int
+.Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
+"sbintime_t pr" "timeout_t *func" "void *arg" "int flags"
+.Ft int
+.Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
+"sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags"
+.Ft int
+.Fn callout_schedule "struct callout *c" "int ticks"
+.Ft int
+.Fn callout_schedule_curcpu "struct callout *c" "int ticks"
+.Ft int
+.Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
+.Ft int
+.Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \
+"sbintime_t pr" "int flags"
+.Ft int
+.Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
+"sbintime_t pr" "int flags"
+.Ft int
+.Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \
+"sbintime_t pr" "int cpu" "int flags"
+.Ft int
+.Fn callout_stop "struct callout *c"
+.Ft struct callout_handle
+.Fn timeout "timeout_t *func" "void *arg" "int ticks"
+.Ft void
+.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
.Sh DESCRIPTION
The
.Nm callout
API is used to schedule a call to an arbitrary function at a specific
-time in the future in a single-shot fashion.
-Consumers of this API are required to allocate a
-.Pq struct callout
-structure for each pending function invocation.
-The
+time in the future.
+Consumers of this API are required to allocate a callout structure
.Pq struct callout
-structure stores the full state about any pending function call and
-should be drained by a call to
-.Fn callout_drain
-or
-.Fn callout_drain_async
-before freeing.
-.Sh INITIALISATION
-.Ft void
-.Fn callout_handle_init "struct callout_handle *handle"
-This function is deprecated and is used to prepare a
-.Pq struct callout_handle
-structure before it can be used the first time.
-If this function is called on a pending timeout, the pending timeout
-cannot be cancelled and the
-.Fn untimeout
-function will return as if there was no timeout pending.
+for each pending function invocation.
+This structure stores state about the pending function invocation including
+the function 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.
+.Pp
+Callouts only provide a single-shot mode.
+If a consumer requires a periodic timer,
+it must explicitly reschedule each function call.
+This is normally done by rescheduling the subsequent call within the called
+function.
.Pp
-.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
-This macro is deprecated and can be used instead of
-.Fn callout_handle_init
-to assign the default state to the
-.Pq struct callout_handle
-structure when declaring static timeouts.
+Callout functions must not sleep.
+They may not acquire sleepable locks,
+wait on condition variables,
+perform blocking allocation requests,
+or invoke any other action that might sleep.
.Pp
-.Ft void
-.Fn callout_init "struct callout *c" "int mpsafe"
-This function prepares a
-.Pq struct callout
-structure before it can be used.
-This function should not be used when the callout is pending a timeout.
+Each callout structure must be initialized by
+.Fn callout_init ,
+.Fn callout_init_mtx ,
+.Fn callout_init_rm ,
+or
+.Fn callout_init_rw
+before it is passed to any of the other callout functions.
+The
+.Fn callout_init
+function initializes a callout structure in
+.Fa c
+that is not associated with a specific lock.
If the
.Fa mpsafe
-argument is non-zero, the callback function will be running unlocked.
-Else the Giant mutex will be locked before calling the callback function.
+argument is zero,
+the callout structure is not considered to be
+.Dq multi-processor safe ;
+and the Giant lock will be acquired before calling the callout function
+and released when the callout function returns.
.Pp
-.Ft void
-.Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags"
-This function prepares a
-.Pq struct callout
-structure before it can be used.
-This function should not be used when the callout is pending a timeout.
The
-.Fa mtx
-argument should be non-zero and should specify a pointer to a valid
-spinlock type of mutex or a valid regular non-sleepable mutex which
-the callback subsystem should lock before calling the callback
-function.
-Valid
+.Fn callout_init_mtx ,
+.Fn callout_init_rm ,
+and
+.Fn callout_init_rw
+functions initialize a callout structure in
+.Fa c
+that is associated with a specific lock.
+The lock is specified by the
+.Fa mtx ,
+.Fa rm ,
+or
+.Fa rw
+parameter.
+The associated lock must be held while stopping or rescheduling the
+callout.
+The callout subsystem acquires the associated lock before calling the
+callout function and releases it after the function 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
+previously scheduled invocation.
+.Pp
+Only regular mutexes may be used with
+.Fn callout_init_mtx ;
+spin mutexes are not supported.
+A sleepable read-mostly lock
+.Po
+one initialized with the
+.Dv RM_SLEEPABLE
+flag
+.Pc
+may not be used with
+.Fn callout_init_rm .
+Similarly, other sleepable lock types such as
+.Xr sx 9
+and
+.Xr lockmgr 9
+cannot be used with callouts because sleeping is not permitted in
+the callout subsystem.
+.Pp
+These
.Fa flags
-are:
+may be specified for
+.Fn callout_init_mtx ,
+.Fn callout_init_rm ,
+or
+.Fn callout_init_rw :
.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED"
.It Dv CALLOUT_RETURNUNLOCKED
-It is assumed that the callout function has released the specified
-mutex before returning.
-Else the callout subsystem will release the specified mutex after the
-callout function has returned.
+The callout function will release the associated lock itself,
+so the callout subsystem should not attempt to unlock it
+after the callout function returns.
+.It Dv CALLOUT_SHAREDLOCK
+The lock is only acquired in read mode when running the callout handler.
+This flag is ignored by
+.Fn callout_init_mtx .
.El
.Pp
-.Ft void
-.Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags"
-This function is the same like the
-.Fn callout_init_mtx
-function except it accepts a read-mostly type of lock.
-The read-mostly lock must not be initialised with the
-.Dv RM_SLEEPABLE
-flag.
+The function
+.Fn callout_stop
+cancels a callout
+.Fa c
+if it is currently pending.
+If the callout is pending, then
+.Fn callout_stop
+returns a non-zero value.
+If the callout is not set,
+has already been serviced,
+or is currently being serviced,
+then zero will be returned.
+If the callout has an associated lock,
+then that lock must be held when this function is called.
.Pp
-.Ft void
-.Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags"
-This function is the same like the
-.Fn callout_init_mtx
-function except it accepts a reader-writer type of lock.
-.Sh SCHEDULING CALLOUTS
-.Ft struct callout_handle
-.Fn timeout "timeout_t *func" "void *arg" "int ticks"
-This function is deprecated and schedules a call to the function given by the argument
-.Fa func
-to take place after
+The function
+.Fn callout_drain
+is identical to
+.Fn callout_stop
+except that it will wait for the callout
+.Fa c
+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
+.Fn callout_drain
+returns.
+However, the callout subsystem does guarantee that the callout will be
+fully stopped before
+.Fn callout_drain
+returns.
+.Pp
+The
+.Fn callout_reset
+and
+.Fn callout_schedule
+function families schedule a future function invocation for callout
+.Fa c .
+If
+.Fa c
+already has a pending callout,
+it is cancelled before the new invocation is scheduled.
+These functions return a non-zero value 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.
+.Pp
+The time at which the callout function will be invoked is determined by
+either the
+.Fa ticks
+argument or the
+.Fa sbt ,
+.Fa pr ,
+and
+.Fa flags
+arguments.
+When
+.Fa ticks
+is used,
+the callout is scheduled to execute after
.Fa ticks Ns No /hz
seconds.
Non-positive values of
.Fa ticks
are silently converted to the value
.Sq 1 .
-The
-.Fa func
-argument should be a valid pointer to a function that takes a single
-.Fa void *
-argument.
-Upon invocation, the
-.Fa func
-function will receive
-.Fa arg
-as its only argument.
-The Giant lock is locked when the
-.Fa arg
-function is invoked and should not be unlocked by this function.
-The returned value from
-.Fn timeout
-is a
-.Ft struct callout_handle
-structure which can be used in conjunction with the
-.Fn untimeout
-function to request that a scheduled timeout be cancelled.
-As handles are recycled by the system, it is possible, although unlikely,
-that a handle from one invocation of
-.Fn timeout
-may match the handle of another invocation of
-.Fn timeout
-if both calls used the same function pointer and argument, and the first
-timeout is expired or canceled before the second call.
-Please ensure that the function and argument pointers are unique when using this function.
.Pp
-.Ft int
-.Fn callout_reset "struct callout *c" "int ticks" "callout_func_t *func" "void *arg"
-This function is used to schedule or re-schedule a callout.
-This function at first stops the callout given by the
-.Fa c
-argument, if any.
-Then it will start the callout given by the
-.Fa c
-argument.
-The relative time until the timeout callback happens is given by the
-.Fa ticks
-argument.
-The number of ticks in a second is defined by
-.Dv hz
-and can vary from system to system.
-This function returns a non-zero value if the given callout was pending and
-the callback function was prevented from being called.
-Else a value of zero is returned.
-If a lock is associated with the callout given by the
-.Fa c
-argument and it is exclusivly locked when this function is called this
-function will always ensure that previous callback function, if any,
-is never reached.
-In other words the callout will be atomically restarted.
-Else there is no such guarantee.
-The callback function is given by the
-.Fa func
-argument and its function argument is given by the
-.Fa arg
-argument.
-.Pp
-.Ft int
-.Fn callout_reset_curcpu "struct callout *c" "int ticks" "callout_func_t *func" \
-"void *arg"
-This function works the same like the
-.Fn callout_reset
-function except the callback function given by the
-.Fa func
-argument will be executed on the same CPU which called this function.
-A change in the CPU selection can happen if the callout has a lock
-associated with it and is locked when this function is called.
-A change in the CPU selection cannot happen if this function is
-re-scheduled inside a callout function.
-Else the callback function given by the
-.Fa func
-argument will be executed on the same CPU like previously done.
-.Pp
-.Ft int
-.Fn callout_reset_on "struct callout *c" "int ticks" "callout_func_t *func" \
-"void *arg" "int cpu"
-This function works the same like the
-.Fn callout_reset
-function except the callback function given by the
-.Fa func
-argument will be executed on the CPU given by the
-.Fa cpu
-argument.
-A change in the CPU selection can happen if the callout has a lock
-associated with it and is locked when this function is called.
-A change in the CPU selection cannot happen if this function is
-re-scheduled inside a callout function.
-Else the callback function given by the
-.Fa func
-argument will be executed on the same CPU like previously done.
-.Pp
-.Ft int
-.Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \
-"sbintime_t pr" "callout_func_t *func" "void *arg" "int flags"
-This function works the same like the
-.Fn callout_reset
-function except the relative or absolute time after which the timeout
-callback should happen is given by the
+The
+.Fa sbt ,
+.Fa pr ,
+and
+.Fa flags
+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
.Fa sbt
-argument and extends for the amount of time specified in the
-.Fa pr
-argument.
-This function is used when you need high precision timeouts.
-If the
+and extends for the amount of time specified in
+.Fa pr .
+If
.Fa sbt
-argument specifies a time in the past,
+specifies a time in the past,
the window is adjusted to start at the current time.
A non-zero value for
.Fa pr
allows the callout subsystem to coalesce callouts scheduled close to each
other into fewer timer interrupts,
reducing processing overhead and power consumption.
-The
+These
.Fa flags
-argument may be non-zero to adjust the interpretation of the
+may be specified to adjust the interpretation of
.Fa sbt
-and the
-.Fa pr
-arguments:
+and
+.Fa pr :
.Bl -tag -width ".Dv C_DIRECT_EXEC"
.It Dv C_ABSOLUTE
Handle the
.Fa sbt
argument as an absolute time since boot.
-By default, the
+By default,
.Fa sbt
-argument is treated like a relative amount of time,
+is treated as a relative amount of time,
similar to
.Fa ticks .
.It Dv C_DIRECT_EXEC
@@ -301,7 +347,7 @@ Callout functions run in this context ma
and should be as small as possible because they run with absolute priority.
.It Fn C_PREL
Specifies relative event time precision as binary logarithm of time interval
-divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4 and so on.
+divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
Note that the larger of
.Fa pr
or this value is used as the length of the time window.
@@ -314,215 +360,65 @@ Align the timeouts to
calls if possible.
.El
.Pp
-.Ft int
-.Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
-"sbintime_t pr" "callout_func_t *func" "void *arg" "int flags"
-This function works the same like the
-.Fn callout_reset_sbt
-function except the callback function given by the
-.Fa func
-argument will be executed on the same CPU which called this function.
-A change in the CPU selection can happen if the callout has a lock
-associated with it and is locked when this function is called.
-A change in the CPU selection cannot happen if this function is
-re-scheduled inside a callout function.
-Else the callback function given by the
-.Fa func
-argument will be executed on the same CPU like previously done.
-.Pp
-.Ft int
-.Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
-"sbintime_t pr" "callout_func_t *func" "void *arg" "int cpu" "int flags"
-This function works the same like the
-.Fn callout_reset_sbt
-function except the callback function given by the
+The
+.Fn callout_reset
+functions accept a
.Fa func
-argument will be executed on the CPU given by the
-.Fa cpu
+argument which identifies the function to be called when the time expires.
+It must be a pointer to a function that takes a single
+.Fa void *
argument.
-A change in the CPU selection can happen if the callout has a lock
-associated with it and is locked when this function is called.
-A change in the CPU selection cannot happen if this function is
-re-scheduled inside a callout function.
-Else the callback function given by the
+Upon invocation,
.Fa func
-argument will be executed on the same CPU like previously done.
-.Pp
-.Ft int
-.Fn callout_schedule "struct callout *c" "int ticks"
-This function works the same like the
-.Fn callout_reset
-function except it re-uses the callback function and the callback argument
-already stored in the
-.Pq struct callout
-structure.
-.Pp
-.Ft int
-.Fn callout_schedule_curcpu "struct callout *c" "int ticks"
-This function works the same like the
-.Fn callout_reset_curcpu
-function except it re-uses the callback function and the callback argument
-already stored in the
-.Pq struct callout
-structure.
-.Pp
-.Ft int
-.Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu"
-This function works the same like the
-.Fn callout_reset_on
-function except it re-uses the callback function and the callback argument
-already stored in the
-.Pq struct callout
-structure.
-.Pp
-.Ft int
-.Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \
-"sbintime_t pr" "int flags"
-This function works the same like the
-.Fn callout_reset_sbt
-function except it re-uses the callback function and the callback argument
-already stored in the
-.Pq struct callout
-structure.
-.Pp
-.Ft int
-.Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \
-"sbintime_t pr" "int flags"
-This function works the same like the
-.Fn callout_reset_sbt_curcpu
-function except it re-uses the callback function and the callback argument
-already stored in the
-.Pq struct callout
-structure.
-.Pp
-.Ft int
-.Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \
-"sbintime_t pr" "int cpu" "int flags"
-This function works the same like the
-.Fn callout_reset_sbt_on
-function except it re-uses the callback function and the callback argument
-already stored in the
-.Pq struct callout
-structure.
-.Sh CHECKING THE STATE OF CALLOUTS
-.Ft int
-.Fn callout_pending "struct callout *c"
-This function returns non-zero if the callout pointed to by the
-.Fa c
-argument is pending for callback.
-Else this function returns zero.
-This function returns zero when inside the callout function if the
-callout is not re-scheduled.
-.Pp
-.Ft int
-.Fn callout_active "struct callout *c"
-This function is deprecated and returns non-zero if the callout
-pointed to by the
-.Fa c
-argument was scheduled in the past.
-Else this function returns zero.
-This function also returns zero after the
-.Fn callout_deactivate
-or the
-.Fn callout_stop
-or the
-.Fn callout_drain
-or the
-.Fn callout_drain_async
-function is called on the same callout as given by the
-.Fa c
-argument.
-.Pp
-.Ft void
-.Fn callout_deactivate "struct callout *c"
-This function is deprecated and ensures that subsequent calls to the
-.Fn callout_activate
-function returns zero until the callout is scheduled again.
-.Sh STOPPING CALLOUTS
-.Ft void
-.Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle"
-This function is deprecated and cancels the timeout associated with the
-.Fa handle
-argument using the function pointed to by the
+will receive
+.Fa arg
+as its only argument.
+The
+.Fn callout_schedule
+functions reuse the
.Fa func
-argument and having the
+and
.Fa arg
-arguments to validate the handle.
-If the handle does not correspond to a timeout with
-the function
+arguments from the previous callout.
+Note that one of the
+.Fn callout_reset
+functions must always be called to initialize
.Fa func
-taking the argument
+and
.Fa arg
-no action is taken. The
-.Fa handle
-must be initialised by a previous call to
-.Fn timeout ,
-.Fn callout_handle_init
-or assigned the value of
-.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
-before being passed to
-.Fn untimeout .
-The behavior of calling
-.Fn untimeout
-with an uninitialised handle
-is undefined.
+before one of the
+.Fn callout_schedule
+functions can be used.
.Pp
-.Ft int
-.Fn callout_stop "struct callout *c"
-This function is used to stop a timeout function invocation associated with the callout pointed to by the
-.Fa c
-argument, in a non-blocking fashion.
-This function can be called multiple times in a row with no side effects, even if the callout is already stopped. This function however should not be called before the callout has been initialised.
-This function returns a non-zero value if the given callout was pending and
-the callback function was prevented from being called.
-Else a value of zero is returned.
-If a lock is associated with the callout given by the
-.Fa c
-argument and it is exclusivly locked when this function is called, the
-.Fn callout_stop
-function will always ensure that the callback function is never reached.
-In other words the callout will be atomically stopped.
-Else there is no such guarantee.
-.Sh DRAINING CALLOUTS
-.Ft int
-.Fn callout_drain "struct callout *c"
-This function works the same like the
-.Fn callout_stop
-function except it ensures that all callback functions have returned and there are no more references to the callout pointed to by the
-.Fa c
-argument inside the callout subsystem before it returns.
-Also this function ensures that the lock, if any, associated with the
-callout is no longer being used.
-When this function returns, it is safe to free the callout structure pointed to by the
-.Fa c
-argument.
+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
+.Fn callout_reset_on ,
+.Fn callout_reset_sbt_on ,
+.Fn callout_schedule_on
+and
+.Fn callout_schedule_sbt_on
+functions assign the callout to CPU
+.Fa cpu .
+The
+.Fn callout_reset_curcpu ,
+.Fn callout_reset_sbt_curpu ,
+.Fn callout_schedule_curcpu
+and
+.Fn callout_schedule_sbt_curcpu
+functions assign the callout to the current CPU.
+The
+.Fn callout_reset ,
+.Fn callout_reset_sbt ,
+.Fn callout_schedule
+and
+.Fn callout_schedule_sbt
+functions schedule the callout to execute in the softclock thread of the CPU
+to which it is currently assigned.
.Pp
-.Ft int
-.Fn callout_drain_async "struct callout *c" "callout_func_t *fn" "void *arg"
-This function is non-blocking and works the same like the
-.Fn callout_stop
-function except if it returns non-zero it means the callback function pointed to by the
-.Fa fn
-argument will be called back with the
-.Fa arg
-argument when all references to the callout pointed to by the
-.Fa c
-argument are gone.
-If this function returns zero, it is safe to free the callout structure pointed to by the
-.Fa c
-argument right away.
-.Sh CALLOUT FUNCTION RESTRICTIONS
-Callout functions must not sleep.
-They may not acquire sleepable locks, wait on condition variables,
-perform blocking allocation requests, or invoke any other action that
-might sleep.
-.Sh CALLOUT SUBSYSTEM INTERNALS
-The callout subsystem has its own set of spinlocks to protect its internal state.
-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.
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
.Va kern.pin_default_swi
@@ -531,7 +427,50 @@ Softclock threads for CPUs other than ze
respective CPUs by setting the
.Va kern.pin_pcpu_swi
loader tunable to a non-zero value.
-.Sh "AVOIDING RACE CONDITIONS"
+.Pp
+The macros
+.Fn callout_pending ,
+.Fn callout_active
+and
+.Fn callout_deactivate
+provide access to the current state of the callout.
+The
+.Fn callout_pending
+macro checks whether a callout is
+.Em pending ;
+a callout is considered
+.Em pending
+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,
+.Fn callout_pending
+will return
+.Dv FALSE
+even though the callout function may not have finished
+.Pq or even begun
+executing.
+The
+.Fn callout_active
+macro checks whether a callout is marked as
+.Em active ,
+and the
+.Fn callout_deactivate
+macro clears the callout's
+.Em active
+flag.
+The callout subsystem marks a callout as
+.Em active
+when a timeout is set and it clears the
+.Em active
+flag in
+.Fn callout_stop
+and
+.Fn callout_drain ,
+but it
+.Em does not
+clear it when a callout expires normally via the execution of the
+callout function.
+.Ss "Avoiding Race Conditions"
The callout subsystem invokes callout functions from its own thread
context.
Without some kind of synchronization,
@@ -548,7 +487,7 @@ synchronization concerns.
The first approach is preferred as it is the simplest:
.Bl -enum -offset indent
.It
-Callouts can be associated with a specific lock when they are initialised
+Callouts can be associated with a specific lock when they are initialized
by
.Fn callout_init_mtx ,
.Fn callout_init_rm ,
@@ -569,7 +508,7 @@ or
.Fn callout_schedule
functions to provide this safety.
.Pp
-A callout initialised via
+A callout initialized via
.Fn callout_init
with
.Fa mpsafe
@@ -592,8 +531,9 @@ function families
.Pc
indicates whether or not the callout was removed.
If it is known that the callout was set and the callout function has
-not yet executed, then a return value of zero indicates that the
-callout function is about to be called.
+not yet executed, then a return value of
+.Dv FALSE
+indicates that the callout function is about to be called.
For example:
.Bd -literal -offset indent
if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) {
@@ -649,14 +589,16 @@ The callout function should first check
.Em pending
flag and return without action if
.Fn callout_pending
-returns non-zero.
+returns
+.Dv TRUE .
This indicates that the callout was rescheduled using
.Fn callout_reset
just before the callout function was invoked.
If
.Fn callout_active
-returns zero then the callout function should also return without
-action.
+returns
+.Dv FALSE
+then the callout function should also return without action.
This indicates that the callout has been stopped.
Finally, the callout function should call
.Fn callout_deactivate
@@ -726,13 +668,129 @@ a callout should always be drained prior
or releasing the storage for the callout structure.
.Sh LEGACY API
.Bf Sy
-The
+The functions below are a legacy API that will be removed in a future release.
+New code should not use these routines.
+.Ef
+.Pp
+The function
+.Fn timeout
+schedules a call to the function given by the argument
+.Fa func
+to take place after
+.Fa ticks Ns No /hz
+seconds.
+Non-positive values of
+.Fa ticks
+are silently converted to the value
+.Sq 1 .
+.Fa func
+should be a pointer to a function that takes a
+.Fa void *
+argument.
+Upon invocation,
+.Fa func
+will receive
+.Fa arg
+as its only argument.
+The return value from
.Fn timeout
+is a
+.Ft struct callout_handle
+which can be used in conjunction with the
+.Fn untimeout
+function to request that a scheduled timeout be canceled.
+.Pp
+The function
+.Fn callout_handle_init
+can be used to initialize a handle to a state which will cause
+any calls to
+.Fn untimeout
+with that handle to return with no side
+effects.
+.Pp
+Assigning a callout handle the value of
+.Fn CALLOUT_HANDLE_INITIALIZER
+performs the same function as
+.Fn callout_handle_init
+and is provided for use on statically declared or global callout handles.
+.Pp
+The function
+.Fn untimeout
+cancels the timeout associated with
+.Fa handle
+using the
+.Fa func
and
+.Fa arg
+arguments to validate the handle.
+If the handle does not correspond to a timeout with
+the function
+.Fa func
+taking the argument
+.Fa arg
+no action is taken.
+.Fa handle
+must be initialized by a previous call to
+.Fn timeout ,
+.Fn callout_handle_init ,
+or assigned the value of
+.Fn CALLOUT_HANDLE_INITIALIZER "&handle"
+before being passed to
+.Fn untimeout .
+The behavior of calling
.Fn untimeout
-functions are a legacy API that will be removed in a future release.
-New code should not use these routines.
-.Ef
+with an uninitialized handle
+is undefined.
+.Pp
+As handles are recycled by the system, it is possible (although unlikely)
+that a handle from one invocation of
+.Fn timeout
+may match the handle of another invocation of
+.Fn timeout
+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
+.Fn timeout
+and
+.Fn untimeout .
+Timeouts are executed from
+.Fn softclock
+with the
+.Va Giant
+lock held.
+Thus they are protected from re-entrancy.
+.Sh RETURN VALUES
+The
+.Fn callout_active
+macro returns the state of a callout's
+.Em active
+flag.
+.Pp
+The
+.Fn callout_pending
+macro returns the state of a callout's
+.Em pending
+flag.
+.Pp
+The
+.Fn callout_reset
+and
+.Fn callout_schedule
+function families return non-zero if the callout was pending before the new
+function invocation was scheduled.
+.Pp
+The
+.Fn callout_stop
+and
+.Fn callout_drain
+functions return non-zero if the callout was still pending when it was
+called or zero otherwise.
+The
+.Fn timeout
+function returns a
+.Ft struct callout_handle
+that can be passed to
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-head
mailing list