Add new async_drain to the callout system. This is so-far not used but

should be used by TCP for sure in its cleanup of the IN-PCB (will be coming shortly).

Sponsored by:	Netflix Inc.
Differential Revision:	https://reviews.freebsd.org/D4076

1 files changed, 33 insertions, 5 deletions

diff --git a/share/man/man9/timeout.9 b/share/man/man9/timeout.9
index a0dc003..3f3841e 100644
--- a/share/man/man9/timeout.9
+++ b/share/man/man9/timeout.9
@@ -35,6 +35,7 @@
 .Sh NAME
 .Nm callout_active ,
 .Nm callout_deactivate ,
+.Nm callout_async_drain ,
 .Nm callout_drain ,
 .Nm callout_handle_init ,
 .Nm callout_init ,
@@ -69,6 +70,8 @@ typedef void timeout_t (void *);
 .Ft void
 .Fn callout_deactivate "struct callout *c"
 .Ft int
+.Fn callout_async_drain "struct callout *c" "timeout_t *drain"
+.Ft int
 .Fn callout_drain "struct callout *c"
 .Ft void
 .Fn callout_handle_init "struct callout_handle *handle"
@@ -236,17 +239,42 @@ The function
 cancels a callout
 .Fa c
 if it is currently pending.
-If the callout is pending, then
+If the callout is pending and successfuly stopped, then
 .Fn callout_stop
-returns a non-zero value.
-If the callout is not set,
-has already been serviced,
-or is currently being serviced,
+returns a value of one.
+If the callout is not set, or
+has already been serviced, then
+negative one is returned.
+If the callout is currently being serviced and cannot be stopped,
 then zero will be returned.
 If the callout has an associated lock,
 then that lock must be held when this function is called.
 .Pp
 The function
+.Fn callout_async_drain
+is identical to
+.Fn callout_stop
+with one difference.
+When
+.Fn callout_async_drain
+returns zero it will arrange for the function
+.Fa drain
+to be called using the same argument given to the
+.Fn callout_reset
+function. 
+.Fn callout_async_drain
+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
+.Fa drain
+function, depending upon which CPU's the callouts are running. The
+.Fa drain
+function itself is called from the context of the completing callout
+i.e. softclock or hardclock, just like a callout itself.
+p
+.Pp
+The function
 .Fn callout_drain
 is identical to
 .Fn callout_stop