lib/libc/sys/_lwp_park.2

   1 .\"     $NetBSD: _lwp_park.2,v 1.7 2008/04/30 13:10:51 martin Exp $
   2 .\"
   3 .\" Copyright (c) 2003, 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Jason R. Thorpe of Wasabi Systems, Inc, and by Andrew Doran.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 25, 2007
  31 .Dt _LWP_PARK 2
  32 .Os
  33 .Sh NAME
  34 .Nm _lwp_park
  35 .Nd wait interruptably in the kernel
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In lwp.h
  40 .Ft int
  41 .Fn _lwp_park "const struct timespec *abstime" "lwpid_t unpark" "const void *hint" "const void *unparkhint"
  42 .Sh DESCRIPTION
  43 .Fn _lwp_park
  44 can be used to synchronize access to resources among multiple light-weight
  45 processes.
  46 It causes the calling LWP to wait interruptably in the kernel, until one
  47 of the following conditions is met:
  48 .Bl -bullet
  49 .It
  50 The
  51 .Fa abstime
  52 argument is non-NULL, and the absolute UTC time it specifies has passed.
  53 .It
  54 The LWP receives a directed signal posted using
  55 .Fn _lwp_kill ,
  56 or is elected to handle a signal on behalf of its containing process.
  57 .It
  58 The LWP is awoken by another LWP in the same process that has made
  59 a call to
  60 .Fn _lwp_wakeup .
  61 .It
  62 The LWP is awoken by another LWP in the same process that has made
  63 a call to
  64 .Fn _lwp_unpark
  65 or
  66 .Fn _lwp_unpark_all .
  67 .El
  68 .Pp
  69 The preferred method to awaken an LWP sleeping as a result of a call
  70 to
  71 .Fn _lwp_park
  72 is to make a call to
  73 .Fn _lwp_unpark ,
  74 or
  75 .Fn _lwp_unpark_all .
  76 The
  77 .Fn _lwp_wakeup
  78 system call is a more general facility, and requires more resources
  79 to execute.
  80 .Pp
  81 The optional
  82 .Fa hint
  83 argument specifies the address of object upon which the LWP is
  84 synchronizing.
  85 When the
  86 .Fa hint
  87 value is matched between calls to
  88 .Fn _lwp_park
  89 and
  90 .Fn _lwp_unpark
  91 or
  92 .Fn _lwp_unpark_all ,
  93 it may reduce the time necessary for the system to resume execution
  94 of waiting LWPs.
  95 .Pp
  96 The
  97 .Fa unpark
  98 and
  99 .Fa unparkhint
 100 arguments can be used to fold a park operation and unpark operation into a
 101 single system call.
 102 If
 103 .Fa unpark
 104 is non-zero, the system will behave as if the following call had been made
 105 before the calling thread begins to wait:
 106 .Bd -literal
 107         _lwp_unpark(unpark, unparkhint);
 108 .Ed
 109 .Sh RETURN VALUES
 110 .Fn _lwp_park
 111 may return a value of 0.
 112 Otherwise, \-1 is returned and
 113 .Va errno
 114 is set to provide more information.
 115 .Sh ERRORS
 116 .Bl -tag -width [EINVAL]
 117 .It Bq Er EALREADY
 118 A request was made to wake the LWP before it began to wait in
 119 the kernel.
 120 .It Bq Er EINTR
 121 The LWP has been awoken by a signal or by a call to one of the
 122 following functions:
 123 .Fn _lwp_unpark ,
 124 .Fn _lwp_unpark_all ,
 125 .Fn _lwp_wakeup .
 126 .It Bq Er EINVAL
 127 The time value specified by
 128 .Fa abstime
 129 is invalid.
 130 .It Bq Er ESRCH
 131 No LWP can be found in the current process corresponding to
 132 .Fa unpark .
 133 .It Bq Er ETIMEDOUT
 134 The UTC time specified by
 135 .Fa abstime
 136 has passed.
 137 .El
 138 .Sh SEE ALSO
 139 .Xr _lwp_unpark 2 ,
 140 .Xr _lwp_unpark_all 2 ,
 141 .Xr _lwp_wakeup 2
 142 .Sh HISTORY
 143 The
 144 .Fn _lwp_park
 145 system call first appeared in
 146 .Nx 5.0 .