usr/src/man/man9f/mt-streams.9f

   1 '\" te
   2 .\" Copyright (c) 2002, Sun Microsystems, Inc.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH MT-STREAMS 9F "May 5, 2009"
   7 .SH NAME
   8 mt-streams \- STREAMS multithreading
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/conf.h>
  13 .fi
  14
  15 .SH INTERFACE LEVEL
  16 .sp
  17 .LP
  18 Solaris DDI specific (Solaris DDI).
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 STREAMS drivers configure the degree of concurrency using the \fBcb_flag\fR
  23 field in the \fBcb_ops\fR structure (see \fBcb_ops\fR(9S)). The corresponding
  24 field for \fBSTREAMS \fRmodules is the \fBf_flag\fR in the \fBfmodsw\fR
  25 structure.
  26 .sp
  27 .LP
  28 For the purpose of restricting and controlling the concurrency in
  29 drivers/modules, we define the concepts of \fBinner\fR and \fBouter
  30 perimeters\fR. A driver/module can be configured either to have no perimeters,
  31 to have only an inner or an outer perimeter, or to have both an inner and an
  32 outer perimeter. Each perimeter acts as a readers-writers lock, that is, there
  33 can be multiple concurrent readers or a single writer. Thus, each perimeter can
  34 be entered in two modes: shared (reader) or exclusive (writer). The mode
  35 depends on the perimeter configuration and can be different for the different
  36 \fBSTREAMS \fRentry points ( \fBopen\fR(9E), \fBclose\fR(9E), \fBput\fR(9E), or
  37 \fBsrv\fR(9E)).
  38 .sp
  39 .LP
  40 The concurrency for the different entry points is (unless specified otherwise)
  41 to enter with exclusive access at the inner perimeter (if present) and shared
  42 access at the outer perimeter (if present).
  43 .sp
  44 .LP
  45 The perimeter configuration consists of flags that define the presence and
  46 scope of the inner perimeter, the presence of the outer perimeter (which can
  47 only have one scope), and flags that modify the default concurrency for the
  48 different entry points.
  49 .sp
  50 .LP
  51 All MT safe modules/drivers specify the \fBD_MP\fR flag.
  52 .SS "Inner Perimeter Flags"
  53 .sp
  54 .LP
  55 The inner perimeter presence and scope are controlled by the mutually exclusive
  56 flags:
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fBD_MTPERQ\fR\fR
  61 .ad
  62 .RS 21n
  63 The module/driver has an inner perimeter around each queue.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBD_MTQPAIR\fR\fR
  70 .ad
  71 .RS 21n
  72 The module/driver has an inner perimeter around each read/write pair of queues.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBD_MTPERMOD\fR\fR
  79 .ad
  80 .RS 21n
  81 The module/driver has an inner perimeter that encloses all the
  82 module's/driver's queues.
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fBNone of the above\fR
  89 .ad
  90 .RS 21n
  91 The module/driver has no inner perimeter.
  92 .RE
  93
  94 .SS "Outer Perimeter Flags"
  95 .sp
  96 .LP
  97 The outer perimeter presence is configured using:
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBD_MTOUTPERIM\fR\fR
 102 .ad
 103 .RS 16n
 104 In addition to any inner perimeter, the module/driver has an outer perimeter
 105 that encloses all the module's/driver's queues. This can be combined with all
 106 the inner perimeter options except \fBD_MTPERMOD.\fR
 107 .RE
 108
 109 .sp
 110 .LP
 111 Note that acquiring exclusive access at the outer perimeter (that is, using
 112 \fBqwriter\fR(9F) with the \fBPERIM_OUTER\fR flag) can incur significant
 113 performance penalties, which grow linearly with the number of open instances of
 114 the module or driver in the system.
 115 .sp
 116 .LP
 117 The default concurrency can be modified using:
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBD_MTPUTSHARED\fR\fR
 122 .ad
 123 .RS 17n
 124 This flag modifies the default behavior when \fBput\fR(9E) procedure are
 125 invoked so that the inner perimeter is entered shared instead of exclusively.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBD_MTOCEXCL\fR\fR
 132 .ad
 133 .RS 17n
 134 This flag modifies the default behavior when \fBopen\fR(9E) and \fBclose\fR(9E)
 135 procedures are invoked so the outer perimeter is entered exclusively instead of
 136 shared.
 137 .sp
 138 Note that drivers and modules using this flag can cause significant system
 139 performance degradation during stream open or close when many instances of the
 140 driver or module are in use simultaneously. For this reason, use of this flag
 141 is discouraged. Instead, since \fBopen\fR(9E) and \fBclose\fR(9E) both execute
 142 with user context, developers are encouraged to use traditional synchronization
 143 routines such as \fBcv_wait_sig\fR(9F) to coordinate with other open instances
 144 of the module or driver.
 145 .RE
 146
 147 .sp
 148 .LP
 149 The module/driver can use \fBqwait\fR(9F) or \fBqwait_sig()\fR in the
 150 \fBopen\fR(9E) and \fBclose\fR(9E) procedures if it needs to wait "outside" the
 151 perimeters.
 152 .sp
 153 .LP
 154 The module/driver can use \fBqwriter\fR(9F) to upgrade the access at the inner
 155 or outer perimeter from shared to exclusive.
 156 .sp
 157 .LP
 158 The use and semantics of \fBqprocson()\fR and \fBqprocsoff\fR(9F) is
 159 independent of the inner and outer perimeters.
 160 .SH SEE ALSO
 161 .sp
 162 .LP
 163 \fBclose\fR(9E), \fBopen\fR(9E), \fBput\fR(9E), \fBsrv\fR(9E),
 164 \fBqprocsoff\fR(9F), \fBqprocson\fR(9F), \fBqwait\fR(9F), \fBqwriter\fR(9F),
 165 \fBcb_ops\fR(9S)
 166 .sp
 167 .LP
 168 \fISTREAMS Programming Guide\fR
 169 .sp
 170 .LP
 171 \fIWriting Device Drivers\fR