queue(9s) - osol9

1queue(9S)                 Data Structures for Drivers                queue(9S)
2
3
4

NAME

6       queue - STREAMS queue structure
7

SYNOPSIS

9       #include <sys/stream.h>
10
11

INTERFACE LEVEL

13       Architecture independent level 1 (DDI/DKI)
14

DESCRIPTION

16       A  STREAMS  driver or module consists of two queue structures: read for
17       upstream processing and write  for  downstream  processing.  The  queue
18       structure is the major building block of a stream.
19
20   queue Structure Members
21       The  queue  structure  is defined as type queue_t. The structure can be
22       accessed at any time from inside a STREAMS entry point associated  with
23       that queue.
24
25         struct    qinit   *q_qinfo;     /* queue processing procedure */
26         struct    msgb    *q_first;     /* first message in queue */
27         struct    msgb    *q_last;      /* last message in queue */
28         struct    queue   *q_next;      /* next queue in stream */
29         void              *q_ptr;       /* module-specific data */
30         size_t             q_count;     /* number of bytes on queue */
31         uint_t             q_flag;      /* queue state */
32         ssize_t            q_minpsz;    /* smallest packet OK on queue */
33         ssize_t            q_maxpsz;    /* largest packet OK on queue */
34         size_t             q_hiwat;     /* queue high water mark */
35         size_t             q_lowat;     /* queue low water mark */
36
37
38
39       Contstraints  and  restrictions on the use of q_flag and queue_t fields
40       and the q_next values are detailed in the following sections.
41
42   q_flag Field
43       The q_flag field must be used only to check the following flag values.
44
45       QFULL     Queue is full.
46
47
48       QREADR    Queue is used for upstream (read-side) processing.
49
50
51       QUSE      Queue has been allocated.
52
53
54       QENAB     Queue has been enabled for service by qenable(9F).
55
56
57       QNOENB    Queue will not be scheduled for service by putq(9F).
58
59
60       QWANTR    Upstream processing element wants to read from queue.
61
62
63       QWANTW    Downstream processing element wants to write to queue.
64
65
66   queue_t Fields
67       Aside from q_ptr and q_qinfo, a module or driver must never assume that
68       a  queue_t  field  value  will remain unchanged across calls to STREAMS
69       entry points. In addition, many  fields  can  change  values  inside  a
70       STREAMS  entry  point,  especially  if the STREAMS module or driver has
71       perimeters that allow parallelism. See mt-streams(9F). Fields that  are
72       not  documented below are private to the STREAMS framework and must not
73       be accessed.
74
75           o      The values of the q_hiwat, q_lowat, q_minpsz,  and  q_maxpsz
76                  fields  can  be  changed  at the discretion of the module or
77                  driver. As such, the stability of their  values  depends  on
78                  the  perimeter  configuration  associated  with any routines
79                  that modify them.
80
81           o      The values of the q_first, q_last, and  q_count  fields  can
82                  change  whenever putq(9F), putbq(9F), getq(9F), insq(9F), or
83                  rmvq(9F) is used on the queue. As  such,  the  stability  of
84                  their  values depends on the perimeter configuration associ‐
85                  ated with any routines that call those STREAMS functions.
86
87           o      The q_flag field can change at any time.
88
89           o      The q_next field  will  not  change  while  inside  a  given
90                  STREAMS  entry  point. Additional restrictions on the use of
91                  the q_next value are described in the next section.
92
93
94       A STREAMS module or driver can assign any  value  to  q_ptr.  Typically
95       q_ptr is used to point to module-specific per-queue state, allocated in
96       open(9E) and freed in close(9E). The value  or  contents  of  q_ptr  is
97       never inspected by the STREAMS framework.
98
99
100       The initial values for q_minpsz, q_maxpsz, q_hiwat, and q_lowat are set
101       using the module_info(9S) structure when mod_install(9F) is  called.  A
102       STREAMS module  or  driver  can subsequently change the values of those
103       fields as necessary. The remaining visible  fields,  q_qinfo,  q_first,
104       q_last, q_next, q_count, and q_flag, must never be modified by a module
105       or driver.
106
107
108       The Solaris DDI requires that STREAMS  modules  and  drivers  obey  the
109       rules  described  on  this page. Those that do not follow the rules can
110       cause data corruption or system instability, and might change in behav‐
111       ior across patches or upgrades.
112
113   q_next Restrictions
114       There are additional restrictions associated with the use of the q_next
115       value. In particular, a STREAMS module or driver:
116
117           o      Must not access the data structure pointed to by q_next.
118
119           o      Must not rely on the value of q_next before  calling  qproc‐
120                  son(9F) or after calling qprocsoff(9F).
121
122           o      Must  not pass the value into any STREAMS framework function
123                  other than  put(9F),  canput(9F),  bcanput(9F),  putctl(9F),
124                  putctl1(9F).  However,  in  all  cases the "next" version of
125                  these functions, such as putnext(9F), should be preferred.
126
127           o      Must not use the value to  compare  against  queue  pointers
128                  from other streams. However, checking q_next for NULL can be
129                  used to distinguish a module from a driver in code shared by
130                  both.
131

NAME

SYNOPSIS

INTERFACE LEVEL

DESCRIPTION

SEE ALSO