Manpage of QUEUE

QUEUE

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

NAME

queue, queue_t, queue_free - STREAMS message queue structure

SYNOPSIS


typedef struct queue {
    struct qinit *q_qinfo;      /* info structure for the queue */
    struct msgb *q_first;       /* head of queued messages */
    struct msgb *q_last;        /* tail of queued messages */
    struct queue *q_next;       /* next queue in this stream */
    struct queue *q_link;       /* next queue for scheduling */
    void *q_ptr;                /* private data pointer */
    size_t q_count;             /* number of bytes in queue */
    unsigned long q_flag;       /* queue state */
    ssize_t q_minpsz;           /* min packet size accepted */
    ssize_t q_maxpsz;           /* max packet size accepted */
    size_t q_hiwat;             /* hi water mark for flow control */
    size_t q_lowat;             /* lo water mark for flow control */
    struct qband *q_bandp;      /* band's flow-control information */
    unsigned char q_nband;      /* number of priority bands */
    unsigned char q_blocked;    /* number of bands flow controlled */
    unsigned char qpad1[2];     /* padding */
    /* Linux fast-STREAMS specific members */
    ssize_t q_msgs;             /* messages on queue */
    rwlock_t q_lock;            /* lock for this queue structure */
    int (*q_ftmsg) (mblk_t *);  /* message filter ala AIX */
    struct syncq *q_syncq;      /* syncrhonization queues */
    struct queue *q_nfsrv;      /* next forward queue w/ service procedure */
    struct queue *q_nbsrv;      /* next backward queue w/ service procedure */
    qi_putp_t q_putp;           /* put procedure cache pointer */
    qi_srvp_t q_srvp;           /* srv procedure cache pointer */
} queue_t;

MEMBERS

The following members correspond to SVR 4.2 EFT members:

q_qinfo

qinit(9) structure for the queue;

q_first

first msgb(9) structure (message) on the queue;

q_last

last msgb(9) structure (message) on the queue;

q_next

downstream queue in this stream;

q_link

next queue to have its qi_srvp(9) procedure scheduled;

q_ptr

a pointer to the module's private structure;

q_count

count of the data bytes in messages on the queue;

q_flag

queue flags:

QENAB: queue is enabled to run;
QWANTR: flow controlled forward;
QWANTW: back-enable necessary;
QFULL: queue is flow controlled;
QREADR: this is the read queue;
QUSE: queue being allocated;
QNOENB: do not enable with putq;
QUP: uni-processor emulation;
QBACK: the queue has been back enabled;
QOLD: module supports old style open/close;
QHLIST: stream head is on the scan list;
QTOENAB: to be enabled;
QSYNCH: flag for queue sync;
QSAFE: safe callbacks needed;
QWELDED: flags for welded queues;
QSVCBUSY: service procedure running;
QWCLOSE: q in close wait;
QPROCS: q has procs turned off;
QBLKING: queue procedures are not to spec and may block;
QSRVP: queue has a service procedure;
QSHEAD: queue actively belongs to a Stream head;

q_minpsz

minimum packet size accepted;

q_maxpsz

maximum packet size accepted;

q_hiwat

queue high water mark for flow control;

q_lowat

queue low water mark for flow control;

q_bandp

pointer to the qband(9) structures representing the bands of the queue;

q_nband

number of queue bands present;

q_pad1

padding.

The following members are Linux Fast-STREAMS specific members:

q_blocked: number of flow controlled bands
q_msgs: number of message on the queue (for optimization of qsize(9));
q_lock: queue read write lock;
q_ftmsg: message filter (to support wantmsg(9));
q_syncq: synchronization queue;
q_nfsrv: next foward queue with service procedure (or Stream end);
q_nbsrv: next backward queue with service procedure (or Stream end);
q_putp: cached put procedure function pointer;
q_srvp: cached service procedure function pointer;

FUNCTIONS

The following queue utility functions are provided (these functions each take a pointer to a queue structure):

