STREAMS-UX Programmer's Guide (February 2007)

Modules and Drivers

Flush Handling

Chapter 4

Flush Handling

The Flush operation involves removing of messages from read queue or write queue or both the queues. It can

be initiated by a user process or by a module/driver.

The M_FLUSH message is used in flush operation. All drivers and modules must handle the M_FLUSH messages.

STREAMS provides two utilities — flushq() and flushqband(), for drivers and modules to flush an entire

queue or just a specified band.

Stream head generates M_FLUSH message and send downstream upon receiving a I_FLUSH or I_FLUSHBAND

IOCTL. Modules/Drivers can initiate the flush operation by sending M_FLUSH upstream or downstream as

appropriate by setting the flags to indicate if read queue or write queue or both the queues to be flushed:

The first byte in the data buffer of an M_FLUSH message contains flags that determines the type of requested

flush operation. It can have the following values. If FLUSHBAND is set, then the second byte contains the

priority band value and only messages in this priority band are flushed.

FLUSHR Flush the read queue.

FLUSHW Flush the write queue.

FLUSHRW Flush both read and write queues.

FLUSHBAND Flush a specified priority band.

M_FLUSH Message Processing

Stream Head A stream head receiving an M_FLUSH message will check the flags first. If FLUSHR is set, it

flushes its read queue and turns off the FLUSHR bit. Following that, if FLUSHW is set, stream

head will turn the message around and send it downstream. If FLUSHW is not set, it frees the

message instead.

Module A module must flush read or write or both the queues based on type of the flags specified in

the first byte of the data buffer of an M_FLUSH message. After processing, it must send it to

the next component in the direction of data flow.

Driver A driver flushes its write queue if FLUSHW is set and unsets the FLUSHW flag. If FLUSHR is not

set, driver frees the message. Otherwise, it flushes its read queue and send the M_FLUSH

message upstream.

If a driver wants to flush the entire stream, it would flush its read/write queues. Following that it generates

an M_FLUSH message with FLUSHRW set in the first byte of the data buffer. This M_FLUSH message is sent

upstream for modules/stream head processing.

If a module wants to flush the entire stream, it would generate M_FLUSH message with FLUSHW set and sends

it upstream. Then, the module generate another M_FLUSH message with FLUSHR set and send it down the

write side of the stream.