queue(9S) Structure

As previously discussed, messages are ordered in message queues. Message queues, message priority, service procedures, and basic flow control all combine in STREAMS. A service procedure processes the messages in its queue. If there is no service procedure for a queue, putq(9F) does not schedule the queue to be run. The module developer must ensure that the messages in the queue are processed. Message priority and flow control are associated with message queues.

The queue structure is defined in stream.h as the typedef queue_t, and has the following public elements:

struct  qinit   *q_qinfo;       /* procs and limits for queue */
struct  msgb    *q_first;       /* first data block */
struct  msgb    *q_last;        /* last data block */
struct  queue   *q_next;        /* Q of next stream */
struct  queue   *q_link;        /* to next Q for scheduling */
void            *q_ptr;         /* to private data structure */
size_t          q_count;        /* number of bytes on Q */
uint            q_flag;         /* queue state */
ssize_t         q_minpsz;       /* min packet size accepted by this module */
ssize_t         q_maxpsz;       /* max packet size accepted by this module */
size_t          q_hiwat;        /* queue high-water mark */
size_t          q_lowat;        /* queue low-water mark */

q_first points to the first message on the queue, and q_last points to the last message on the queue. q_count is used in flow control and contains the total number of bytes contained in normal and high-priority messages in band 0 of this queue. Each band is flow controlled individually and has its own count. See "qband(9S) Structure " for more details. qsize(9F) can be used to determine the total number of messages on the queue. q_flag indicates the state of the queue. See Table 7-3 for the definition of these flags.

q_minpsz contains the minimum packet size accepted by the queue, and q_maxpsz contains the maximum packet size accepted by the queue. These are suggested limits, and some implementations of STREAMS may not enforce them. The SunOS^TM Stream head enforces these values but is voluntary at the module level. Design modules to handle messages of any size.

q_hiwat indicates the limiting maximum number of bytes that can be put on a queue before flow control occurs. q_lowat indicates the lower limit where STREAMS flow control is released.

q_ptr is the element of the queue structure where modules can put values or pointers to data structures that are private to the module. This data can include any information required by the module for processing messages passed through the module, such as state information, module IDs, routing tables, and so on. Effectively, this element can be used any way the module or driver writer chooses. q_ptr can be accessed or changed directly by the driver, and is typically initialized in the open(9E) routine.

When a queue pair is allocated, streamtab initializes q_qinfo, and module_info initializes q_minpsz, q_maxpsz, q_hiwat, and q_lowat. Copying values from the module_info structure allows them to be changed in the queue without modifying the streamtab and module_info values.

Queue Flags

Be aware of the following queue flags. See queue(9S).