OTHERQ(9) -: other queue in a queue pair
RD(9) -: read queue of a queue pair
SAMESTR(9) -: next queue in the same stream
WR(9) -: write queue of a queue pair
allocq(9) -: allocate a queue pair
appq(9) -: append a message behind another in a queue
backq(9) -: feeding queue
bcanput(9) -: test band for flow control for a queue
bcanputnext(9) -: test band for flow control for next queue
canenable(9) -: test if queue can be enabled
canput(9) -: test for flow control for a queue
canputnext(9) -: test for flow control for next queue
enableok(9) -: allow a queue to be enabled
flushband(9) -: flush messages from a band of a queue
flushq(9) -: flush messages from a queue
freeq(9) -: free a queue pair
freezestr(9) -: freeze the stream containing a queue
getq(9) -: get a message from a queue
insq(9) -: insert a message before another in a queue
mi_bufcall(9) -: enable a queue on bufcall
noenable(9) -: prohibit enabling of a queue
put(9) -: put a message to a queue's put procedure
putbq(9) -: put a message back on a queue
putctl(9) -: put a control message on a queue
putctl1(9) -: put a one-byte control message on a queue
putnext(9) -: put a message on the next queue
putnextctl(9) -: put a control message on the next queue
putnextctl1(9) -: put a one-byte control message on the next queue
putq(9) -: put a message on a queue
qattach(9) -: attach a queue pair to a stream
qbufcall(9) -: perform a buffer callback for a queue
qclose(9) -: close a queue pair
qcountstrm(9) -: count the data bytes on all queues in a stream
qdetach(9) -: detach a queue pair from a stream
qenable(9) -: enable a service procedure for a queue
qopen(9) -: open a queue pair
qprocsoff(9) -: turn put and service procedures off for a queue pair
qprocson(9) -: turn put and service procedures on for a queue pair
qreply(9) -: reply with a message for a queue
qsize(9) -: count the messages on a queue
qtimeout(9) -: schedule a timeout for a queue
qunbufcall(9) -: cancel a buffer call for a queue
quntimeout(9) -: cancel a timeout for a queue
qwait(9) -: wait for a put to a queue
qwait_sig(9) -: wait for a signal or put to a queue
qwriter(9) -: call exclusive procedure for a queue
rmvq(9) -: remove a message from a queue
setq(9) -: set the parameters of a queue pair
strqget(9) -: get a parameter for a queue
strqset(9) -: set a parameter for a queue
unfreezestr(9) -: thaw the stream containing a queue

queue_free is a per-thread pointer to the list of free queue structures for fast allocation or deallocation. This per-thread global does not really exist. There is, instead, a global memory cache pointer for queinfo structures.

INTERFACE

STREAMS.

DESCRIPTION

The queue structure is a structure dynamically allocated by STREAMS(9) using the allocq(9) utility. queue structures are always allocated in pairs by the allocq(9) utility. STREAMS allocates a queue pair as an array of two elements, where each element is a queue structure. The first queue in the array corresponds to the read-side queue in the pair; the second, the write-side queue. queue pairs are deallocated with freeq(9).

STREAMS keeps track of the number of queue pairs currently allocated by allocq(9), and a system high water mark of allocations active since the last boot. This information is available to system administration in the /proc/streams/strinfo system file.

USAGE

Queue Pair Linkage

Queue pairs form an instance of the Stream head, driver or module within a Stream. The Stream is a linear sequence of queue pairs connected in two directions by their q_next pointers. q_next pointers point to the corresponding queue in the next queue pair along the Stream and are used for passing messages along the Stream. The q_next pointers of the read queues in each queue pair point upstream beginning at the driver, following up the read queues of the module stack, and terminating at the Stream head read queue. The q_next pointer of the Stream head read queue contains NULL. The q_next pointers for the write queues in each queue pair point downstream beginning at the Stream head, following dosn through the write queues of the module stack, and terminating at the driver. The q_next pointer of the driver write queue contains NULL.

Queue Pair Initialization

When a queue structure is allocated by STREAMS and linked into a Stream, elements of each queue structure in the queue pair are initialized.

The QUSE bit is set in the q_flag member of each queue to indicate that it is initialized. The QREADR bit is set for the read queue and cleared for the write queue. For any given queue pointer, this flag indicates whether the queue referenced is a read or write queue. While the queue pair is still in the initialization process, and before qprocson(9) is called for the queue pair, the QPROCS bit is set, indicating that the queue's procedures are disabled. This is also the case after qprocsoff(9) is called on close. While the queue pair is in operation, QPROCS is clear on both queues. While STREAMS is waiting for the write queue of a queue pair to drain on close, the QWCLOSE bit is set in q_flag.

