group functions together by function...

document knlist_delete, and better document what knlist_clear does...  Note
that both of these functions may sleep, and also unlock/relock the list
lock...

document knlist_init_mtx (forgotten by kib)...

other minor improvements

Reviewed by:	ru (previous rev)
MFC after:	1 week

1 files changed, 117 insertions, 42 deletions

diff --git a/share/man/man9/kqueue.9 b/share/man/man9/kqueue.9
index c657088..8f0d109 100644
--- a/share/man/man9/kqueue.9
+++ b/share/man/man9/kqueue.9
@@ -1,4 +1,4 @@
-.\" Copyright 2006 John-Mark Gurney
+.\" Copyright 2006,2011 John-Mark Gurney
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -24,15 +24,16 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 28, 2006
+.Dd November 5, 2011
 .Dt KQUEUE 9
 .Os
 .Sh NAME
 .Nm kqueue_add_filteropts , kqueue_del_filteropts ,
 .Nm kqfd_register ,
 .Nm knote_fdclose ,
+.Nm knlist_init , knlist_init_mtx ,
 .Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty ,
-.Nm knlist_init , knlist_destroy , knlist_clear , knlist_delete ,
+.Nm knlist_clear , knlist_delete , knlist_destroy ,
 .Nm KNOTE_LOCKED , KNOTE_UNLOCKED
 .Nd "event delivery subsystem"
 .Sh SYNOPSIS
@@ -46,14 +47,6 @@
 .Ft void
 .Fn knote_fdclose "struct thread *td" "int fd"
 .Ft void
-.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked"
-.Ft void
-.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked"
-.Ft void
-.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn"
-.Ft int
-.Fn knlist_empty "struct knlist *knl"
-.Ft void
 .Fo knlist_init
 .Fa "struct knlist *knl"
 .Fa "void *lock"
@@ -62,12 +55,22 @@
 .Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]"
 .Fc
 .Ft void
-.Fn knlist_destroy "struct knlist *knl"
+.Fn knlist_init_mtx "struct knlist *knl" "struct mtx *lock"
+.Ft void
+.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked"
+.Ft void
+.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked"
+.Ft void
+.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn"
+.Ft int
+.Fn knlist_empty "struct knlist *knl"
 .Ft void
 .Fn knlist_clear "struct knlist *knl" "int islocked"
 .Ft void
 .Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
 .Ft void
+.Fn knlist_destroy "struct knlist *knl"
+.Ft void
 .Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
 .Ft void
 .Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint"
@@ -135,7 +138,8 @@ bit of
 .Va kn_status
 in the
 .Vt knote .
-The function shall return 0 on success, or appropriate error for the failure.
+The function shall return 0 on success, or appropriate error for the failure,
+such as when the object is being destroyed, or does not exist.
 During
 .Va f_attach ,
 it is valid to change the
@@ -155,7 +159,13 @@ function will be called to detach the
 if the
 .Vt knote
 has not already been detached by a call to
-.Fn knlist_remove .
+.Fn knlist_remove ,
+.Fn knlist_remove_inevent
+or
+.Fn knlist_delete .
+The list
+.Fa lock
+will not be held when this function is called.
 .It Va f_event
 The
 .Va f_event
@@ -247,57 +257,120 @@ A
 is not required, but is commonly used.
 If used, the
 .Vt knlist
-must be initialized with the
+must be initialized with either
 .Fn knlist_init
-function.
-If
+or
+.Fn knlist_init_mtx .
+The
+.Vt knlist
+structure may be embedded into the object structure.
+The
+.Fa lock
+will be held over
+.Va f_event
+calls.
+.Pp
+For the
+.Fn knlist_init
+function, if
 .Fa lock
 is
 .Dv NULL ,
-an internal lock will be used and the remaining arguments will be ignored.
-The
+a shared global lock will be used and the remaining arguments must be
+.Dv NULL .
+The function pointers
 .Fa kl_lock , kl_unlock
 and
 .Fa kl_locked
-functions will be used to manipulate a
+will be used to manipulate the argument
 .Fa lock .
-If the argument is
+If any of the function pointers are
 .Dv NULL ,
-default routines operating on
-.Vt "struct mtx *"
-will be used.
-The
+a function operating on
+.Dv MTX_DEF
+style
+.Xr mutex 9
+locks will be used instead.
+.Pp
+The function
+.Fn knlist_init_mtx
+may be used to initalize a
 .Vt knlist
-structure may be embedded into the object structure.
-The
+when
 .Fa lock
-will be held over calls to
-.Va f_event .
-If
-.Dv NULL
-is passed for the mutex, a private mutex will be used.
+is a
+.Dv MTX_DEF
+style
+.Xr mutex 9
+lock.
+.Pp
 The function
 .Fn knlist_empty
-requires that a
+returns true when there are no
+.Vt knotes
+on the list.
+The function requires that the
 .Fa lock
-be held.
+be held when called.
+.Pp
 The function
 .Fn knlist_clear
-is used to remove all
+removes all
 .Vt knotes
-associated with the list.
+from the list.
 The
 .Fa islocked
-argument declares if
+argument declares if the
 .Fa lock
 has been acquired.
 All
 .Vt knotes
-will be marked as detached, and
+will have
 .Dv EV_ONESHOT
-will be set so that the
+set so that the
 .Vt knote
-will be deleted after the next scan.
+will be returned and removed durning the next scan.
+The
+.Va f_detach
+function will be called when the
+.Vt knote
+is deleted durning the next scan.
+This function must not be used when
+.Va f_isfd
+is set in
+.Vt "struct filterops" ,
+as the
+.Fa td
+argument of
+.Fn fdrop
+will be
+.Dv NULL .
+.Pp
+The function
+.Fn knlist_delete
+removes and deletes all
+.Vt knotes
+on the list.
+The function
+.Va f_detach
+will not be called, and the
+.Vt knote
+will not be returned on the next scan.
+Using this function could leak user land resources if a process uses the
+.Vt knote
+to track resources.
+.Pp
+Both the
+.Fn knlist_clear
+and
+.Fn knlist_delete
+functions may sleep.
+They also may release the
+.Fa lock
+to wait for other
+.Vt knotes
+to drain.
+.Pp
 The
 .Fn knlist_destroy
 function is used to destroy a
@@ -314,7 +387,9 @@ may be attached to the object.
 A
 .Vt knlist
 may be emptied by calling
-.Fn knlist_clear .
+.Fn knlist_clear
+or
+.Fn knlist_delete .
 .Pp
 The macros
 .Fn KNOTE_LOCKED
@@ -333,7 +408,7 @@ The macro
 .Fn KNOTE_LOCKED
 must be used if the lock associated with the
 .Fa knl
-passed in is held.
+is held.
 The function
 .Fn KNOTE_UNLOCKED
 will acquire the lock before iterating over the list of