share/man/man9f/testb.9f

   1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (c) 2006, Sun Microsystems, Inc.
   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 TESTB 9F "Jan 16, 2006"
   8 .SH NAME
   9 testb \- check for an available buffer
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/stream.h>
  14
  15
  16
  17 \fBint\fR \fBtestb\fR(\fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Architecture independent level 1 (DDI/DKI).
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIsize\fR\fR
  29 .ad
  30 .RS 8n
  31 Size of the requested buffer.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIpri\fR\fR
  38 .ad
  39 .RS 8n
  40 Priority of the allocb request.
  41 .RE
  42
  43 .SH DESCRIPTION
  44 .sp
  45 .LP
  46 The \fBtestb()\fR function checks to see if an \fBallocb\fR(9F) call is likely
  47 to succeed if a buffer of \fBsize\fR bytes at priority \fIpri\fR is requested.
  48 Even if \fBtestb()\fR returns successfully, the call to \fBallocb\fR(9F) can
  49 fail. The \fIpri\fR argument is no longer used, but is retained for
  50 compatibility.
  51 .SH RETURN VALUES
  52 .sp
  53 .LP
  54 Returns \fB1\fR if a buffer of the requested size is available, and \fB0\fR if
  55 one is not.
  56 .SH CONTEXT
  57 .sp
  58 .LP
  59 The \fBtestb()\fR function can be called user, interrupt, or kernel context.
  60 .SH EXAMPLES
  61 .LP
  62 \fBExample 1 \fR\fBtestb()\fR example
  63 .sp
  64 .LP
  65 In a service routine, if \fBcopymsg\fR(9F) fails (line 6), the message is put
  66 back on the queue (line 7) and a routine, \fBtryagain\fR, is scheduled to be
  67 run in one tenth of a second. Then the service routine returns.
  68
  69 .sp
  70 .LP
  71 When the \fBtimeout\fR(9F) function runs, if there is no message on the front
  72 of the queue, it just returns. Otherwise, for each message block in the first
  73 message, check to see if an allocation would succeed.  If the number of message
  74 blocks equals the number we can allocate, then enable the service procedure.
  75 Otherwise, reschedule \fBtryagain\fR to run again in another tenth of a second.
  76 Note that \fBtryagain\fR is merely an approximation. Its accounting may be
  77 faulty. Consider the case of a message comprised of two 1024-byte message
  78 blocks. If there is only one free 1024-byte message block and no free 2048-byte
  79 message blocks, then \fBtestb()\fR will still succeed twice. If no message
  80 blocks are freed of these sizes before the service procedure runs again, then
  81 the \fBcopymsg\fR(9F) will still fail. The reason \fBtestb()\fR is used here is
  82 because it is significantly faster than calling \fBcopymsg\fR. We must minimize
  83 the amount of time spent in a \fBtimeout()\fR routine.
  84
  85 .sp
  86 .in +2
  87 .nf
  88 \fB1  xxxsrv(q)
  89  2      queue_t *q;
  90  3  {
  91  4      mblk_t *mp;
  92  5      mblk_t *nmp;
  93         ...
  94  6      if ((nmp = copymsg(mp)) == NULL) {
  95  7              putbq(q, mp);
  96  8              timeout(tryagain, (intptr_t)q, drv_usectohz(100000));
  97  9              return;
  98 10      }
  99         ...
 100 11  }
 101 12
 102 13  tryagain(q)
 103 14      queue_t *q;
 104 15  {
 105 16      register int can_alloc = 0;
 106 17      register int num_blks = 0;
 107 18      register mblk_t *mp;
 108 19
 109 20      if (!q->q_first)
 110 21              return;
 111 22      for (mp = q->q_first; mp; mp = mp->b_cont) {
 112 23              num_blks++;
 113 24              can_alloc += testb((mp->b_datap->db_lim -
 114 25                  mp->b_datap->db_base), BPRI_MED);
 115 26      }
 116 27      if (num_blks == can_alloc)
 117 28              qenable(q);
 118 29      else
 119 30              timeout(tryagain, (intptr_t)q, drv_usectohz(100000));
 120 31  }\fR
 121 .fi
 122 .in -2
 123
 124 .SH SEE ALSO
 125 .sp
 126 .LP
 127 \fBallocb\fR(9F), \fBbufcall\fR(9F), \fBcopymsg\fR(9F), \fBtimeout\fR(9F)
 128 .sp
 129 .LP
 130 \fIWriting Device Drivers\fR
 131 .sp
 132 .LP
 133 \fISTREAMS Programming Guide\fR
 134 .SH NOTES
 135 .sp
 136 .LP
 137 The \fIpri\fR argument is provided for compatibility only. Its value is
 138 ignored.