The q_qinfo pointer of the read queue is initialized to point to the st_rdinit pointer of the driver or module streamtab(9) structure; the write queue q_qinfo, the st_wrinit pointer. These qinit(9) structures contain the qi_putp(9) and qi_srvp(9) procedures associated with each queue. The qinit(9) structure associated with the read queue contains the qi_qopen(9) and qi_qclose(9) procedures associated with the queue pair.

Each queue's associated qinit(9) structure also contains a pointer to the module_info(9) structure, qi_minfo, that is used to initialize packet size and flow control values in each queue. The mi_minpsz, mi_maxpsz, mi_hiwat, mi_lowat, members of the module_info(9) structure are used to initialize the corresponding q_minpsz, q_maxpsz, q_hiwat, q_lowat, members of the queue structure.

When the driver or module qi_qopen(9) procedure is called, the driver or module can associated module private information with each queue structure using the q_ptr member. This use of this member is private to the module and will not be altered or examined by STREAMS. When the driver or module qi_qclose(9) procedure is called, the driver or module has the opportunity to deallocate and resources that were associated with the q_ptr. This member is typically used by the module to point to an allocated structure containing module private state information. It is common that the q_ptr members of both the read and write queues are directed at the same module private structure.

Message Queues

Each queue in a queue pair contains a message queue. The message queue is a NULL-terminated, double-linked list of msgb(9) structures representing messages on the queue. The message queue is ordered with respect to the priority of messages on the queue. q_first points to the head of the queue. This is the first message on the queue awaiting processing. When the message queue is empty, q_first contains NULL. q_last points to the tail of the queue. This is the last message on the queue available for processing. When the message queue is empty, q_last contains NULL. q_count contains the byte count of all the normal (priority zero) and high priority message blocks contained on the message queue.

The message queue can also contain priority messages (messages in which the b_band member is non-zero). Each band that currently has, or has previously had, a message of that band queued to the message queue will also have a qband(9) structure that locates the messages of the same priority within the message queue. qband(9) structures are linked onto a list beginning with the q_bandp pointer. q_nband contains the band number of the highest priority qband(9) structure linked to q_bandp. This is also the number of qband(9) structures attached. Each queue band structure provides a qb_first and qb_last pointers that point to messages only within the band.

Queue Scheduling

Although queue qi_putp(9) procedures are directly invoked by STREAMS, a queue's qi_srvp(9) procedure can be scheduled for later execution. STREAMS utilities that place a message on the message queue can cause the queue's qi_srvp(9) procedures to be scheduled. qenable(9) directly schedules a queue, and when scheduled, the queue is termed enabled . When a queue becomes enabled, the QENAB flag is set in the q_flag member of the queue, and the queue is linked onto the tail off a list of queues awaiting qi_srvp(9) procedure execution using the q_link pointers in the queue structures forming the list.

The STREAMS noenable(9) utility sets the QNOENB flag to indicate to STREAMS utilities placing messages on the message queue that the queue's qi_srvp(9) procedure is only to be scheduled for high priority messages. enableq(9) clears the QNOENB flag, and canenable(9) tests it. When the queue's qi_srvp(9) procedure is run by the STREAMS scheduler, the scheduler first sets the QSVCBUSY flag before running the procedure to indicate that the queue has its qi_srvp(9) procedure executing.

Flow Control

Any STREAMS utility function placing a normal (priority zero) or high priority message on the queue will adjust q_count and compare it with q_hiwat. If the count exceeds the high water mark, the QFULL bit will be set in q_flag to indicate that the queue is blocked by flow control. Any STREAMS utility function placing a priority message on the queue will adjust qb_count for the corresponding qband(9) structure, and compare it with qb_hiwat. If the count exceeds the high water mark, the QB_FULL bit will be set in qb_flag to indicate that the queue band is blocked by flow control. The q_blocked member will also be incremented if the queue band was previously unblocked.

Any STREAMS utility function removing a normal (priority zero) or high priority message from the queue will adjust q_count and compare it with q_lowat. If the count drops beneath the low water mark, the QFULL bit will be cleared in q_flag to indicate that the queue is no longer blocked by flow control. Any STREAMS utility function removing a priority message from the queue will adjust qb_count for the corresponding qband(9) structure, and compare it with qb_lowat. If the count drops beneath the low water mark, the QB_FULL bit will be cleared in qb_flag to indicate that the queue is no longer blocked by flow control. The q_blocked member will also be decremented if the queue band was previously blocked.

