.TH QIO 10.2.SH NAMEqio: qget, qdiscard, qconsume, qpass, qproduce, qcopy, qopen, qbread, qread, qbwrite, qwrite, qiwrite, qfree, qclose, qhangup, qreopen, qlen, qwindow, qcanread, qsetlimit, qnoblock, qflush, qfull \- queued I/O for devices.SH SYNOPSIS.ta \w'\fLQueue*  'u.BQueue*	qopen(int limit,int msg, void (*kick)(void*),void *arg).PP.Bvoid	qhangup(Queue *q, char *reason).PP.Bvoid	qclose(Queue *q).PP.Bvoid	qreopen(Queue *q).PP.Bvoid	qfree(Queue *q).PP.Blong	qbwrite(Queue *q, Block *b).PP.Blong	qwrite(Queue *q, void *buf, int len).PP.Bint	qpass(Queue *q, Block *b).PP.Bint	qpassnolim(Queue *q, Block *b).PP.Bint	qproduce(Queue *q, void	*buf, int len).PP.Bint	qiwrite(Queue *q, void *buf, int len).PP.BBlock*	qbread(Queue *q, int len).PP.Blong	qread(Queue *q, void *buf, int len).PP.BBlock*	qcopy(Queue *q, int len, ulong offset).PP.BBlock*	qget(Queue *q).PP.Bint	qconsume(Queue *q, void *buf, int len).PP.Bint	qdiscard(Queue *q, int len).PP.Bvoid	qflush(Queue *q).PP.Bint	qlen(Queue *q).PP.Bint	qwindow(Queue *q).PP.Bint	qcanread(Queue *q).PP.Bvoid	qsetlimit(Queue *q, int limit).PP.Bvoid	qnoblock(Queue *q, int nonblock).PP.Bint	qfull(Queue *q);.SH DESCRIPTIONThis suite of functions provides serial data buffering for device drivers.Data is stored in a.B Queuestructure as a sequence of variable-sized.BR Blocks ;see.IR allocb (10.2)..PP.I Qopeninitialises and returns a pointer to a new.BR Queue ,configuring it according to the following parameters:.TF limit.PD.TP.I limitSet the queue limit (high water mark) in bytes..TP.I msgSet message mode if non-zero; otherwise, stream mode (discussed below)..TP.I kickOptional flow-control function called by.I qbreadto restart writers, and by.I qbwrite(also.IR qiwrite )to restart readers..TP.I argArgument to pass to.I kick.PP.I Qhangupmarks.I qas `hung up'for the given.IR reason.RB ( Ehungupby default).Subsequent attempts to write to the queue raise an.IR error (10.2)..I Qhangupdoes not flush the queue: subsequent read requests arehandled normally until the queue empties..I Qreadand the other functions then return their conventional valuesfor a hungup stream: 0, -1 or a null pointer, depending on the function.After a few such attempts by any process, an.IR error (10.2)is raised (typically.BR Ehungup )on each subsequent read..PPIf queued data is left unread, and not flushed by.I qflushor.IR qclose ,the data will again be readable following a subsequent.IR qreopen ..PP.I Qclosealso marks a given.I qas `hung up',but removes and frees any queued data Blocks..I Qcloseignores calls when.I qis null..PP.I Qreopenmakes a closed or hung up queue available for use again.The queue's data limit is reset to the.I limitvalue given when the queue was first created by.IR qopen ,cancelling the effect of any previous call to.IR qsetlimit ..PP.I Qfreecloses.I qwith.I qcloseand frees it.The caller must ensure that no references remain;these functions do not keep a reference count..SS "Flow control"The queue I/O routines provide a flow control mechanism to coordinate producers and consumers.Each queue has a limit on the number of bytes queued, its `high water mark',initially set when the queue is created, but adjustable by.IR qsetlimit ,below. The low water mark is not set explicitly:it is always half the current queue limit.When the high water mark is exceeded, writes normally block until a reader drains thequeue below its low water mark; the writer is then allowed to proceed.Conversely, readers normally block when the queue is empty, until a writerarrives with data, or the queue is closed..PPA queue can be given a.I kickfunction when the queue is created by.IR qopen .The function is invoked by.IR qreadand.IR qbread ,to prod an output routine when the queue falls below the low-water mark, and by.IR qwrite ,.IR qbwriteand.IR qiwrite ,to notify a reader that a queue is no longer empty.Because.I kickis called from the reading (or writing) process, or an interrupt handler, itmust not block..PPInterrupt handlers must not.IR sleep (10.2),and are therefore restricted to using only the non-blocking functions described below..SS "Stream mode and message mode"In stream mode,no read will return more than oneblockof data, buta read can split a block that contains more data than requested, leaving the remainderin a new block at the front of the Queue.Writes of more than the maximum.B Blocksize (currently 128k bytes)are split into as many Blocks as required, each written separately to the queue,in order, but with possible flow-control between them.The queue is locked meanwhile, however, so that data from other writers is not intermingled..PPIn message mode, by contrast, a read will return at mostone block's worth of data, but the remainder of a partially-read block will be discarded,not returned to the queue.If a write count exceeds the maximum.B Blocksize, the excess data is discarded:at most a single block can be queued..PPThe mode of the queue should be taken into account in the descriptions belowof the following functions:.IR qwrite ,.IR qiwrite ,.IR qbreadand.IR qconsume .No other functions are aware of the distinction..SS "Write operations (flow controlled)".I Qwritecopies.I lenbytes of data from.I bufinto one or more.B Blockswhich it places on the.IR q ..I Qwritealways returns.IR len .It can implement message mode..PP.I Qbwriteplaces the single Block.I bon the tail of.IR q ,waking any sleeping reader.If the queue is full, thewriting process blocks until a readerhas reduced the queued data tothe low-water mark;if the queue is non-blocking(see.I qnoblockbelow),the data is discarded without notice..I Qbwritenormally returns.IR len ,but raises an.IR error (10.2)if the queue is closed (see.I qhangupand.IR qclose ).The block.I bis always freed.Note that.I bcan be empty (zero-length), to punctuate the data in a queue..I Qbwritecannot handle a list of Blocks;.I qpassmust be used instead..SS Non-blocking writes.PP.I Qproducereturns -1immediately  if.I qis full.Otherwise, it queues.I lenbytes of data from.I bufin a single.B Blockon.I qand returns the number of bytes written..PP.I Qpassattempts to place the list of Blocks headed by.I bon.IR q ,returning the number of bytes written if successful.If.I qwas full, itfrees the Block list.I band returns -1..PP.I Qpassnolimputs the Block list.I bon.I qregardless of flow control; it returns the number of bytes in the list.IR b ..PP.I Qiwriteis a variant of.I qwriteused exclusively by the kernel print function,to allow printing by interrupt handlers;.I qiwritecould be used with care by other routines, but.IR qproduceis preferable..I Qiwritewrites the.I lenbytes of data at.I bufinto the.I qwithout regard to flow control;the writer never blocks.The queue is assumed to be open..I Qiwritealways returns.IR len .It can implement message mode..SS "Read operations (flow controlled)".I Qbreadblocks until data arrives on.IR q ,thenreturns the first.BR Block ;it limits the data returnedto.I lenbytes (in the manner depending on the mode of.IR q ).It returns a null pointer if the queue has hung up..PP.I Qreadreads a Block of up to.I lenbytes from.I qusing.IR qbread ,and copies the data in the Block into.IR buf ,then frees the Block and returnsthe number of bytes read..I Qreadreturns 0 on end of file or error (hangup).It can implement message mode..PP.I Qcopyreturns a Block with a copy of data from the queue (the data remains on the queue).The copy begins.I offsetbytes into the queue's data and proceeds until.I lenbytes have been copied or no more data remains.The Block's read and write pointers delimit the data copied into it..I Qcopycan be used by a reliable transport protocol to copy a packet for transmission,leaving the data queued for possible retransmission, if unacknowledged..SS Non-blocking reads.PP.I Qconsumereturns -1 immediately if.I qis empty.Otherwise, itcopies up to.I lenbytes from the first.B Blockon the queue into.IR buf ,returning the number of bytes copied.It can implement message mode..PP.I Qgetreturns a null pointer immediately if.I qis empty or closed.Otherwise, itreturns the first.B Blockon the queue..SS "Discard and flush".I Qdiscardremoves the first.I lendata bytes from.IR q ;it returns the number of bytes actually discarded, in casethe queue is shorter than.IR len .If the queue drains below the low-water mark,.I qdiscardwakes any sleeping writers.Since it does not block,.I qdiscardcan safely be called from interrupt handlers.It is useful in transport protocol drivers to remove data from the queueonce acknowledged..PP.I Qflushdiscards all data waiting on.IR q ,waking any waiting writer..SS "Queue status"The following functions return a Queue's status.Note that between a call to one of these functions and another operation,the state can change if a driver allows concurrent access byeither another process or an interrupt handler..PP.I Qlenreturns the number of bytes queued on.IR q ..PP.I Qwindowreturns the number of bytes that can be written before reaching the queue's high-water mark.A return of 0 means that a write operation will certainly block;a non-zero return gives no guarantees (see.IR qfull ,below)..PP.I Qcanreadreturns 1 if any data queued is queued. A subsequent read operation will not block..PP.I Qfullreturns non-zero if.I qis flow-controlled and a write would block or a non-blocking write would return an error.(Note that the implementation allows.I qwindowto return non-zero yet.I qfullto return true.).SS "Queue control".I Qsetlimitsets the high water mark for the queue to.IR limit .Note that.I qopensaves the initial queue limit.If the queue is closed and reopened (by.IR qreopen )that initial limit is restored..PP.I Qnoblocksets or resets non-blocking mode.If.I nonblockis non-zero,the queue becomes non-blocking, anddata written to a queue beyond its high water mark is discardedby calls that would otherwise block..SH SOURCE.B /os/port/qio.c.br.B /emu/port/qio.c.SH SEE ALSO.IR allocb (10.2),.IR ref (10.2)