Manpage of ENABLEOK

ENABLEOK

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

NAME

enableok - allows a STREAMS message queue to be scheduled

SYNOPSIS

#include <sys/stream.h>

void enableok(queue_t *q);

ARGUMENTS

q: the queue upon which to permit enabling.

INTERFACE

STREAMS.

DESCRIPTION

enableok() clears the QNOENB flag on the specified queue, q. This tells the STREAMS scheduler that the queue, q, can be scheduled for runqueues(9).

enableok() is typically used to re-enable a queue after it has been disabled with noenable(9).

If enableok() has been called for a queue and noenable(9) has not subsequently been called for the same queue a second call to enableok() will have no effect.

Queues that have their QNOENB flag clear will enable the qi_srvp(9) procedure under all normal queue enabling situations, as follows:

-: the queue is explicity enabled with qenable(9);
-: the queue is back-enabled;
-: an arriving message becomes the first message on the queue;
-: a message arrives and the QWANTR flag is set.

USAGE

enableok() can be used in conjunction with noenable(9) to temporarily suspend queue qi_srvp(9) procedure processing for a queue for normal priority messages. noenable(9) permits data messages to be enqueued without invoking the queue's qi_srvp(9) procedure. A call to enableok() will then reverse the situation and restore normal queue scheduling.

RETURN

enableok() clears the QNOENB flag and returns void.

ERRORS

enableok() always succeeds.

CONTEXT

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

enableok() is MP-safe. No global locks need to be held across the call to enableok(). enableok() takes a recursive freeze lock that can be acquired by the caller when the Stream is frozen. If another thread has the Stream frozen with freezestr(9), the calling processor will spin until the Stream is thawed by unfreezestr(9). If one thread enables a queue with enableok() and another disables the queue with noenable(9), there will be a race condition on the QNOENB flag.

NOTICES

enableok() does not place the queue on the current runqueues(9) schedule list. It only clears the QNOENB flag to indicate whether the queue should be subsequently scheduled. To add a queue to the current run list, use qenable(9).

EXAMPLE

enableok(9) can be used to re-enable a queue after a call to noenable(9). The following qrestart() function will restart a disabled queue:

void qrestart(queue_t *q)
{
        enableok(q);
        if (q->q_first)
                qenable(q);
}

Note that enableok() does not place the queue on the runqueues() list. It takes qenable(9) to do that.

BUGS

enableok() has no known bugs.

COMPATIBILITY

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

---: enableok() may be called on a stream frozen with freezestr(9), but it is not recommended. enableok() uses atomic bit operations and uses a recursive freeze lock permitting it to be called while the Stream is frozen with freezestr(9) by the caller.
: SUPER-UX® and UnixWare® do not permit enableok() to be called on a stream frozen with freezestr(9)[2,3]. Solaris®[4] permits enableok() to be called on a stream frozen with freezestr(9). Under LiS[5], enableok() takes the queue spin lock and uses normal bit operations to set the flag.
: Portable STREAMS drivers and modules will not invoke enableok() on a stream that has previously been frozen with freezestr(9). (Linux Fast-STREAMS[6] includes an assertion to enforce this in the SMP environment.)
---: enableok() called with an invalid q argument will have an undefined result. In referenced versions of LiS[5] the result is undefined in the same situations due to an LiS coding error. Repaired versions of LiS will make enableok() fail silently in these situations, which is largely unacceptable because it masks errors.
: Portable STREAMS drivers and modules will not invoke enableok() with an invalid q argument. Portable STREAMS drivers and modules will use Linux Fast-STREAMS[6] instead of LiS.
---: enableok() is not bug for bug compatible with LiS.
: LiS incorrectly schedules a queue that would have otherwise been enabled had nonenable(9) not been in effect, whenever enableok() is called. This is not consistent with SVR 4 descriptions of treatment of the QNOENB flag and is an LiS bug.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[6] instead of LiS.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1].

HISTORY

enableok() appears as part of SVR 4.0 STREAMS [7].

enableok() first appeared in SVR 3[8].

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]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[3]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[4]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[5]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[6]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[7]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[8]: 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
CONTEXT
MP-STREAMS
NOTICES
EXAMPLE
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 23:01:14 GMT, May 22, 2013