Whenever getq(9) is called to removes a message from a message queue and the message queue is found to be empty, STREAMS sets the QWANTR in the q_flag member of the corresponding queue. (Since QWANTR is only set on an empty queue, there is no corresponding QB_WANTR flag for the qband(9) structure.) The QWANTR flag signals STREAMS utilities that place messages onto the message queue that the queue's qi_srvp(9) procedure needs to be scheduled and the flag cleared.

Whenever canput(9) or canputnext(9) is called and the queue is found to be flow controlled (i.e., the QFULL bit is set in q_flag), the QWANTW flag is set in q_flag. bcanput(9) and bcanputnext(9) called for a queue band that is flow controlled (i.e., the QB_FULL bit is set in qb_flag), the QB_WANTW bit is set in the qb_flag member of the corresponding qband(9) structure. The QWANTW and QB_WANTW flags are an indication that an feeding queue wishes to write to a flow controlled queue or queue band. When messages are removed from the message queue or queue band that cause its count to fall to the low water mark, feeding queues are back-enabled. Back-enabling consists of locating the feeding queue that wanted to write (one with a qi_srvp(9) procedure) and causing its qi_srvp(9) procedure to be scheduled. When a Stream head write queue is back-enabled in this fashion, STREAMS sets the QBACK or QB_BACK flag in the q_flag or qb_flag members to indicate for which message bands the queue was back-enabled.

Packet Sizes

A STREAMS driver or module specifies the minimum and maximum packet sizes that it wishes to accept for each queue in a queue pair by setting the q_minpsz and q_maxpsz members of the queue structure. The initial values of these members is taken from the corresponding members, mi_minpsz and mi_maxpsz of the module_info(9) structure pointed to by the qinit(9) structure used to initialize the queue.

On a write queue, q_minpsz and q_maxpsz specify the minimum and maximum packet sizes accepted by the driver or module in the downstream direction. The sizes act as advice to the upstream module. If the upstream module is the Stream head, the Stream head will observe the minimum and maximum packet sizes when generating messages from the write(2s), putmsg(2s), putpmsg(2s), system calls, and ioctl(2s) system calls that generate messages (e.g., I_FDINSERT(7)). (Note that the Stream head does not use its write queue but, rather, places messages directly on the write queue at the top of the module stack.)

When performing a write or write-like operation, the Stream head interprets q_minpsz and q_maxpsz different, depending on the value of q_minpsz:

*: When q_minpsz is zero, the write operation will fragment writes larger than q_maxpsz down into multiple messages of q_maxpsz or less.
*: When q_minpsz is non-zero, a write operation of less than q_minpsz or more than q_maxpsz will fail with errno(3) set to [ERANGE]. See write(2s) for details.

On a read queue, q_minpsz and q_maxpsz specify the minimum and maximum packet sizes accepted by the driver or module in the upstream direction. The sizes act as advice to the downstream module. At the Stream head, the read queue packet sizes act as advise to the top of the module stack; however, the Stream head is always prepared to accept a data stream message of any size. The Stream head read queue packet sizes can be adjusted by any driver or module by sending an M_SETOPTS(9) message to the Stream head.

Specialized Flags and Members

Several additional flags can be set on a queue during initialization to indicate specific specialized features:

