STREAMS Flow Control

Even on a well-designed system, general system delays, malfunctions, and excessive accumulation on one or more streams can cause the message buffer pools to become depleted. Additionally, processing bursts can arise when a service procedure in one module has a long message queue and processes all its messages in one pass. STREAMS provides an independent mechanism to guard its message buffer pools from being depleted and to minimize long processing bursts at any one module.

Note: Flow control is applied only to normal priority messages.

The flow control mechanism is local to each stream and is advisory (voluntary), and it limits the number of characters that can be queued for processing at any QUEUE in a stream. This mechanism limits the buffers and related processing at any one QUEUE and in any one stream, but does not consider buffer pool levels or buffer usage in other streams.

The advisory mechanism operates between the two nearest QUEUEs in a stream containing service procedures. Messages are generally held on a message queue only if a service procedure is present in the associated QUEUE.

Messages accumulate at a QUEUE when its service procedure processing does not keep pace with the message arrival rate, or when the procedure is blocked from placing its messages on the following stream component by the flow-control mechanism. Pushable modules contain independent upstream and downstream limits, which are set when a developer specifies high-water and low-water control values for the QUEUE. The stream head contains a preset upstream limit (which can be modified by a special message sent from downstream) and a driver may contain a downstream limit.

STREAMS flow control operates in the following order:

1. Each time a STREAMS message-handling routine (for example, the putq utility) adds or removes a message from a message queue in a QUEUE, the limits are checked. STREAMS calculates the total size of all message blocks on the message queue.
2. The total is compared to the QUEUE high-water and low-water values. If the total exceeds the high-water value, an internal full indicator is set for the QUEUE. The operation of the service procedure in this QUEUE is not affected if the indicator is set, and the service procedure continues to be scheduled.
3. The next part of flow control processing occurs in the nearest preceding QUEUE that contains a service procedure. In the Flow Control Diagram, if D is full and C has no service procedure, then B is the nearest preceding QUEUE.
4. In the Flow Control Diagram, the service procedure in B uses a STREAMS utility routine to see if a QUEUE ahead is marked full. If messages cannot be sent, the scheduler blocks the service procedure in B from further execution. B remains blocked until the low-water mark of the full QUEUE D is reached.
5. While B is blocked (in the Flow Control Diagram), any nonpriority messages that arrive at B will accumulate on its message queue (recall that priority messages are not blocked). In turn, B can reach a full state and the full condition will propagate back to the last module in the stream.
6. When the service procedure processing on D (in the Flow Control Diagram) causes the message block total to fall below the low-water mark, the full indicator is turned off. Then, STREAMS automatically schedules the nearest preceding blocked QUEUE (in this case, B) and gets things moving again. This automatic scheduling is known as back-enabling a QUEUE.

To use flow control, a developer need only call the utility that tests if a full condition exists ahead (for example, the canput utility), and perform some housekeeping if it does. Everything else is automatically handled by STREAMS.

See "STREAMS Messages" for more information about the STREAMS message-passing scheme.