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 be to 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 as the typedef queue_t, and has the following public elements:

struct qinit			*q_qinfo;	/* procedure and info for queue */
struct msgb				*q_first;	/* head of message queue */
struct msgb				*q_last;		/* tail of message queue */
struct queue			*q_next;		/* next queue in stream */
void						*q_ptr;		/* module private data pointer */
ulong						q_count;		/* number of bytes on queue */
ulong						q_flag;		/* queue state */
long						q_minpsz;	/* min packet size accepted by this module */
long						q_maxpsz;	/* max packet size accepted by this module */
ulong						q_hiwat;		/* queue high water mark */
ulong						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 the "Queue Flags" section 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 this 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).