QUP: indicates that the queue is operating in uni-processor emulation mode. This bit is set at initialization of the queue pair. Uni-processor emulation mode is not supported by Linux Fast-STREAMS.
QOLD: indicates that the prototype of the qi_qopen procedure is the old SVR 3-style prototype. This bit is set at initialization of the queue pair. Old style qi_qopen prototypes are not supported by Linux Fast-STREAMS.
QHLIST: indicates that, instead of being linked on the run queues list with q_link, a Stream head write queue is linked on the scan list with q_link. As the Stream head write queue does not have a qi_srvp(9) procedure, it can only be linked on the scan list. The scan list is used by the SNDHOLD feature (see SO_STRHOLD under M_SETOPTS(9) for details.)
QTOENAB: indicates that the queue needs to be enabled (or does TO stand for timeout?). UnixWare®[1] uses this bit for some unknown purpose. This bit is set while the queue pair is active. Its use is not supported by Linux Fast-STREAMS.
QSYNCH: set by Linux Fast-STREAMS when a synchronization queue has been allocated and attached to the q_syncq member of the structure. This bit is set at initialization of the queue pair. The use of this bit is implementation specific.
QSAFE: indicates that the module requires safe callbacks (that is, interrupts are to be suppressed before calling callback functions). This has the effect of freezing the Stream with freezestr(9) before the callback is invoked and thawing the Stream with unfreezestr(9) after the callback returns. This bit is set at initialization of the queue pair. Its use is supported by Linux Fast-STREAMS.
QWELDED: set when two queue pairs are welded together using the weldq(9) utility function. Its use is supported by Linux Fast-STREAMS.
QBLKING: Used by Linux Fast-STREAMS to indicate a queue pair for a module or driver that at registration time indicated that it was not to specification an might block in its service procedure. See str_install_AIX(9).
QSRVP: Use by Linux Fast-STREAMS to cache the fact that the queue has a service procedure.
QSHEAD: Use by Linux Fast-STREAMS to indicate that the queue is actively part of a Stream head. That is, the queue belongs to a Stream head and the Stream is not currently linked under a multiplexing driver.

Also, Linux Fast-STREAMS provides some implementation specific members to the queue structure:

q_msgs: used by Linux Fast-STREAMS to hold a count of the number of messages on the message queue. This is in support of the qsize(9) utility.
q_lock: read-write lock used by Linux Fast-STREAMS to provide shared or exclusive access to the structure.
q_ftmsg: used by Linux Fast-STREAMS to support AIX®[2] message filtering (see wantmsg(9) for details).
q_syncq: used by Linux Fast-STREAMS to attach synchronization queues in support of STREAMS synchronization levels.
q_nfsrv: Used by Linux Fast-STREAMS, in a fashion similar to Solaris®[3], to store the next forward (fed) queue that either has a service procedure or is the last queue (Stream end) in the forward direction. This cache pointer is used to speed execution of bcanputnext(9) and friends when many modules without service procedures are pushed on a Stream.
q_nbsrv: Used by Linux Fast-STREAMS, in a fashion similar to Solaris®[3], to store the next backward (feeding) queue that either has a service procedure or is the last queue (Stream end) in the backward direction. This cache pointer is used to speed execution of qbackenable(9) and friends when many modules without service procedures are pushed on a Stream.
q_putp: Used by Linux Fast-STREAMS to cache the put procedure function pointer. This saves continual dereferencing of q->q_qinfo->qi_putp to obtain the procedure pointer. Because the qinit(9) structure is statically allocated by the module, better cache efficiency can be achieved by storing this function pointer in the queue structure.
q_srvp: Used by Linux Fast-STREAMS to cache the service procedure function pointer. This saves continual dereferencing of q->q_qinfo->qi_srvp to obtain the procedure pointer. Because the qinit(9) structure is statically allocated by the module, better cache efficiency can be achieved by storing this function pointer in the queue structure.

CONTEXT

Functions that operate on a queue or queue pair can be called from any context.

MP-STREAMS

The queue pointers and members, with the exception of the q_next pointer and the q_flag member, are protected by the queue read write lock, (q_lock). The q_next pointer is protected with the stream head read write lock. The q_flag member is protected using atomic bit operations.

Because the queue read write lock (q_lock) is not a nesting lock, functions that take the queue write lock cannot be invoked again by the same thread, or cause the invocation of another function that takes the queue write lock by the same thread or single-party deadlock will result.

IMPLEMENTATION

The following subsections provide implementation details with regard to the allocation and deallocation of queue pairs under Linux Fast-STREAMS:

Allocation

When Linux Fast-STREAMS allocates a queue pair with allocq(9), the first element, or read-side queue has the QREADR flag set in its q_flag member; the second, write-side queue, has the QREADR flag clear. Given a pointer to a queue structure, one can determine whether it is the read-side or write-side queue of the queue pair by examining the QREADR flag. When Linux Fast-STREAMS allocates a queue pair, it sets the QUSE flag in both queues of the pair; when deallocating, this flag is cleared in both queues.

Linux Fast-STREAMS allocates a queue pair, using allocq(9), in two situations:

