Manpage of FLUSHBAND

FLUSHBAND

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

flushband - flushes band STREAMS messages from a message queue

SYNOPSIS

#include <sys/stream.h>

void flushband(queue_t *q, unsigned char band, int flag);

ARGUMENTS

q: the queue to flush.
band: the band to flush within the queue.
flag: how to flush the band within the queue.

INTERFACE

STREAMS.

DESCRIPTION

flushband() is used to flush messages from a message queue band. It is typically called in a M_FLUSH(9) handling routine to flush the requested messages from a queue band.

If band is zero (0), flushband() will flush only normal and high priority messages.

flag can be one of the following:

FLUSHDATA: Flush only data messages; do not flush the control messages from the queue band.
FLUSHALL: Flush all the messages from queue band: both data messages and control messages.

If flag is other than FLUSHDATA or FLUSHALL flushband() will perform FLUSHALL.

If QB_WANTW is set for the band and the flush causes the band's count to fall below the low water mark, or if the band's count is reduced to zero, the nearest feeding queue with a qi_srvp(9) procedure or that is a stream head or stream end (including a multiplexing driver) will be enabled. That is, back-enabling will be performed. The QB_FULL and QB_WANTW flags will also be cleared.

RETURN

flushband() flushes the band and then returns void.

ERRORS

flushband() always succeeds.

CONTEXT

flushband() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines.

MP-STREAMS

flushband() is MP-safe when called from any context; however, the caller is responsibility for the validity of the passed in q pointer across the call.

The validity of either queue in the pair, and either q_next pointer for a queue in the pair, for the queue pointer passed to a module procedure, callout or synchronous callback functions, is guaranteed by Linux Fast-STREAMS. Any queue pointer in the pair passed as an argument to an asynchronous callback function are also valid, providing the driver or module observes the rules for cancellation of asynchronous callbacks on close. Linux Fast-STREAMS also provides that a queue pointer in the pair within whose procedures an asynchronous callback was invoked, and either q_next pointer, are also valid in an asynchronous callback.

NOTICES

flushband() is a widely supported STREAMS function. Portable STREAMS drivers and modules may use flushband(); however, portable STREAMS drivers and modules will not call flushband() with a band of zero (0). See COMPATIBILITY , below.

IMPLEMENTATION

flushband() performs fast flushes by linking all band messages into the per-thread free messages list. These messages will then later be broken into individual message blocks and freed to the per-thread free list and finally to the mdbblock memory cache at the end of any queue run. A new queue service run will be scheduled if one is not already running.

flushband() is well optimized to handle the initial stage of FLUSHALL flushes in constant time.

EXAMPLES

flushband() is normally used within the M_FLUSH(9) handling procedures for a STREAMS driver or module as follows:

 1  int
 2  x_w_flush(queue_t *q, mblk_t *mp)
 3  {
 4      if (*mp->b_rptr & FLUSHW) {
 5          if (*mp->b_rptr & FLUSHBAND
 6              && mp->b_rptr[1] != 0)
 7              flushband(WR(q), mp->b_rptr[1], FLUSHALL);
 8          else
 9              flushq(WR(q), FLUSHALL);
10          if (q->q_next) {
11              putnext(q, mp);
12              return (0);
13          }
14          *mp->b_rptr &= ~FLUSHW;
15      }
16      if (*mp->b_rptr & FLUSHR) {
17          if (*mp->b_rptr & FLUSHBAND
18              && mp->b_rptr[1] != 0)
19              flushband(RD(q), mp->b_rptr[1], FLUSHALL);
20          else
21              flushq(RD(q), FLUSHALL);
22          if (!q->q_next) {
23              qreply(q, mp);
24              return (0);
25          }
26          *mp->b_rptr &= ~FLUSHR;
27      }
28      freemsg(mp);
29      return (0);
30  }
31  
32  int
33  x_r_flush(queue_t *q, mblk_t *mp)
34  {
35      if (*mp->b_rptr & FLUSHR) {
36          if (*mp->b_rptr & FLUSHBAND
37              && mp->b_rptr[1] != 0)
38              flushband(RD(q), mp->b_rptr[1], FLUSHALL);
39          else
40              flushq(RD(q), FLUSHALL);
41          if (q->q_next) {
42              putnext(q, mp);
43              return (0);
44          }
45          *mp->b_rptr &= ~FLUSHR;
46      }
47      if (*mp->b_rptr & FLUSHW) {
48          if (*mp->b_rptr & FLUSHBAND
49              && mp->b_rptr[1] != 0)
50              flushband(WR(q), mp->b_rptr[1], FLUSHALL);
51          else
52              flushq(WR(q), FLUSHALL);
53          if (!q->q_next) {
54              qreply(q, mp);
55              return (0);
56          }
57          *mp->b_rptr &= ~FLUSHW;
58      }
59      freemsg(mp);
60      return (0);
61  }

Note in the example that the band is checked for band zero (0) before calling flushband(). If the band is zero (0), then flushq(9) is call instead. This is consistent with portability recommendations listed under COMPATIBILITY , below.

