Manpage of NOENABLE

NOENABLE

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

NAME

noenable - disables a STREAMS message queue from being scheduled

SYNOPSIS

#include <sys/stream.h>

void noenable(queue_t *q);

ARGUMENTS

q: the queue for which to suppress scheduling.

INTERFACE

STREAMS.

DESCRIPTION

noenable() sets the QNOENB flag on the specified queue, q. This tells the STREAMS scheduler that the queue not be enabled (scheduled for service by runqueues(9)) when a ordinary priority message is enqueued by putq(9) or putbq(9), or which any messae is enqueued by insq(9). noenable() has no effect on the enablig of queues (scheduling of queue qi_srvp(9) procedures) when the queue is back-enabled, when qenable(9) is called explicitly, or when a message of a high priority message type is enqueued with putq(9) or putbq(9).

noenable() can be cancelled with enableok(9). If noenable() has been called for a queue and enableok(9) has not subsequently been called for the same queue, a second call to noenable() for the queue will have no effect. Whether a queue has been disabled with a call to noenable() can be tested with canenable(9).

USAGE

noenable() can be used to temporarily suspend queue qi_srvp(9) procedure processing for a queue for ordinary priority messages enqueued with putq(9) and putbq(9), and any messages enqueued with insq(9). This permits data messages to be enqueued with putq(9) or putbq(9), and any message to be enqueued with insq(9), without enabling the queue (invoking the queue's qi_srvp(9) procedure).

This facility can be used to provide message coallescing capabilities on read or write queues. For example, multiple messages can be enqueued by a queue's qi_putp(9) procedure without invoking the queue's qi_srvp(9) procedure until a criteria is met. Once the a sufficient time period has elapsed, or once a sufficient number of bytes have been enqueued, the qi_putp(9) procedure, or a timeout(9) callback, can explicity invoke the qi_srvp(9) procedure with qenable(9). The queue's qi_srvp(9) procedure, thus invoked, may coalesce smaller messages into larger ones.

Canonical processing in the Line Discipline, ldterm(4), module can use this capability to perform a similar function.

RETURN

noenable() sets the QNOENB flag and returns void.

ERRORS

noenable() always succeeds.

NOTICES

noenable() does not remove the queue from the current runqueues(9) schedule list. It only sets the QNOENB flag to indicate whether the queue should be subsequently scheduled. To stop a queue from being scheduled, use qprocsoff(9).

CONTEXT

noenable() 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

noenable() is MP-safe. noenable() uses atomic bit operations and does not write lock the queue. Therefore, noenable() can be called for a queue that has been frozen with freezestr(9). No global locks need to be held across a call to noenable() and noenable() takes no locks.

If one thread disables a queue with noenable() and another enables the queue with enableok(9), there will be a race condition on the QNOENB flag.

BUGS

noenable() has no known bugs.

COMPATIBILITY

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

---: The function of noenable() on all implementations is presumably the same: noenable() simply sets the QNOENB flag in the q_flag member of the queue(9) structure. It is the effect of setting this flag on other STREAMS utility functions and the STREAMS scheduler and flow control mechanisms that tend to differ, at least in the documentation.
---: noenable() uses atomic bit operations and does not require taking the queue write lock. This makes noenable() safe for use on a write locked stream that has been frozen with freezestr(9). LiS takes the queue spin lock and uses normal bit operations to set the flag.
---: noenable() may be called on a stream frozen with freezestr(9). SVR 4.2MP DDI/DKI[1], SUPER-UX®[3] and UnixWare®[4] do not permit noenable() to be called on a stream frozen with freezestr(9). Solaris®[5] permits noenable() to be called on a stream frozen with freezestr(9).
: Portable STREAMS drivers and modules will not invoke noenable() on a stream that has previously been frozen with freezestr(9).
---: noenable() called with an invalid q argument will have an undefined result. In referenced versions of LiS[6] the result is undefined in the same situations due to an LiS coding error. Repaired versions of LiS will make noenable() fail silently in these situations.
: Portable STREAMS drivers and modules will not invoke noenable() with an invalid q argument.
---: noenable() supresses the scheduling of queues for both high priority and ordinary priority messages enqueued with appq(9). Only LiS provides the appq(9) function so the behaviour of noenable() with regard to appq(9) is non-portable anyway. As with insq(9) LiS suppresses the scheduling of queues for any message enqueued with appq(9).
: Portable STREAMS drivers and modules will not use the appq(9) function call. STREAMS drivers and modules using the appq(9) function call should not rely on the LiS behavior with regard to noenable().
---: noenable() does not suppress the scheduling of queues when back-enabling is performed, when qenable(9) is explicitly called, or when high priority messages are enqueued with putq(9) or putbq(9).
: AIX®, HP-UX® and UXP/V® state that noenable() disables the scheduling of queues resulting from a ordinary priority message being placed on the queue with putq(9) or putbq(9) and that it disables scheduling of queues resulting from any message being placed on the queue with insq(9)[7,8]. LiS also follows this behaviour[6].
: OSF/1® and Solaris®, document noenable() a suppressing enabling of queues when an ordinary priority message is enqueued with putq(9), putbq(9), or insq(9), but makes no mention of high priority messages.
: Solaris® states that queue class is ignored by insq(9), but lump insq(9) together with putbq(9) and putq(9) when describing noenable()[9,10]. OSF/1®, Solaris®, SUPER-UX® and UnixWare® state that noenable() disables the scheduling of queues resulting from a ordinary priority message being placed on the queue with putq(9), putbq(9) or insq(9), and that the scheduling of queues resulting from back-enabling or high priority messages being enqueued is never suppressed with noenable()[9..12]. Yet SUPER-UX® documents insq(9) as enabling the queue when any message is enqueued by insq(9) unless noenable() has been called for the queue[11]. HP-UX®[13] does not talk about insq(9) behaviour.
: Portable STREAMS drivers and modules should not rely upon the behaviour of insq(9) with regard to high priority messages when noenable() is in effect. The best practice is to explicitly enable, using qenable(9), the queue immediately after a high priority message is inserted into the queue with insq(9); thus yeilding like behaviour across all these systems.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1].

HISTORY

noenable() appears as part of SVR 4.0 STREAMS[2].

noenable() first appeared in SVR 3[14].

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]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[4]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[5]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[6]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[7]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[8]: UXP/V® V10L10, UXP/V V10L10 Documentation, 1997, Fujitsu Limited, Fujitsu.
[9]: Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[10]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[11]: SUPER-UX® Release 9.2, SUPER-UX Release 9.2 Documentation, 1999, NEC Corporation, NEC.
[12]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[13]: 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/>
[14]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (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
USAGE
RETURN
ERRORS
NOTICES
CONTEXT
MP-STREAMS
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 21:40:15 GMT, May 21, 2013