(1): Linux Fast-STREAMS allocates a queue pair to form an instance of a driver or module in a Stream, during qattach(9). qattach(9) is called for a queue pair forming a module instance by the I_PUSH(7) ioctl(2s) system call; for a driver instance, by the open(2s) system call. This is the normal case for creation of a queue pair to represent a driver or module in the Stream.
(2): Linux Fast-STREAMS allocates a queue pair to form an instances of a Stream head, during stropen(). stropen() is called for a queue pair forming a Stream head instance by the open(2s) or pipe(2s) system call. This is a special case of creating a Stream head for a Stream when the Stream is first created.

In the normal case of allocating a queue pair to form a driver or module instance, qattach(9) is used to allocate, initialize and attach the queue pair. qattach(9) performs the following actions:

(1)

qalloc(9) is called to allocate and initialize the queue pair.

qalloc(9) performs the following actions:

a)

allocq(9) is called to allocate a queue pair from cache memory and increment the count of the number of currently allocated queue pairs.

b)

The QPROCS and QNOENB bits are set in the q_flag member of each queue, to disable queue procedures.

c)

setsq(9) is called to allocate any synchronization queues necessary to represent the synchronization model under which the driver or module is running, and attaches them to the q_syncq private member of the queue structure. See syncq(9) for more information on synchronization queues.

d)

setq(9) is called to:

-: locate the qinit(9) structures associated with the st_rdinit and st_wrinit members of the streamtab(9) structure defining the driver or module;
-: attach the qinit(9) structures to the q_qinfo member of each queue; and,
-: initialize the packet sizes and flow control levels, q_minpsz, q_maxpsz, q_hiwat, q_lowat, from the corresponding mi_minpsz, mi_maxpsz, mi_hiwat, mi_lowat, members of the module_info(9) structure associated with each qinit(9) structure (via the qi_minfo member).

See setq(9) for details of its operation.

(2)

qinsert(9) is called to half-insert the queue pair into the Stream beneath the Stream head. The insertion is a half-insertion in the sense that the q_next pointers of the inserted queue pair point to the Stream head on the read-side and the module stack on the write-side, but the q_next pointers of the Stream head and the top of the module stack do no yet point to the half-inserted module. Messages active in the Stream will bypass the half-inserted module. This situation persists until qprocson(9) is called, either by the driver or module qi_qopen(9) procedure, or by qattach(9) later in this sequence. See qinsert(9) for details.

(3)

qi_qopen(9) is called to invoke the driver or module qi_qopen(9) procedure found in the qi_qopen member of the qinit(9) structure associated with the read side queue pair. An error returned from this procedure causes the queue pair to be deleted from the Stream and deallocated. The error code is used in the return to the corresponding open(2s) system call, or I_PUSH(7) ioctl(2s).

(4)

If the queue pair forms an instance of a driver, Linux Fast-STREAMS checks whether the device number returned from the driver qi_qopen(9) procedure is different than the device number passed. When the returned device number differs, Linux Fast-STREAMS looks up the new device number in its cdevsw(9) tables, and, if the streamtab(9) associated with the new device table entry differs from that of the original device table entry, then a setsq(9) and setq(9) operation is performed again on the Stream, to reinitialize the queues in the pair to values associated with the new streamtab(9)[4]. See also NOTICES , below.

(5)

qprocson(9) is called which performs the following actions:

a): If the QPROCS bit is clear on the read queue of the queue pair, it indicates that procedures are already enabled, in which case, qprocson(9) takes no further action. If the QPROCS bit is set, the driver or module qi_qopen(9) procedure forgot (or was not designed to) call the qprocson(9) facility, in which case, the remaining actions are performed.
b): The QPROCS and QNOENB bits are cleared in the q_flag members of each queue in the queue pair. Clearing these flags enables procedures for each queue.
c): The QWANTR bit is set in the q_flag members of each queue in the queue pair. Setting this flag causes the queue's qi_srvp(9) procedure to be scheduled on the first message that is placed on its message queue.
d): The half-insertion performed by qinsert(9) is completed. That is, the q_next pointers of the Stream head and top of the module stack are adjusted to no longer bypass the queue pair, but now point to the queue pair.
e): The sd_minpsz and sd_maxpsz fields in the stdata(9) structure (Stream head) are set to the corresponding q_minspz and q_maxpsz values from the write queue of the queue pair, which now occupies the top of the module stack. (The Stream head caches these values to avoid problems with referencing a non-existent driver write queue.)

(6)

The queue pair is then active within the Stream.

