1bufmod(7M) STREAMS Modules bufmod(7M)
2
6 bufmod - STREAMS Buffer Module
7
9 #include <sys/bufmod.h>
10 ioctl(fd, I_PUSH, "bufmod");
13
16 bufmod is a STREAMS module that buffers incoming messages, reducing the
17 number of system calls and the associated overhead required to read and
18 process them. Although bufmod was originally designed to be used in
19 conjunction with STREAMS-based networking device drivers, the version
20 described here is general purpose so that it can be used anywhere
21 STREAMS input buffering is required.
22 Read-side Behavior
24 The behavior of bufmod depends on various parameters and flags that can
25 be set and queried as described below under IOCTLS. bufmod collects
26 incoming M_DATA messages into chunks, passing each chunk upstream when
27 the chunk becomes full or the current read timeout expires. It option‐
28 ally converts M_PROTO messages to M_DATA and adds them to chunks as
29 well. It also optionally adds to each message a header containing a
30 timestamp, and a cumulative count of messages dropped on the stream
31 read side due to resource exhaustion or flow control. Thedefault set‐
32 tings of bufmod allow it to drop messages when flow control sets in or
33 resources are exhausted; disabling headers and explicitly requesting no
34 drops makes bufmod pass all messages through. Finally, bufmod is capa‐
35 ble of truncating upstream messages to a fixed, programmable length.
36 When a message arrives, bufmod processes it in several steps. The fol‐
39 lowing paragraphs discuss each step in turn.
40 Upon receiving a message from below, if the SB_NO_HEADER flag is not
43 set, bufmod immediately timestamps it and saves the current time value
44 for later insertion in the header described below.
45 Next, if SB_NO_PROTO_CVT is not set, bufmod converts all leading
48 M_PROTO blocks in the message to M_DATA blocks, altering only the mes‐
49 sage type field and leaving the contents alone.
50 It then truncates the message to the current snapshot length, which is
53 set with the SBIOCSSNAP ioctl described below.
54 Afterwards, if SB_NO_HEADER is not set, bufmod prepends a header to the
57 converted message. This header is defined as follows.
58 struct sb_hdr {
60 uint_t sbh_origlen;
61 uint_t sbh_msglen;
62 uint_t sbh_totlen;
63 uint_t sbh_drops;
64 #if defined(_LP64) || defined(_I32LPx)
65 struct timeval32 sbh_timestamp;
66 #else
67 struct timeval sbh_timestamp;
68 #endif /* !_LP64 */
69 };
70 The sbh_origlen field gives the message's original length before trun‐
74 cation in bytes. The sbh_msglen field gives the length in bytes of the
75 message after the truncation has been done. sbh_totlen gives the dis‐
76 tance in bytes from the start of the truncated message in the current
77 chunk (described below) to the start of the next message in the chunk;
78 the value reflects any padding necessary to insure correct data align‐
79 ment for the host machine and includes the length of the header itself.
80 sbh_drops reports the cumulative number of input messages that this
81 instance of bufmod has dropped due to flow control or resource exhaus‐
82 tion. In the current implementation message dropping due to flow con‐
83 trol can occur only if the SB_NO_DROPS flag is not set. (Note: this
84 accounts only for events occurring within bufmod, and does not count
85 messages dropped by downstream or by upstream modules.) The sbh_time‐
86 stamp field contains the message arrival time expressed as a struct
87 timeval.
88 After preparing a message, bufmod attempts to add it to the end of the
91 current chunk, using the chunk size and timeout values to govern the
92 addition. The chunk size and timeout values are set and inspected using
93 the ioctl() calls described below. If adding the new message would make
94 the current chunk grow larger than the chunk size, bufmod closes off
95 the current chunk, passing it up to the next module in line, and starts
96 a new chunk. If adding the message would still make the new chunk over‐
97 flow, the module passes it upward in an over-size chunk of its own.
98 Otherwise, the module concatenates the message to the end of the cur‐
99 rent chunk.
100 To ensure that messages do not languish forever in an accumulating
103 chunk, bufmod maintains a read timeout. Whenever this timeout expires,
104 the module closes off the current chunk and passes it upward. The mod‐
105 ule restarts the timeout period when it receives a read side data mes‐
106 sage and a timeout is not currently active. These two rules insure that
107 bufmod minimizes the number of chunks it produces during periods of
108 intense message activity and that it periodically disposes of all mes‐
109 sages during slack intervals, but avoids any timeout overhead when
110 there is no activity.
111 bufmod handles other message types as follows. Upon receiving an
114 M_FLUSH message specifying that the read queue be flushed, the module
115 clears the currently accumulating chunk and passes the message on to
116 the module or driver above. (Note: bufmod uses zero length M_CTL mes‐
117 sages for internal synchronization and does not pass them through.)
118 bufmod passes all other messages through unaltered to its upper neigh‐
119 bor, maintaining message order for non high priority messages by pass‐
120 ing up any accumulated chunk first.
121 If the SB_DEFER_CHUNK flag is set, buffering does not begin until the
124 second message is received within the timeout window.
125 If the SB_SEND_ON_WRITE flag is set, bufmod passes up the read side any
128 buffered data when a message is received on the write side.
129 SB_SEND_ON_WRITE and SB_DEFER_CHUNK are often used together.
130 Write-side Behavior
132 bufmod intercepts M_IOCTL messages for the ioctls described below. The
133 module passes all other messages through unaltered to its lower neigh‐
134 bor. If SB_SEND_ON_WRITE is set, message arrival on the writer side
135 suffices to close and transmit the current read side chunk.
136
138 bufmod responds to the following ioctls.
139 SBIOCSTIME Set the read timeout value to the value referred to by
141 the struct timeval pointer given as argument. Setting
142 the timeout value to zero has the side-effect of forc‐
143 ing the chunk size to zero as well, so that the module
144 will pass all incoming messages upward immediately upon
145 arrival. Negative values are rejected with an EINVAL
146 error.
147 SBIOCGTIME Return the read timeout in the struct timeval pointed
150 to by the argument. If the timeout has been cleared
151 with the SBIOCCTIME ioctl, return with an ERANGE error.
152 SBIOCCTIME Clear the read timeout, effectively setting its value
155 to infinity. This results in no timeouts being active
156 and the chunk being delivered when it is full.
157 SBIOCSCHUNK Set the chunk size to the value referred to by the
160 uint_t pointer given as argument. See Notes for a
161 description of effect on stream head high water mark.
162 SBIOCGCHUNK Return the chunk size in the uint_t pointed to by the
165 argument.
166 SBIOCSSNAP Set the current snapshot length to the value given in
169 the uint_t pointed to by the ioctl's final argument.
170 bufmod interprets a snapshot length value of zero as
171 meaning infinity, so it will not alter the message. See
172 Notes for a description of effect on stream head high
173 water mark.
174 SBIOCGSNAP Returns the current snapshot length in the uint_t
177 pointed to by the ioctl's final argument.
178 SBIOCSFLAGS Set the current flags to the value given in the uint_t
181 pointed to by the ioctl's final argument. Possible val‐
182 ues are a combination of the following.
183 SB_SEND_ON_WRITE Transmit the read side chunk on
185 arrival of a message on the write
186 side.
187 SB_NO_HEADER Do not add headers to read side
190 messages.
191 SB_NO_DROPS Do not drop messages due to flow
194 control upstream.
195 SB_NO_PROTO_CVT Do not convert M_PROTO messages
198 into M_DATA.
199 SB_DEFER_CHUNK Begin buffering on arrival of the
202 second read side message in a
203 timeout interval.
204 SBIOCGFLAGS Returns the current flags in the uint_t pointed to by
208 the ioctl's final argument.
209
212 dlpi(7P), pfmod(7M)
213
215 Older versions of bufmod did not support the behavioral flexibility
216 controlled by the SBIOCSFLAGS ioctl. Applications that wish to take
217 advantage of this flexibility can guard themselves against old versions
218 of the module by invoking the SBIOCGFLAGS ioctl and checking for an
219 EINVAL error return.
220 When buffering is enabled by issuing an SBIOCSCHUNK ioctl to set the
223 chunk size to a non zero value, bufmod sends a SETOPTS message to
224 adjust the stream head high and low water marks to accommodate the
225 chunked messages.
226 When buffering is disabled by setting the chunk size to zero, message
229 truncation can have a significant influence on data traffic at the
230 stream head and therefore the stream head high and low water marks are
231 adjusted to new values appropriate for the smaller truncated message
232 sizes.
233
235 bufmod does not defend itself against allocation failures, so that it
236 is possible, although very unlikely, for the stream head to use inap‐
237 propriate high and low water marks after the chunk size or snapshot
238 length have changed.
239SunOS 5.11 11 Nov 1997 bufmod(7M)