Module Name: src
Committed By: ad
Date: Mon May 4 11:28:20 UTC 2009
Modified Files:
src/share/man/man9: callout.9
Log Message:
Document callout_halt.
To generate a diff of this commit:
cvs rdiff -u -r1.21 -r1.22 src/share/man/man9/callout.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/callout.9
diff -u src/share/man/man9/callout.9:1.21 src/share/man/man9/callout.9:1.22
--- src/share/man/man9/callout.9:1.21 Thu Mar 12 12:48:26 2009
+++ src/share/man/man9/callout.9 Mon May 4 11:28:20 2009
@@ -1,6 +1,6 @@
-.\" $NetBSD: callout.9,v 1.21 2009/03/12 12:48:26 joerg Exp $
+.\" $NetBSD: callout.9,v 1.22 2009/05/04 11:28:20 ad Exp $
.\"
-.\" Copyright (c) 2000, 2003 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2000, 2003, 2009 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
@@ -27,12 +27,13 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd December 29, 2007
+.Dd May 4, 2009
.Dt CALLOUT 9
.Os
.Sh NAME
.Nm callout_init ,
.Nm callout_destroy ,
+.Nm callout_halt ,
.Nm callout_reset ,
.Nm callout_schedule ,
.Nm callout_setfunc ,
@@ -58,6 +59,8 @@
.Ft bool
.Fn "callout_stop" "callout_t *c"
.Ft bool
+.Fn "callout_halt" "callout_t *c" "kmutex_t *interlock"
+.Ft bool
.Fn "callout_pending" "callout_t *c"
.Ft bool
.Fn "callout_expired" "callout_t *c"
@@ -156,8 +159,9 @@
.Pp
The
.Fn callout_stop
-function stops the timer associated the callout handle
-.Fa c .
+function requests that the timer associated the callout handle
+.Fa c
+be stopped.
The
.Em PENDING
and
@@ -169,6 +173,43 @@
.Fn callout_stop
will return a non-zero value if the callout was
.Em EXPIRED .
+Note that
+.Fn callout_stop
+can return while the callout is running on a different CPU or at a
+different interrupt priority level on the current CPU.
+It can only be said to prevent the callout from firing in the future,
+unless explicitly re-scheduled.
+To stop a callout and wait for completion, use
+.Fn callout_halt .
+.Pp
+.Fn callout_halt
+acts much like
+.Fn callout_stop ,
+but waits for the callout to complete if it is currently in-flight.
+.Fn callout_halt
+may not be called from a hard interrupt handler as it will sleep if the
+callout is currently executing.
+If the callout can take locks (such as mutexes or RW locks), the caller of
+.Fn callout_halt
+must not hold any of those locks, otherwise the two could deadlock.
+To facilitate this,
+.Fn callout_halt
+can optionally release a single mutex specified by the
+.Fa interlock
+parameter.
+If
+.Fa interlock
+is not
+.Dv NULL
+and the calling thread must wait for the callout to complete,
+.Fa interlock
+will be released before waiting and re-acquired before returning.
+If no wait is required,
+.Fa interlock
+will not be released.
+However, to avoid race conditions the caller should always assume that
+.Fa interlock
+has been released and reacquired, and act accordingly.
.Pp
The
.Fn callout_pending