For the special case, where a queue pair is created as an instance of a Stream head, stropen() creates the pair in a similar fashion as above. See stdata(9) for details.

Deallocation

Linux Fast-STREAMS deallocates a queue pair only after it is no longer needed by a Stream. Queue pairs forming an instance of a module are released as part of the I_POP(7) operation to ioctl(2s) for the queue pair. Queue pairs forming an instance of the Stream head, or an instance of a driver, are only released as part of the last close(2s) system call resulting in dismantling of the Stream.

Queue pairs forming instances of a module are removed from the Stream and deallocated by calling qdetach(9) for the queue pair directly from the I_POP(7) handling in the Stream head. Queue pairs forming instances of a driver are removed from the Stream and deallocated by calling qdetach(9) also, however, qdetach(9) is called from strwaitclose() which is called from strlastclose(). which is normally called from strclose().

strlastclose() is normally called from strclose() whenever the last close(2s) system call in performed on a Stream. However, Streams that are linked under a multiplexing driver and then closed will have strlastclose() called when the Stream is unlinked. A STREAMS-based pipe(4) that has one end mounted with fattach(3) and then closed, will have strlastclose() called when the other end of the pipe is closed for the last time. Otherwise, a Stream that is mounted with fattach(3) and then closed, will have strlastclose() called when unmounted with fdetach(3).

strwaitclose() will wait up to 15 seconds for the write side of a queue to drain under certain circumstances. See close(2s) for details.

qdetach(9) performs the following actions when detaching an deallocating a queue pair:

(1)

qi_qclose(9) is called to invoke the qi_qclose(9) procedure of the driver or module located in the qi_qclose member of the qinit(9) structure associated with the read queue of the queue pair.

(2)

qprocsoff(9) is called to ensure that the driver or module writer did not forget to call qprocsoff(9) from the driver or module qi_qclose(9) procedure. qprocsoff(9) checks the QPROCS bit in the q_flag member of the read side queue to determine whether it has already been called for the queue pair. If the QPROCS bit is set, then procedures are disabled and no action is taken. If the QPROCS bit is clear, procedure are still enabled and the driver or module writer forgot to call qprocsoff(9) from the qi_qclose(9) procedure. (The driver or module could also have been written to uni-processor SVR 4, which did not have a qprocsoff(9) facility.)

qprocsoff(9) then performs the following actions:

a): The QPROCS and QNOENB flags are set for each queue.
b): The QENAB, QWANTR, QWANTW, bits are cleared for each queue.
c): The QB_WANTW bit is cleared in each queue band for each queue.
d): The queue pair is half-deleted from the Stream. That is, the q_next pointers of the Stream head and the top of the module stack are adjusted to bypass the queue pair being half-deleted.
e): The sd_minpsz and sd_maxpsz fields in the stdata(9) structure (Stream head) are ajusted to reflect the values of the driver or module now beneath the Stream head.

(3)

qdelete(9) is called to complete the half-deletion of the queue pair. qdelete(9) also releases the intial allocation reference to the queue pair. This often results in the immediate deallocation of the queue pair; however, if the Linux Fast-STREAMS scheduler is still holding a temporary reference to the queue pair, the queue pair will not be deallocated until that reference is released. When the last reference is released, freeq(9) is called to deallocate the queue pair.

freeq(9) performs the following actions:

a): The QUSE bit in the q_flag member of each queue in the queue pair is cleared indicating that the queue pair is deallocating.
b): flushq(9) is called with the FLUSHALL flag on each queue to flush all messages from each message queue. freebands() is called on each queue to unlink and deallocate each qband(9) structure linked to the q_bandp member of the queue structure.
c): Finally the peg counts of the number of queue pairs allocated is decremented, and the cache memory associated with the queue pair is released.

NOTICES

Members of the queue structure should not be accessed directly by STREAMS drivers or modules. Portable STREAMS drivers and modules should use the facilities provided by strqget(9) and strqset(9) for implementation and architecture independence.

The queue structure is only a subset of the queinfo structure used by the STREAMS scheduler. Additional hidden fields are present in the queinfo structure.

Note that the description in The Magic Garden Explained[4] says that setq(9) is called if the major device number changes in the device number returned by a driver's qi_qopen(9) procedure. This is because SVR 4 does not associate more than one streamtab(9) structure with a major device number. Linux Fast-STREAMS has the ability to associate a different streamtab(9) structure with each minor device number as well, so the entire device number is checked under Linux Fast-STREAMS.

