misc/153254: Please add API to kqueue(2) to notify when watches are dropped

[Paul Evans]

>Number:         153254
>Category:       misc
>Synopsis:       Please add API to kqueue(2) to notify when watches are dropped
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-bugs
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Dec 17 17:00:19 UTC 2010
>Closed-Date:
>Last-Modified:
>Originator:     Paul Evans
>Release:        8.1-RELEASE
>Organization:
>Environment:
n/a
>Description:
kevent(2) can be used to pass userland pointers into the kernel's watch structure, via the  void *udata  field. Kernel holds these pointers in the knote structure in the kernel, until such time as they are dropped by the kernel. It does not inform userland of this fact.

This makes it impossible to generically handle memory-management issues (malloc/free or equivalent) in a portable wrapper library.

See my message thread on freebsd-hackers@,

  http://lists.freebsd.org/pipermail/freebsd-hackers/2010-November/033565.html

and in particular the issues numbered 1 to 4 in the last message:

  http://lists.freebsd.org/pipermail/freebsd-hackers/2010-November/033621.html
>How-To-Repeat:
n/a
>Fix:
I propose the addition of a new flag applicable to any kevent watch structure, documented thusly:

     The flags field can contain the following values:
..
     EV_DROPWATCH   Requests that the kernel will send an EV_DROPPED event
                    on this watch when it has finished watching it for any
                    reason, including EV_DELETE, expiry because of
                    EV_ONESHOT, or because the filehandle was closed by
                    close(2).

     EV_DROPPED     This flag is returned by the kernel if it is now about
                    to drop the watch. After this flag has been received,
                    no further events will occur on this watch.

This flag then makes it trivial to build a generic wrapper for kqueue that can always manage its memory correctly.

 a) at EV_ADD time, simply set  flags |= EV_DROPWATCH

 b) after an event has been processed that included the EV_DROPPED flag, 
    free() the pointer given in the udata field.

It is not required that these two flags have distinct values; since one is userland->kernel and the other kernel->userland, they could for neatness reuse the same bit field.

Having had a read of the kevent implementation at

  http://www.freebsd.org/cgi/cvsweb.cgi/src/sys/kern/kern_event.c?rev=1.140

I believe it ought to be possible to implement this with only a small change, around 50 lines, mostly altering the behaviour of knote_drop().

I am happy to look into implementing this feature, if you agree it looks useful to add and would be willing to consider accepting it.

>Release-Note:
>Audit-Trail:
>Unformatted: