Date: Sat, 5 Nov 2011 17:55:49 +0000 (UTC) From: John-Mark Gurney <jmg@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r227116 - head/share/man/man9 Message-ID: <201111051755.pA5HtnTF078535@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: jmg Date: Sat Nov 5 17:55:49 2011 New Revision: 227116 URL: http://svn.freebsd.org/changeset/base/227116 Log: 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 Modified: head/share/man/man9/kqueue.9 Modified: head/share/man/man9/kqueue.9 ============================================================================== --- head/share/man/man9/kqueue.9 Sat Nov 5 17:43:28 2011 (r227115) +++ head/share/man/man9/kqueue.9 Sat Nov 5 17:55:49 2011 (r227116) @@ -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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201111051755.pA5HtnTF078535>