QUEUE man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

QUEUE(9S)							     QUEUE(9S)

NAME
       queue - STREAMS queue structure

SYNOPSIS
       #include <sys/stream.h>

INTERFACE LEVEL
       Architecture independent level 1 (DDI/DKI)

DESCRIPTION
       A  STREAMS  driver or module consists of two queue structures: read for
       upstream processing and write for  downstream  processing.   The	 queue
       structure is the major building block of a stream.

   queue Structure Members
       The  queue  structure  is defined as type queue_t. The structure can be
       accessed at any time from inside a STREAMS entry point associated  with
       that queue.

	 struct	   qinit   *q_qinfo;	 /* queue processing procedure */
	 struct	   msgb	   *q_first;	 /* first message in queue */
	 struct	   msgb	   *q_last;	 /* last message in queue */
	 struct	   queue   *q_next;	 /* next queue in stream */
	 void		   *q_ptr;	 /* module-specific data */
	 size_t		    q_count;	 /* number of bytes on queue */
	 uint_t		    q_flag;	 /* queue state */
	 ssize_t	    q_minpsz;	 /* smallest packet OK on queue */
	 ssize_t	    q_maxpsz;	 /* largest packet OK on queue */
	 size_t		    q_hiwat;	 /* queue high water mark */
	 size_t		    q_lowat;	 /* queue low water mark */

       Contstraints  and  restrictions on the use of q_flag and queue_t fields
       and the q_next values are detailed in the following sections.

   q_flag Field
       The q_flag field must be used only to check the following flag values.

       QFULL
		 Queue is full.

       QREADR
		 Queue is used for upstream (read-side) processing.

       QUSE
		 Queue has been allocated.

       QENAB
		 Queue has been enabled for service by qenable(9F).

       QNOENB
		 Queue will not be scheduled for service by putq(9F).

       QWANTR
		 Upstream processing element wants to read from queue.

       QWANTW
		 Downstream processing element wants to write to queue.

   queue_t Fields
       Aside from q_ptr and q_qinfo, a module or driver must never assume that
       a  queue_t  field  value	 will remain unchanged across calls to STREAMS
       entry points. In addition, many	fields	can  change  values  inside  a
       STREAMS	entry  point,  especially  if the STREAMS module or driver has
       perimeters that allow parallelism. See mt-streams(9F). Fields that  are
       not  documented below are private to the STREAMS framework and must not
       be accessed.

	   o	  The values of the q_hiwat, q_lowat, q_minpsz,	 and  q_maxpsz
		  fields  can  be  changed  at the discretion of the module or
		  driver.  As such, the stability of their values  depends  on
		  the  perimeter  configuration	 associated  with any routines
		  that modify them.

	   o	  The values of the q_first, q_last, and  q_count  fields  can
		  change  whenever putq(9F), putbq(9F), getq(9F), insq(9F), or
		  rmvq(9F) is used on the queue. As  such,  the	 stability  of
		  their	 values depends on the perimeter configuration associ‐
		  ated with any routines that call those STREAMS functions.

	   o	  The q_flag field can change at any time.

	   o	  The q_next field  will  not  change  while  inside  a	 given
		  STREAMS  entry  point. Additional restrictions on the use of
		  the q_next value are described in the next section.

       A STREAMS module or driver can assign any  value	 to  q_ptr.  Typically
       q_ptr is used to point to module-specific per-queue state, allocated in
       open(9E) and freed in close(9E). The value  or  contents	 of  q_ptr  is
       never inspected by the STREAMS framework.

       The initial values for q_minpsz, q_maxpsz, q_hiwat, and q_lowat are set
       using the module_info(9S) structure when mod_install(9F) is  called.  A
       STREAMS module  or  driver  can subsequently change the values of those
       fields as necessary. The remaining visible  fields,  q_qinfo,  q_first,
       q_last, q_next, q_count, and q_flag, must never be modified by a module
       or driver.

       The Solaris DDI requires that STREAMS  modules  and  drivers  obey  the
       rules  described	 on  this page. Those that do not follow the rules can
       cause data corruption or system instability, and might change in behav‐
       ior across patches or upgrades.

   q_next Restrictions
       There are additional restrictions associated with the use of the q_next
       value. In particular, a STREAMS module or driver:

	   o	  Must not access the data structure pointed to by q_next.

	   o	  Must not rely on the value of q_next before  calling	qproc‐
		  son(9F) or after calling qprocsoff(9F).

	   o	  Must	not pass the value into any STREAMS framework function
		  other than  put(9F),	canput(9F),  bcanput(9F),  putctl(9F),
		  putctl1(9F).	However,  in  all  cases the "next" version of
		  these functions, such as putnext(9F), should be preferred.

	   o	  Must not use the value to  compare  against  queue  pointers
		  from	other  streams.	 However, checking q_next for NULL can
		  be used to distinguish a module from a driver in code shared
		  by both.

SEE ALSO
       close(9E),   open(9E),  bcanput(9F),  canput(9F),  getq(9F),  insq(9F),
       mod_install(9F),	 put(9F),  putbq(9F),  putctl(9F),  putctl1(9F),  put‐
       next(9F), putq(9F), qprocsoff(9F), qprocson(9F), rmvq(9F), strqget(9F),
       strqset(9F), module_info(9S), msgb(9S), qinit(9S), streamtab(9S)

       Writing Device Drivers

       STREAMS Programming Guide

				 Jan 10, 2006			     QUEUE(9S)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net