share/man/man9e/srv.9e

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (c) 2002 Sun Microsystems, Inc. All Rights Reserved
   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 .\" 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 .\" 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 .TH SRV 9E "Nov 12, 1992"
   8 .SH NAME
   9 srv \- service queued messages
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/stream.h>
  15 #include <sys/stropts.h>
  16 #include <sys/ddi.h>
  17 #include <sys/sunddi.h>
  18
  19
  20
  21 \fBintprefix\fR\fBrsrv\fR(\fBqueue_t *\fR\fIq\fR/* read side */
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBintprefix\fR\fBwsrv\fR(\fBqueue_t *\fR\fIq\fR/* write side */
  27 .fi
  28
  29 .SH INTERFACE LEVEL
  30 .sp
  31 .LP
  32 Architecture independent level 1 (DDI/DKI). This entry point is required for
  33 \fBSTREAMS\fR.
  34 .SH ARGUMENTS
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIq\fR\fR
  39 .ad
  40 .RS 5n
  41 Pointer to the \fBqueue\fR(9S) structure.
  42 .RE
  43
  44 .SH DESCRIPTION
  45 .sp
  46 .LP
  47 The optional service \fBsrv()\fR routine may be included in a \fBSTREAMS
  48 \fRmodule or driver for many possible reasons, including:
  49 .RS +4
  50 .TP
  51 .ie t \(bu
  52 .el o
  53 to provide greater control over the flow of messages in a stream;
  54 .RE
  55 .RS +4
  56 .TP
  57 .ie t \(bu
  58 .el o
  59 to make it possible to defer the processing of some messages to avoid depleting
  60 system resources;
  61 .RE
  62 .RS +4
  63 .TP
  64 .ie t \(bu
  65 .el o
  66 to combine small messages into larger ones, or break large messages into
  67 smaller ones;
  68 .RE
  69 .RS +4
  70 .TP
  71 .ie t \(bu
  72 .el o
  73 to recover from resource allocation failure. A module's or driver's
  74 \fBput\fR(9E) routine can test for the availability of a resource, and if it is
  75 not available, enqueue the message for later processing by the \fBsrv()\fR
  76 routine.
  77 .RE
  78 .sp
  79 .LP
  80 A message is first passed to a module's or driver's \fBput\fR(9E) routine,
  81 which may or may not do some processing. It must then either:
  82 .RS +4
  83 .TP
  84 .ie t \(bu
  85 .el o
  86 Pass the message to the next stream component with \fBputnext\fR(9F).
  87 .RE
  88 .RS +4
  89 .TP
  90 .ie t \(bu
  91 .el o
  92 If a \fBsrv()\fR routine has been included, it may call \fBputq\fR(9F) to place
  93 the message on the queue.
  94 .RE
  95 .sp
  96 .LP
  97 Once a message has been enqueued, the \fBSTREAMS \fRscheduler controls the
  98 service routine's invocation. The scheduler calls the service routines in
  99 \fBFIFO \fRorder. The scheduler cannot guarantee a maximum delay \fBsrv()\fR
 100 routine to be called except that it will happen before any user level process
 101 are run.
 102 .sp
 103 .LP
 104 Every stream component (stream head, module or driver) has limit values it uses
 105 to implement flow control. Each component should check the tunable high and low
 106 water marks to stop and restart the flow of message processing. Flow control
 107 limits apply only between two adjacent components with \fBsrv()\fR routines.
 108 .sp
 109 .LP
 110 \fBSTREAMS \fR messages can be defined to have up to 256 different priorities
 111 to support requirements for multiple bands of data flow. At a minimum, a stream
 112 must distinguish between normal (priority zero) messages and high priority
 113 messages (such as \fBM_IOCACK\fR). High priority messages are always placed at
 114 the head of the \fBsrv()\fR routine's queue, after any other enqueued high
 115 priority messages. Next are messages from all included priority bands, which
 116 are enqueued in decreasing order of priority. Each priority band has its own
 117 flow control limits. If a flow controlled band is stopped, all lower priority
 118 bands are also stopped.
 119 .sp
 120 .LP
 121 Once the \fBSTREAMS \fRscheduler calls a \fBsrv()\fR routine, it must process
 122 all messages on its queue. The following steps are general guidelines for
 123 processing messages. Keep in mind that many of the details of how a \fBsrv()\fR
 124 routine should be written depend of the implementation, the direction of flow
 125 (upstream or downstream), and whether it is for a module or a driver.
 126 .RS +4
 127 .TP
 128 1.
 129 Use \fBgetq\fR(9F) to get the next enqueued message.
 130 .RE
 131 .RS +4
 132 .TP
 133 2.
 134 If the message is high priority, process (if appropriate) and pass to the
 135 next stream component with \fBputnext\fR(9F).
 136 .RE
 137 .RS +4
 138 .TP
 139 3.
 140 If it is not a high priority message (and therefore subject to flow
 141 control), attempt to send it to the next stream component with a \fBsrv()\fR
 142 routine. Use \fBbcanputnext\fR(9F) to determine if this can be done.
 143 .RE
 144 .RS +4
 145 .TP
 146 4.
 147 If the message cannot be passed, put it back on the queue with
 148 \fBputbq\fR(9F). If it can be passed, process (if appropriate) and pass with
 149 \fBputnext()\fR.
 150 .RE
 151 .SH RETURN VALUES
 152 .sp
 153 .LP
 154 Ignored.
 155 .SH SEE ALSO
 156 .sp
 157 .LP
 158 \fBput\fR(9E), \fBbcanput\fR(9F), \fBbcanputnext\fR(9F), \fBcanput\fR(9F),
 159 \fBcanputnext\fR(9F), \fBgetq\fR(9F), \fBnulldev\fR(9F), \fBputbq\fR(9F),
 160 \fBputnext\fR(9F), \fBputq\fR(9F), \fBqinit\fR(9S), \fBqueue\fR(9S)
 161 .sp
 162 .LP
 163 \fIWriting Device Drivers\fR
 164 .sp
 165 .LP
 166 \fISTREAMS Programming Guide\fR
 167 .SH WARNINGS
 168 .sp
 169 .LP
 170 Each stream module must specify a read and a write service \fBsrv()\fR routine.
 171 If a service routine is not needed (because the \fBput()\fR routine processes
 172 all messages), a \fBNULL\fR pointer should be placed in module's
 173 \fBqinit\fR(9S) structure. Do not use \fBnulldev\fR(9F) instead of the
 174 \fBNULL\fR pointer. Use of \fBnulldev\fR(9F) for a \fBsrv()\fR routine can
 175 result in flow control errors.