BUGS

flushband() has no known bugs.

COMPATIBILITY

flushband() is compatible with SVR 4.2 MP DDI/DKI[1], and systems based on SVR 4, with the following portability considerations:

---: flushband() moves messages from the queue to the per-CPU free chains list. Freeing blocks on the free chains list will be deferred to the next runqueues(9) pass. The next runqueues(9) pass frees message blocks from the flush to the per-CPU free blocks list for use by qi_srvp(9) procedures in the pass. runqueues(9) runs at normal soft interrupt priority. LiS removes all messages from the queue and then rebuilds the queue one message at a time while freeing those to be flushed. This is a rather inefficient way to do things, and with LiS running at higher priority than soft interrupts, bottom halves and timeouts, all these are locked out until the flush is complete. Linux Fast-STREAMS flushband() should have far less of an impact on system latency and performance as that of LiS.
: Performing STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: flushband() holds the queue write lock while removing selected messages or unlinking entire bands. Order is preserved across concurrent attempts to perform putq(9), insq(9), appq(9), rmvq(9) or putbq(9) functions. LiS empties the queue and unlocks the queue and then goes about adding messages back onto the queue that need to remain using normal utility functions. This means that order is not necessarily preserved (even for messages that were on the queue) with concurrent calls to putq(9), insq(9), appq(9), rmvq(9) or putbq(9) functions. Also, queue enabling and back-enabling will not necessary be performed correctly. There doesn't seem to be any excuse for the LiS approach, removing messages from the queue, rmvq(9), is no more difficult than inserting them, insq(9).
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: flushband() flushes normal and high priority messages when band is zero (0). AIX®[2] and UXP/V®[3] state that a band of zero (0) will only flush ordinary messages. IRIX®[4], OSF/1®[5], Solaris®[6] and SUPER-UX®[7] state that a band of zero (0) flushes normal and high priority messages. UnixWare®[8] states that a band of zero (0) flushes normal priority (band 0) messages. LiS, when band is zero (0), will only flush normal priority messages from band zero and will leave high priority messages on the queue.
: Portable STREAMS drivers and modules should never call flushband() with a band of zero (0). Portable STREAMS drivers and modules should call flushq(9) instead.
---: flushband() does not clear the QWANTR flag when flushing an empty queue. This is an indication to the STREAMS scheduler that getq(9) read an empty queue and the queue needs to be enabled when a message is placed on the queue. LiS clears the QWANTR flag when flushing an empty queue. This means that a call to putbq(9), insq(9) or appq(9) for the empty queue will fail to enable the queue.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: flushband() may be called on a stream frozen with freezestr(9). SVR 4.2 MP DDI/DKI[1], Solaris®[6], SUPER-UX®[7] and UnixWare®[8] do not permit flushband() to be called on a stream frozen with freezestr(9).
: Portable STREAMS drivers and modules will not call flushband() on a Stream frozen by the caller with freezestr(9).
---: HP-UX®[9] lists flushband() as a function that can only be passed a queue in the queue pair currently being synchronized within a module procedure. HP-UX®[9] also lists flushband() as a utility that cannot be called from user functions or non-STREAMS code; that is, contexts asynchronous to the Stream containing q.
: HP-UX® compatible drivers and modules will not call flushband() from outside of a qinit(9) routine for the queue pair of q. As Linux Fast-STREAMS permits this more restricted operation as a subset of its capabilities, there are no portability issues.
---: Solaris®[6] permits flushband() to be called from outside of STREAMS (e.g., by a driver flushing its own write queue from an ISR, or across a multiplexing driver).
: As Linux Fast-STREAMS permits the same, there are no portability issues.
---: LiS appears to be rather buggy with regard to flushing queues and flushband() may behave rather different from that of LiS.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1].

HISTORY

flushband() first appeared in SVR 4.0 STREAMS[10].

REFERENCES

[1]: USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: AIX® 5L Version 5.1, AIX STREAMS Programmers Guide, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[3]: UXP/V® V10L10, UXP/V Programmer's Guide: STREAMS V10, 1997, Fujitsu Limited, Fujitsu.
[4]: IRIX® 6.5.17, IRIX 6.5 Manual Pages, 2003, (Mountainview, California), Silicon Graphics, Inc., SGI Technical Publications. <http://techpubs.sgi.com/>
[5]: Digital® UNIX (OSF/1.2), Digital UNIX: Network Programmers Guide, 1996, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[6]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[7]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[8]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[9]: HP-UX STREAMS, STREAMS Programmer's Guide -- HP 9000 and Integrity Server Computer Systems, October 2005, (Palo Alto, California), Hewlett-Packard Development Company L.P., HP. <http://docs.hp.com/>
[10]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

Index

NAME
SYNOPSIS
ARGUMENTS
INTERFACE
DESCRIPTION
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
IMPLEMENTATION
EXAMPLES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 19:06:24 GMT, May 25, 2013