5025 import and use mandoc
Reviewed by: Hans Rosenfeld <hans.rosenfeld@nexenta.com>
Reviewed by: Igor Kozhukhov <ikozhukhov@gmail.com>
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Albert Lee <trisk@nexenta.com>
Approved by: TBD

          --- old/usr/src/man/man9f/rwlock.9f
          +++ new/usr/src/man/man9f/rwlock.9f

   1    1  '\" te
   2    2  .\"  Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved
   3    3  .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
   4    4  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5    5  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6    6  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7    7  .TH RWLOCK 9F "Sep 19, 2013"
   8    8  .SH NAME
   9    9  rwlock, rw_init, rw_destroy, rw_enter, rw_exit, rw_tryenter, rw_downgrade,
  10   10  rw_tryupgrade, rw_read_locked \- readers/writer lock functions
  11   11  .SH SYNOPSIS
  12   12  .LP
  13   13  .nf
  14   14  #include <sys/ksynch.h>
  15   15  
  16   16  
  17   17  
  18   18  \fBvoid\fR \fBrw_init\fR(\fBkrwlock_t *\fR\fIrwlp\fR, \fBchar *\fR\fIname\fR, \fBkrw_type_t\fR \fItype\fR, \fBvoid *\fR\fIarg\fR);
  19   19  .fi
  20   20  
  21   21  .LP
  22   22  .nf
  23   23  \fBvoid\fR \fBrw_destroy\fR(\fBkrwlock_t *\fR\fIrwlp\fR);
  24   24  .fi
  25   25  
  26   26  .LP
  27   27  .nf
  28   28  \fBvoid\fR \fBrw_enter\fR(\fBkrwlock_t *\fR\fIrwlp\fR, \fBkrw_t\fR \fIenter_type\fR);
  29   29  .fi
  30   30  
  31   31  .LP
  32   32  .nf
  33   33  \fBvoid\fR \fBrw_exit\fR(\fBkrwlock_t *\fR\fIrwlp\fR);
  34   34  .fi
  35   35  
  36   36  .LP
  37   37  .nf
  38   38  \fBint\fR \fBrw_tryenter\fR(\fBkrwlock_t *\fR\fIrwlp\fR, \fBkrw_t\fR \fIenter_type\fR);
  39   39  .fi
  40   40  
  41   41  .LP
  42   42  .nf
  43   43  \fBvoid\fR \fBrw_downgrade\fR(\fBkrwlock_t *\fR\fIrwlp\fR);
  44   44  .fi
  45   45  
  46   46  .LP
  47   47  .nf
  48   48  \fBint\fR \fBrw_tryupgrade\fR(\fBkrwlock_t *\fR\fIrwlp\fR);
  49   49  .fi
  50   50  
  51   51  .LP
  52   52  .nf
  53   53  \fBint\fR \fBrw_read_locked\fR(\fBkrwlock_t *\fR\fIrwlp\fR);
  54   54  .fi
  55   55  
  56   56  .SH INTERFACE LEVEL
  57   57  .sp
  58   58  .LP
  59   59  Solaris DDI specific (Solaris DDI).
  60   60  .SH PARAMETERS
  61   61  .sp
  62   62  .ne 2
  63   63  .na
  64   64  \fB\fIrwlp\fR\fR
  65   65  .ad
  66   66  .RS 14n
  67   67  Pointer to a \fBkrwlock_t\fR readers/writer lock.
  68   68  .RE
  69   69  
  70   70  .sp
  71   71  .ne 2
  72   72  .na
  73   73  \fB\fIname\fR\fR
  74   74  .ad
  75   75  .RS 14n
  76   76  Descriptive string. This is obsolete and should be \fBNULL\fR. (Non-null
  77   77  strings are legal, but they're a waste of kernel memory.)
  78   78  .RE
  79   79  
  80   80  .sp
  81   81  .ne 2
  82   82  .na
  83   83  \fB\fItype\fR\fR
  84   84  .ad
  85   85  .RS 14n
  86   86  Type of readers/writer lock.
  87   87  .RE
  88   88  
  89   89  .sp
  90   90  .ne 2
  91   91  .na
  92   92  \fB\fIarg\fR\fR
  93   93  .ad
  94   94  .RS 14n
  95   95  Type-specific argument for initialization function.
  96   96  .RE
  97   97  
  98   98  .sp
  99   99  .ne 2
 100  100  .na
 101  101  \fB\fIenter_type\fR\fR
 102  102  .ad
 103  103  .RS 14n
 104  104  One of the values \fBRW_WRITER\fR, \fBRW_READER\fR or
 105  105  \fBRW_READER_STARVEWRITER\fR, indicating whether the
 106  106  lock is to be acquired exclusively (\fBRW_WRITER\fR), non-exclusively
 107  107  (\fBRW_READER\fR) or non-exclusively without regard to any threads
 108  108  that may be blocked on exclusive access (\fBRW_READER_STARVEWRITER\fR).
 109  109  .RE
 110  110  
 111  111  .SH DESCRIPTION
 112  112  .sp
 113  113  .LP
 114  114  A multiple-readers, single-writer lock is represented by the \fBkrwlock_t\fR
 115  115  data type. This type of lock will allow many threads to have simultaneous
 116  116  read-only access to an object. Only one thread may have write access at any one
 117  117  time. An object that is searched more frequently than it is changed is a good
 118  118  candidate for a readers/writer lock.
 119  119  .sp
 120  120  .LP
 121  121  Readers/writer locks are slightly more expensive than mutex locks, and the
 122  122  advantage of multiple read access may not occur if the lock will only be held
 123  123  for a short time.
 124  124  .sp
 125  125  .LP
 126  126  The \fBrw_init()\fR function initializes a readers/writer lock. It is an error
 127  127  to initialize a lock more than once. The \fItype\fR argument should be set to
 128  128  \fBRW_DRIVER\fR. If the lock is used by the interrupt handler, the
 129  129  type-specific argument, \fIarg\fR, should be the interrupt priority returned
 130  130  from \fBddi_intr_get_pri\fR(9F) or \fBddi_intr_get_softint_pri\fR(9F). Note
 131  131  that arg should be the value of the interrupt priority cast by calling the
 132  132  \fBDDI_INTR_PRI\fR macro. If the lock is not used by any interrupt handler, the

 133  133  argument should be \fINULL.\fR
 134  134  .sp
 135  135  .LP
 136  136  The \fBrw_destroy()\fR function releases any resources that might have been
 137  137  allocated by \fBrw_init()\fR. It should be called before freeing the memory
 138  138  containing the lock. The lock must not be held by any thread when it is
 139  139  destroyed.
 140  140  .sp
 141  141  .LP
 142  142  The \fBrw_enter()\fR function acquires the lock, and blocks if necessary. If
 143      -\fIenter_type\fR is \fBRW_WRITER\fR, the caller blocks if any thread holds 
      143 +\fIenter_type\fR is \fBRW_WRITER\fR, the caller blocks if any thread holds
 144  144  the lock. If \fIenter_type\fR is \fBRW_READER\fR, the caller blocks if there
 145  145  is a writer or a thread attempting to enter for writing. If \fIenter_type\fR
 146  146  is \fBRW_READER_STARVEWRITER\fR, the caller blocks only if there is a writer;
 147  147  if the lock is held for reading and a thread is blocked attempting to enter
 148  148  for writing, the caller will acquire the lock as a reader instead of
 149  149  blocking on the pending writer.
 150  150  
 151  151  .sp
 152  152  .LP
 153  153  NOTE: It is a programming error for any thread to acquire an rwlock as

 154  154  \fBRW_READER\fR that it already holds. Doing so can deadlock the system: if
 155  155  thread R acquires the lock as \fBRW_READER\fR, then thread W tries to acquire
 156  156  the lock as a writer, W will set write-wanted and block. When R tries to get
 157  157  its second read hold on the lock, it will honor the write-wanted bit and block
 158  158  waiting for W; but W cannot run until R drops the lock. Thus threads R and W
 159  159  deadlock.  To opt out of this behavior -- that is, to safely allow a lock to
 160  160  be grabbed recursively as a reader -- the lock should be acquired as
 161  161  \fBRW_READER_STARVEWRITER\fR, which will allow R to get its second read hold
 162  162  without regard for the write-wanted bit set by W.  Note that the
 163  163  \fBRW_READER_STARVEWRITER\fR behavior will starve writers in the presence of
 164  164  infinite readers; it should be used with care, and only where the default
 165  165  \fBRW_READER\fR behavior is unacceptable.
 166  166  .sp
 167  167  .LP
 168  168  The \fBrw_exit()\fR function releases the lock and may wake up one or more
 169  169  threads waiting on the lock.
 170  170  .sp
 171  171  .LP
 172  172  The \fBrw_tryenter()\fR function attempts to enter the lock, like
 173  173  \fBrw_enter()\fR, but never blocks. It returns a non-zero value if the lock was
 174  174  successfully entered, and zero otherwise.
 175  175  .sp
 176  176  .LP
 177  177  A thread that holds the lock exclusively (entered with \fBRW_WRITER\fR), may
 178  178  call \fBrw_downgrade()\fR to convert to holding the lock non-exclusively (as if
 179  179  entered with \fBRW_READER\fR). One or more waiting readers may be unblocked.
 180  180  .sp
 181  181  .LP
 182  182  The \fBrw_tryupgrade()\fR function can be called by a thread that holds the
 183  183  lock for reading to attempt to convert to holding it for writing. This upgrade
 184  184  can only succeed if no other thread is holding the lock and no other thread is
 185  185  blocked waiting to acquire the lock for writing.
 186  186  .sp
 187  187  .LP
 188  188  The \fBrw_read_locked()\fR function returns non-zero if the calling thread
 189  189  holds the lock for read, and zero if the caller holds the lock for write. The
 190  190  caller must hold the lock. The system may panic if \fBrw_read_locked()\fR is
 191  191  called for a lock that isn't held by the caller.
 192  192  .SH RETURN VALUES
 193  193  .sp
 194  194  .ne 2
 195  195  .na
 196  196  \fB\fB0\fR\fR
 197  197  .ad
 198  198  .RS 12n
 199  199  \fBrw_tryenter()\fR could not obtain the lock without blocking.
 200  200  .RE
 201  201  
 202  202  .sp
 203  203  .ne 2
 204  204  .na
 205  205  \fB\fB0\fR\fR
 206  206  .ad
 207  207  .RS 12n
 208  208  \fBrw_tryupgrade()\fR was unable to perform the upgrade because of other
 209  209  threads holding or waiting to hold the lock.
 210  210  .RE
 211  211  
 212  212  .sp
 213  213  .ne 2
 214  214  .na
 215  215  \fB\fB0\fR\fR
 216  216  .ad
 217  217  .RS 12n
 218  218  \fBrw_read_locked()\fR returns \fB0\fR if the lock is held by the caller for
 219  219  write.
 220  220  .RE
 221  221  
 222  222  .sp
 223  223  .ne 2
 224  224  .na
 225  225  \fB\fBnon-zero\fR\fR
 226  226  .ad
 227  227  .RS 12n
 228  228  from \fBrw_read_locked()\fR if the lock is held by the caller for read.
 229  229  .RE
 230  230  
 231  231  .sp
 232  232  .ne 2
 233  233  .na
 234  234  \fB\fBnon-zero\fR\fR
 235  235  .ad
 236  236  .RS 12n
 237  237  successful return from \fBrw_tryenter()\fR or \fBrw_tryupgrade()\fR.
 238  238  .RE
 239  239  
 240  240  .SH CONTEXT
 241  241  .sp
 242  242  .LP
 243  243  These functions can be called from user, interrupt, or kernel context, except
 244  244  for \fBrw_init()\fR and \fBrw_destroy()\fR, which can be called from user
 245  245  context only.
 246  246  .SH SEE ALSO
 247  247  .sp
 248  248  .LP
 249  249  \fBcondvar\fR(9F), \fBddi_intr_alloc\fR(9F), \fBddi_intr_add_handler\fR(9F),
 250  250  \fBddi_intr_get_pri\fR(9F), \fBddi_intr_get_softint_pri\fR(9F),
 251  251  \fBmutex\fR(9F), \fBsemaphore\fR(9F)
 252  252  .sp
 253  253  .LP
 254  254  \fIWriting Device Drivers\fR
 255  255  .SH NOTES
 256  256  .sp
 257  257  .LP
 258  258  Compiling with \fB_LOCKTEST\fR or \fB_MPSTATS\fR defined no longer has any
 259  259  effect. To gather lock statistics, see \fBlockstat\fR(1M).

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX