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
This commit is contained in:
parent
66aa9b8dc9
commit
4ce04b3d91
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=227116
@ -1,4 +1,4 @@
|
|||||||
.\" Copyright 2006 John-Mark Gurney
|
.\" Copyright 2006,2011 John-Mark Gurney
|
||||||
.\" All rights reserved.
|
.\" All rights reserved.
|
||||||
.\"
|
.\"
|
||||||
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
@ -24,15 +24,16 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd December 28, 2006
|
.Dd November 5, 2011
|
||||||
.Dt KQUEUE 9
|
.Dt KQUEUE 9
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
.Nm kqueue_add_filteropts , kqueue_del_filteropts ,
|
.Nm kqueue_add_filteropts , kqueue_del_filteropts ,
|
||||||
.Nm kqfd_register ,
|
.Nm kqfd_register ,
|
||||||
.Nm knote_fdclose ,
|
.Nm knote_fdclose ,
|
||||||
|
.Nm knlist_init , knlist_init_mtx ,
|
||||||
.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty ,
|
.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
|
.Nm KNOTE_LOCKED , KNOTE_UNLOCKED
|
||||||
.Nd "event delivery subsystem"
|
.Nd "event delivery subsystem"
|
||||||
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
||||||
@ -46,14 +47,6 @@
|
|||||||
.Ft void
|
.Ft void
|
||||||
.Fn knote_fdclose "struct thread *td" "int fd"
|
.Fn knote_fdclose "struct thread *td" "int fd"
|
||||||
.Ft void
|
.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
|
.Fo knlist_init
|
||||||
.Fa "struct knlist *knl"
|
.Fa "struct knlist *knl"
|
||||||
.Fa "void *lock"
|
.Fa "void *lock"
|
||||||
@ -62,12 +55,22 @@
|
|||||||
.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]"
|
.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]"
|
||||||
.Fc
|
.Fc
|
||||||
.Ft void
|
.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
|
.Ft void
|
||||||
.Fn knlist_clear "struct knlist *knl" "int islocked"
|
.Fn knlist_clear "struct knlist *knl" "int islocked"
|
||||||
.Ft void
|
.Ft void
|
||||||
.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
|
.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
|
||||||
.Ft void
|
.Ft void
|
||||||
|
.Fn knlist_destroy "struct knlist *knl"
|
||||||
|
.Ft void
|
||||||
.Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
|
.Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
|
||||||
.Ft void
|
.Ft void
|
||||||
.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint"
|
.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint"
|
||||||
@ -135,7 +138,8 @@ bit of
|
|||||||
.Va kn_status
|
.Va kn_status
|
||||||
in the
|
in the
|
||||||
.Vt knote .
|
.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
|
During
|
||||||
.Va f_attach ,
|
.Va f_attach ,
|
||||||
it is valid to change the
|
it is valid to change the
|
||||||
@ -155,7 +159,13 @@ function will be called to detach the
|
|||||||
if the
|
if the
|
||||||
.Vt knote
|
.Vt knote
|
||||||
has not already been detached by a call to
|
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
|
.It Va f_event
|
||||||
The
|
The
|
||||||
.Va f_event
|
.Va f_event
|
||||||
@ -247,57 +257,120 @@ A
|
|||||||
is not required, but is commonly used.
|
is not required, but is commonly used.
|
||||||
If used, the
|
If used, the
|
||||||
.Vt knlist
|
.Vt knlist
|
||||||
must be initialized with the
|
must be initialized with either
|
||||||
.Fn knlist_init
|
.Fn knlist_init
|
||||||
function.
|
or
|
||||||
If
|
.Fn knlist_init_mtx .
|
||||||
.Fa lock
|
|
||||||
is
|
|
||||||
.Dv NULL ,
|
|
||||||
an internal lock will be used and the remaining arguments will be ignored.
|
|
||||||
The
|
|
||||||
.Fa kl_lock , kl_unlock
|
|
||||||
and
|
|
||||||
.Fa kl_locked
|
|
||||||
functions will be used to manipulate a
|
|
||||||
.Fa lock .
|
|
||||||
If the argument is
|
|
||||||
.Dv NULL ,
|
|
||||||
default routines operating on
|
|
||||||
.Vt "struct mtx *"
|
|
||||||
will be used.
|
|
||||||
The
|
The
|
||||||
.Vt knlist
|
.Vt knlist
|
||||||
structure may be embedded into the object structure.
|
structure may be embedded into the object structure.
|
||||||
The
|
The
|
||||||
.Fa lock
|
.Fa lock
|
||||||
will be held over calls to
|
will be held over
|
||||||
.Va f_event .
|
.Va f_event
|
||||||
If
|
calls.
|
||||||
.Dv NULL
|
.Pp
|
||||||
is passed for the mutex, a private mutex will be used.
|
For the
|
||||||
|
.Fn knlist_init
|
||||||
|
function, if
|
||||||
|
.Fa lock
|
||||||
|
is
|
||||||
|
.Dv NULL ,
|
||||||
|
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
|
||||||
|
will be used to manipulate the argument
|
||||||
|
.Fa lock .
|
||||||
|
If any of the function pointers are
|
||||||
|
.Dv NULL ,
|
||||||
|
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
|
||||||
|
when
|
||||||
|
.Fa lock
|
||||||
|
is a
|
||||||
|
.Dv MTX_DEF
|
||||||
|
style
|
||||||
|
.Xr mutex 9
|
||||||
|
lock.
|
||||||
|
.Pp
|
||||||
The function
|
The function
|
||||||
.Fn knlist_empty
|
.Fn knlist_empty
|
||||||
requires that a
|
returns true when there are no
|
||||||
|
.Vt knotes
|
||||||
|
on the list.
|
||||||
|
The function requires that the
|
||||||
.Fa lock
|
.Fa lock
|
||||||
be held.
|
be held when called.
|
||||||
|
.Pp
|
||||||
The function
|
The function
|
||||||
.Fn knlist_clear
|
.Fn knlist_clear
|
||||||
is used to remove all
|
removes all
|
||||||
.Vt knotes
|
.Vt knotes
|
||||||
associated with the list.
|
from the list.
|
||||||
The
|
The
|
||||||
.Fa islocked
|
.Fa islocked
|
||||||
argument declares if
|
argument declares if the
|
||||||
.Fa lock
|
.Fa lock
|
||||||
has been acquired.
|
has been acquired.
|
||||||
All
|
All
|
||||||
.Vt knotes
|
.Vt knotes
|
||||||
will be marked as detached, and
|
will have
|
||||||
.Dv EV_ONESHOT
|
.Dv EV_ONESHOT
|
||||||
will be set so that the
|
set so that the
|
||||||
.Vt knote
|
.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
|
The
|
||||||
.Fn knlist_destroy
|
.Fn knlist_destroy
|
||||||
function is used to destroy a
|
function is used to destroy a
|
||||||
@ -314,7 +387,9 @@ may be attached to the object.
|
|||||||
A
|
A
|
||||||
.Vt knlist
|
.Vt knlist
|
||||||
may be emptied by calling
|
may be emptied by calling
|
||||||
.Fn knlist_clear .
|
.Fn knlist_clear
|
||||||
|
or
|
||||||
|
.Fn knlist_delete .
|
||||||
.Pp
|
.Pp
|
||||||
The macros
|
The macros
|
||||||
.Fn KNOTE_LOCKED
|
.Fn KNOTE_LOCKED
|
||||||
@ -333,7 +408,7 @@ The macro
|
|||||||
.Fn KNOTE_LOCKED
|
.Fn KNOTE_LOCKED
|
||||||
must be used if the lock associated with the
|
must be used if the lock associated with the
|
||||||
.Fa knl
|
.Fa knl
|
||||||
passed in is held.
|
is held.
|
||||||
The function
|
The function
|
||||||
.Fn KNOTE_UNLOCKED
|
.Fn KNOTE_UNLOCKED
|
||||||
will acquire the lock before iterating over the list of
|
will acquire the lock before iterating over the list of
|
||||||
|
Loading…
Reference in New Issue
Block a user