usr/src/man/man9s/queue.9s

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   5 .\"  See the License for the specific language governing permissions and limitations under the License. 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
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH QUEUE 9S "Jan 10, 2006"
   8 .SH NAME
   9 queue \- STREAMS queue structure
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/stream.h>
  14 .fi
  15
  16 .SH INTERFACE LEVEL
  17 .sp
  18 .LP
  19 Architecture independent level 1 (DDI/DKI)
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 A \fBSTREAMS\fR driver or module consists of two \fBqueue\fR structures:
  24 \fIread\fR for upstream processing and \fIwrite\fR for downstream processing.
  25 The queue structure is the major building block of a stream.
  26 .SS "\fBqueue\fR Structure Members"
  27 .sp
  28 .LP
  29 The \fBqueue\fR structure is defined as type \fBqueue_t\fR. The structure can
  30 be accessed at any time from inside a \fBSTREAMS\fR entry point associated with
  31 that queue.
  32 .sp
  33 .in +2
  34 .nf
  35 struct    qinit   *q_qinfo;     /* queue processing procedure */
  36 struct    msgb    *q_first;     /* first message in queue */
  37 struct    msgb    *q_last;      /* last message in queue */
  38 struct    queue   *q_next;      /* next queue in stream */
  39 void              *q_ptr;       /* module-specific data */
  40 size_t             q_count;     /* number of bytes on queue */
  41 uint_t             q_flag;      /* queue state */
  42 ssize_t            q_minpsz;    /* smallest packet OK on queue */
  43 ssize_t            q_maxpsz;    /* largest packet OK on queue */
  44 size_t             q_hiwat;     /* queue high water mark */
  45 size_t             q_lowat;     /* queue low water mark */
  46 .fi
  47 .in -2
  48
  49 .sp
  50 .LP
  51 Contstraints and restrictions on the use of \fBq_flag\fR and \fBqueue_t\fR
  52 fields and the \fBq_next\fR values are detailed in the following sections.
  53 .SS "\fBq_flag\fR Field"
  54 .sp
  55 .LP
  56 The \fBq_flag\fR field must be used only to check the following flag values.
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fBQFULL\fR\fR
  61 .ad
  62 .RS 10n
  63 Queue is full.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBQREADR\fR\fR
  70 .ad
  71 .RS 10n
  72 Queue is used for upstream (read-side) processing.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBQUSE\fR\fR
  79 .ad
  80 .RS 10n
  81 Queue has been allocated.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBQENAB\fR\fR
  88 .ad
  89 .RS 10n
  90 Queue has been enabled for service by \fBqenable\fR(9F).
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBQNOENB\fR\fR
  97 .ad
  98 .RS 10n
  99 Queue will not be scheduled for service by \fBputq\fR(9F).
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBQWANTR\fR\fR
 106 .ad
 107 .RS 10n
 108 Upstream processing element wants to read from queue.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBQWANTW\fR\fR
 115 .ad
 116 .RS 10n
 117 Downstream processing element wants to write to queue.
 118 .RE
 119
 120 .SS "\fBqueue_t\fR Fields"
 121 .sp
 122 .LP
 123 Aside from \fBq_ptr\fR and \fBq_qinfo\fR, a module or driver must never assume
 124 that a \fBqueue_t\fR field value will remain unchanged across calls to
 125 \fBSTREAMS\fR entry points. In addition, many fields can change values inside a
 126 \fBSTREAMS\fR entry point, especially if the \fBSTREAMS\fR module or driver has
 127 perimeters that allow parallelism. See \fBmt-streams\fR(9F). Fields that are
 128 not documented below are private to the \fBSTREAMS\fR framework and must not be
 129 accessed.
 130 .RS +4
 131 .TP
 132 .ie t \(bu
 133 .el o
 134 The values of the \fBq_hiwat\fR, \fBq_lowat\fR, \fBq_minpsz\fR, and
 135 \fBq_maxpsz\fR fields can be changed at the discretion of the module or driver.
 136 As such, the stability of their values depends on the perimeter configuration
 137 associated with any routines that modify them.
 138 .RE
 139 .RS +4
 140 .TP
 141 .ie t \(bu
 142 .el o
 143 The values of the \fBq_first\fR, \fBq_last\fR, and \fBq_count\fR fields can
 144 change whenever \fBputq\fR(9F), \fBputbq\fR(9F), \fBgetq\fR(9F),
 145 \fBinsq\fR(9F), or \fBrmvq\fR(9F) is used on the queue. As such, the stability
 146 of their values depends on the perimeter configuration associated with any
 147 routines that call those \fBSTREAMS\fR functions.
 148 .RE
 149 .RS +4
 150 .TP
 151 .ie t \(bu
 152 .el o
 153 The \fBq_flag\fR field can change at any time.
 154 .RE
 155 .RS +4
 156 .TP
 157 .ie t \(bu
 158 .el o
 159 The \fBq_next\fR field will not change while inside a given \fBSTREAMS\fR entry
 160 point. Additional restrictions on the use of the \fBq_next\fR value are
 161 described in the next section.
 162 .RE
 163 .sp
 164 .LP
 165 A \fBSTREAMS\fR module or driver can assign any value to \fBq_ptr\fR. Typically
 166 \fBq_ptr\fR is used to point to module-specific per-queue state, allocated in
 167 \fBopen\fR(9E) and freed in \fBclose\fR(9E). The value or contents of
 168 \fBq_ptr\fR is never inspected by the \fBSTREAMS\fR framework.
 169 .sp
 170 .LP
 171 The initial values for \fBq_minpsz\fR, \fBq_maxpsz\fR, \fBq_hiwat\fR, and
 172 \fBq_lowat\fR are set using the \fBmodule_info\fR(9S) structure when
 173 \fBmod_install\fR(9F) is called. A \fBSTREAMS\fR\ module or driver can
 174 subsequently change the values of those fields as necessary. The remaining
 175 visible fields, \fBq_qinfo\fR, \fBq_first\fR, \fBq_last\fR, \fBq_next\fR,
 176 \fBq_count\fR, and \fBq_flag\fR, must never be modified by a module or driver.
 177 .sp
 178 .LP
 179 The Solaris DDI requires that \fBSTREAMS\fR modules and drivers obey the rules
 180 described on this page. Those that do not follow the rules can cause data
 181 corruption or system instability, and might change in behavior across patches
 182 or upgrades.
 183 .SS "\fBq_next\fR Restrictions"
 184 .sp
 185 .LP
 186 There are additional restrictions associated with the use of the \fBq_next\fR
 187 value. In particular, a \fBSTREAMS\fR module or driver:
 188 .RS +4
 189 .TP
 190 .ie t \(bu
 191 .el o
 192 Must not access the data structure pointed to by \fBq_next\fR.
 193 .RE
 194 .RS +4
 195 .TP
 196 .ie t \(bu
 197 .el o
 198 Must not rely on the value of \fBq_next\fR before calling \fBqprocson\fR(9F) or
 199 after calling \fBqprocsoff\fR(9F).
 200 .RE
 201 .RS +4
 202 .TP
 203 .ie t \(bu
 204 .el o
 205 Must not pass the value into any \fBSTREAMS\fR framework function other than
 206 \fBput\fR(9F), \fBcanput\fR(9F), \fBbcanput\fR(9F), \fBputctl\fR(9F),
 207 \fBputctl1\fR(9F). However, in all cases the "next" version of these functions,
 208 such as \fBputnext\fR(9F), should be preferred.
 209 .RE
 210 .RS +4
 211 .TP
 212 .ie t \(bu
 213 .el o
 214 Must not use the value to compare against queue pointers from other streams.
 215 However, checking \fBq_next\fR for NULL can be used to distinguish a module
 216 from a driver in code shared by both.
 217 .RE
 218 .SH SEE ALSO
 219 .sp
 220 .LP
 221 \fBclose\fR(9E), \fBopen\fR(9E), \fBbcanput\fR(9F), \fBcanput\fR(9F),
 222 \fBgetq\fR(9F), \fBinsq\fR(9F), \fBmod_install\fR(9F), \fBput\fR(9F),
 223 \fBputbq\fR(9F), \fBputctl\fR(9F), \fBputctl1\fR(9F), \fBputnext\fR(9F),
 224 \fBputq\fR(9F), \fBqprocsoff\fR(9F), \fBqprocson\fR(9F), \fBrmvq\fR(9F),
 225 \fBstrqget\fR(9F), \fBstrqset\fR(9F), \fBmodule_info\fR(9S), \fBmsgb\fR(9S),
 226 \fBqinit\fR(9S), \fBstreamtab\fR(9S)
 227 .sp
 228 .LP
 229 \fIWriting Device Drivers\fR
 230 .sp
 231 .LP
 232 \fISTREAMS Programming Guide\fR