share/man/man9/selrecord.9

   1 .\"
   2 .\" Copyright (C) 2002 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd August 25, 2011
  30 .Dt SELRECORD 9
  31 .Os
  32 .Sh NAME
  33 .Nm seldrain ,
  34 .Nm selrecord ,
  35 .Nm selwakeup
  36 .Nd "record and wakeup select requests"
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/selinfo.h
  40 .Ft void
  41 .Fn seldrain "struct selinfo *sip"
  42 .Ft void
  43 .Fn selrecord "struct thread *td" "struct selinfo *sip"
  44 .Ft void
  45 .Fn selwakeup "struct selinfo *sip"
  46 .Sh DESCRIPTION
  47 .Fn seldrain ,
  48 .Fn selrecord
  49 and
  50 .Fn selwakeup
  51 are the three central functions used by
  52 .Xr select 2 ,
  53 .Xr poll 2
  54 and the objects that are being selected on.
  55 They handle the task of recording which threads are waiting on which objects
  56 and the waking of the proper threads when an event of interest occurs on an
  57 object.
  58 .Pp
  59 .Fn selrecord
  60 records that the calling thread is interested in events related to a given
  61 object.
  62 If another thread is already waiting on the object a collision will be flagged
  63 in
  64 .Fa sip
  65 which will be later dealt with by
  66 .Fn selwakeup .
  67 .Pp
  68 .Fn selrecord
  69 acquires and releases
  70 .Va sellock .
  71 .Pp
  72 .Fn selwakeup
  73 is called by the underlying object handling code in order to notify any waiting
  74 threads that an event of interest has occurred.
  75 If a collision has occurred,
  76 .Fn selwakeup
  77 will increment
  78 .Va nselcoll ,
  79 and broadcast on the global cv in order to wake all waiting threads so that
  80 they can handle it.
  81 If the thread waiting on the object is not currently sleeping or the wait
  82 channel is not
  83 .Va selwait ,
  84 .Fn selwakeup
  85 will clear the
  86 .Dv TDF_SELECT
  87 flag which should be noted by
  88 .Xr select 2
  89 and
  90 .Xr poll 2
  91 when they wake up.
  92 .Pp
  93 .Fn seldrain
  94 will flush the waiters queue on a specified object before its
  95 destruction.
  96 The object handling code must ensure that
  97 .Fa *sip
  98 cannot be used once
  99 .Fn seldrain
 100 has been called.
 101 .Pp
 102 The contents of
 103 .Fa *sip
 104 must be zeroed, such as by softc initialization, before any call to
 105 .Fn selrecord
 106 or
 107 .Fn selwakeup ,
 108 otherwise a panic may occur.
 109 .Fn selwakeup
 110 acquires and releases
 111 .Va sellock
 112 and may acquire and release
 113 .Va sched_lock .
 114 .Fn seldrain
 115 could usually be just a wrapper for
 116 .Fn selwakeup ,
 117 but consumers should not generally rely on this feature.
 118 .Sh SEE ALSO
 119 .Xr poll 2 ,
 120 .Xr select 2
 121 .Sh AUTHORS
 122 .An -nosplit
 123 This manual page was written by
 124 .An Chad David Aq davidc@FreeBSD.org
 125 and
 126 .An Alfred Perlstein Aq alfred@FreeBSD.org .