PERFORCE change 146468 for review

[Sam Leffler]

http://perforce.freebsd.org/chv.cgi?CH=146468

Change 146468 by sam at sam_ebb on 2008/08/02 17:15:57

	document callout_schedule

Affected files ...

.. //depot/projects/vap/share/man/man9/timeout.9#3 edit

Differences ...

==== //depot/projects/vap/share/man/man9/timeout.9#3 (text+ko) ====

@@ -36,7 +36,7 @@
 .\"
 .\" $FreeBSD: src/share/man/man9/timeout.9,v 1.32 2007/11/20 12:21:36 gabor Exp $
 .\"
-.Dd November 20, 2007
+.Dd August 2, 2008
 .Dt TIMEOUT 9
 .Os
 .Sh NAME
@@ -49,6 +49,7 @@
 .Nm callout_stop ,
 .Nm callout_drain ,
 .Nm callout_reset ,
+.Nm callout_schedule ,
 .Nm callout_pending ,
 .Nm callout_active ,
 .Nm callout_deactivate
@@ -83,6 +84,8 @@
 .Ft int
 .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg"
 .Ft int
+.Fn callout_schedule "struct callout *c" "int ticks"
+.Ft int
 .Fn callout_pending "struct callout *c"
 .Ft int
 .Fn callout_active "struct callout *c"
@@ -191,9 +194,10 @@
 .Fn callout_init_mtx ,
 .Fn callout_init_rw ,
 .Fn callout_stop ,
-.Fn callout_drain
+.Fn callout_drain ,
+.Fn callout_reset
 and
-.Fn callout_reset
+.Fn callout_schedule
 are low-level routines for clients who wish to allocate their own
 callout structures.
 .Pp
@@ -201,9 +205,10 @@
 .Fn callout_init
 initializes a callout so it can be passed to
 .Fn callout_stop ,
-.Fn callout_drain
+.Fn callout_drain ,
+.Fn callout_reset 
 or
-.Fn callout_reset
+.Fn callout_schedule 
 without any side effects.
 If the
 .Fa mpsafe
@@ -294,6 +299,17 @@
 will return a non-zero value.
 If the callout has an associated mutex, then that mutex must be
 held when this function is called.
+The function
+.Fn callout_schedule
+(re)schedules an existing callout for a new period of time; it is
+equivalent to calling
+.Fn callout_reset
+with the
+.Fa func
+and
+.Fa arg
+parameters extracted from the callout structure (though possibly with
+lower overhead).
 .Pp
 The macros
 .Fn callout_pending ,