COMPATIBILITY

The queue structure is compatible with SVR 4.2 MP DDI/DKI[5], and systems based on SVR 4.2, with the following portability considerations:

---: The flags defined for the q_flag member of the queue structure are not necessarily binary compatible with any given implementation.
: HP-UX®[6] defines the additional flags for the q_flag member of the queue structure not supported by Linux Fast-STREAMS as follows: QBACKTRACE, QPOP. HP-UX® does not document the QTOENAB, QSVCBUSY or QWCLOSE flags.
: Solaris®[3] defines the additional flags for the q_flag member of the queue structure not supported by Linux-Fast STREAMS as follows: QPAIR, QPERQ, QPERMOD, QMTSAFE, QMTOUTPERIM, QEND, QWANTWSYNC, QSYNCSTR, QISDRV, QHOT, QNEXTHOT, _QINSERTING and _QREMOVING. Solaris® does not document the QUP, QOLD, QTOENAB, QSYNCH, QSAFE or QWELDED flags.
: UnixWare®[7] defines the additional flags for the q_flag member of the queue structure not supported by Linux Fast-STREAMS as follows: QINTER, QBOUND, QDEFCNT and QMOVED. UnixWare® does not document the QOLD, QSAFE or QWELDED flags.
: AIX®[2] defines the additional flags for the q_flag member of the queue structure not supported by Linux Fast-STREAMS as follows: QUNWELDING, QPROTECTED and QEXECOPENCLOSE. AIX® does not document the QUP, QTOENAB, QSYNCH, QSAFE, QSVCBUSY or QWCLOSE flags.
: OSF/1®[8] defines the additional flags for the q_flag member of the queue structure not supported by Linux Fast-STREAMS as follows: none. OSF/1® does not document the QUP, QTOENAB, QSVCBUSY or QWCLOSE flags.
: LiS[9] defines the additional flags for the q_flag member of the queue structure not supported by Linux Fast-STREAMS as follows: QRETRY, QSCAN, QWASFULL and QWAITING. LiS does not provide the QUP, QOLD, QTOENAB, QSYNCH, QSAFE or QWELDED flags.
: UXP/V®[10] defines the additional flags for the q_flag member of the queue structure not supported by Linux Fast-STREAMS as follows: none. UXP/V® does not document the QUP, QBACK, QOLD, QHLIST, QTOENAB, QSAFE, QWELDED, QSVCBUSY or QWCLOSE flags.
: QUP is sometimes called QBLKING or QUPMODE. QHLIST is sometimes called QSCAN. QSYNCH is sometimes called QFREEZE or QLOCK. QSVCBUSY is sometimes called QINSERVICE or QRUNNING. QWCLOSE is sometimes called QCLOSEWT or QCLOSING. QPROCS is sometimes called QPROCSON or QPROCSOFF.
---: LiS uses a q_other member which is not present. LiS drivers or modules that manipulate this queue field directly will not be binary compatible. LiS drivers or modules that use only RD(9), WR(9), OTHERQ(9), will be compatible because they call external symbols provided by the LiS compatibility module. See, liscompat(9).
---: Any direct manipulation of any of the implementation specific members of the LiS structure by an LiS driver or module will result in binary incompatibility.
---: LiS does not provide the SVR 4.2 EFT[11] q_nband member.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: All versions of LiS contain the bug that they keep track of message queue counts, q_count, qb_count, in terms of the sum of the absolute sizes of the data buffers referenced by message blocks, (db_lim - db_base), and not the sizes of the message blocks themselves, (b_wptr - b_rptr), which does not conform to SVR 4.2 STREAMS[11]. See msgsize(9). No other implementation has this bug.
: Portable STREAMS applications programs, drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility considerations.

CONFORMANCE

SVR 4.2 EFT MP[12], Solaris®[3] documentation.

HISTORY

The queue structure was introduced in SVR 3[13].

REFERENCES

[1]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[2]: AIX® 5L Version 5.1, AIX STREAMS Programmers Guide, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[3]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[4]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9]
[5]: 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.
[6]: 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/>
[7]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[8]: 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/>
[9]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[10]: UXP/V® V10L10, UXP/V V10L10 Documentation, 1997, Fujitsu Limited, Fujitsu.
[11]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[12]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[13]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.