STREAMS-UX Programmer's Guide (February 2007)

Messages

Message Processing and Flow Control

Chapter 3

Watermarks

Each queue is associated with the following watermarks and counter to manage the amount of data

accumulated in the message queue:

q_hiwat High watermark

q_lowat Low watermark

q_count Counter

When a message is placed onto the message queue, STREAMS increments q_count by the size of the

message. When a message is removed from the message queue, STREAMS decrements the q_count

accordingly.

The high watermark defines the maximum amount of data in bytes that can be accumulated in the message

queue. Once the accumulated data in the message queue reaches the high watermark, STREAMS sets the

QFULL flag to indicate that this message queue is full. When the message queue is full, the queue is under flow

control.

The high watermark is a soft limit. Hence, STREAMS allows the accumulated data to grow above the high

watermark if the preceding queue ignores the flow control condition. The low watermark defines the point

where STREAMS resets the queue full condition. That is, when the accumulated data in the message queue

reaches the low watermark, STREAMS resets the QFULL flag.

Set the high and low watermarks as follows:

1. Specify the high and low watermarks in the mi_hiwat and mi_lowat fields of the module_info structure.

These values are set independently for the read queue and the write queue. Once an instance of the

module is allocated, the q_hiwat and the q_lowat are initialized to the values specified in mi_hiwat and

mi_lowat fields.

When q_band is allocated for the band messages, the corresponding qb_hiwat and qb_lowat for each

band are defaulted to equal to the value of q_hiwat and q_lowat.

2. Dynamically change the high and low watermarks at run time by using the

strqset

() utility.

Checking Data Flow Condition

STREAMS provides the canput (), bcanput (), canputnext () and bcanputnext () utilities to check the flow

control condition. Their definition are available in the “Message Processing Utilities” section.

The module implementing flow control usually checks the flow control condition before it passes the message

to its next queue. HP recommends that high priority messages are not flow controlled. However, if high

priority messages are placed onto the message queue, they will be read and processed before other messages

in the queue.

Implementing flow control is optional. For example, Figure 3-3, “Flow Control,” shows that queue A and

queue C implement flow control, queue B is not flow controlled.