putbq(9f) [bsd man page]
putbq(9F) Kernel Functions for Drivers putbq(9F) NAME
putbq - place a message at the head of a queue SYNOPSIS
#include <sys/stream.h> int putbq(queue_t *q, mblk_t *bp); INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI). PARAMETERS
q Pointer to the queue. bp Pointer to the message block. DESCRIPTION
putbq() places a message at the beginning of the appropriate section of the message queue. There are always sections for high priority and ordinary messages. If other priority bands are used, each will have its own section of the queue, in priority band order, after high prior- ity messages and before ordinary messages. putbq() can be used for ordinary, priority band, and high priority messages. However, unless precautions are taken, using putbq() with a high priority message is likely to lead to an infinite loop of putting the message back on the queue, being rescheduled, pulling it off, and putting it back on. This function is usually called when bcanput(9F) or canput(9F) determines that the message cannot be passed on to the next stream compo- nent. The flow control parameters are updated to reflect the change in the queue's status. If QNOENB is not set, the service routine is enabled. RETURN VALUES
putbq() returns 1 upon success and 0 upon failure. Note - Upon failure, the caller should call freemsg(9F) to free the pointer to the message block. CONTEXT
putbq() can be called from user or interrupt context. EXAMPLES
See the bufcall(9F) function page for an example of putbq(). SEE ALSO
bcanput(9F), bufcall(9F), canput(9F), getq(9F), putq(9F) Writing Device Drivers STREAMS Programming Guide SunOS 5.10 28 Aug 2001 putbq(9F)
Check Out this Related Man Page
srv(9E) Driver Entry Points srv(9E) NAME
srv - service queued messages SYNOPSIS
#include <sys/types.h> #include <sys/stream.h> #include <sys/stropts.h> #include <sys/ddi.h> #include <sys/sunddi.h> intprefixrsrv(queue_t *q); /* read side */ intprefixwsrv(queue_t *q); /* write side */ INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI). This entry point is required for STREAMS. ARGUMENTS
q Pointer to the queue(9S) structure. DESCRIPTION
The optional service srv() routine may be included in a STREAMS module or driver for many possible reasons, including: o to provide greater control over the flow of messages in a stream; o to make it possible to defer the processing of some messages to avoid depleting system resources; o to combine small messages into larger ones, or break large messages into smaller ones; o to recover from resource allocation failure. A module's or driver's put(9E) routine can test for the availability of a resource, and if it is not available, enqueue the message for later processing by the srv() routine. A message is first passed to a module's or driver's put(9E) routine, which may or may not do some processing. It must then either: o Pass the message to the next stream component with putnext(9F). o If a srv() routine has been included, it may call putq(9F) to place the message on the queue. Once a message has been enqueued, the STREAMS scheduler controls the service routine's invocation. The scheduler calls the service routines in FIFO order. The scheduler cannot guarantee a maximum delay srv() routine to be called except that it will happen before any user level process are run. Every stream component (stream head, module or driver) has limit values it uses to implement flow control. Each component should check the tunable high and low water marks to stop and restart the flow of message processing. Flow control limits apply only between two adjacent components with srv() routines. STREAMS messages can be defined to have up to 256 different priorities to support requirements for multiple bands of data flow. At a mini- mum, a stream must distinguish between normal (priority zero) messages and high priority messages (such as M_IOCACK). High priority mes- sages are always placed at the head of the srv() routine's queue, after any other enqueued high priority messages. Next are messages from all included priority bands, which are enqueued in decreasing order of priority. Each priority band has its own flow control limits. If a flow controlled band is stopped, all lower priority bands are also stopped. Once the STREAMS scheduler calls a srv() routine, it must process all messages on its queue. The following steps are general guidelines for processing messages. Keep in mind that many of the details of how a srv() routine should be written depend of the implementation, the direction of flow (upstream or downstream), and whether it is for a module or a driver. 1. Use getq(9F) to get the next enqueued message. 2. If the message is high priority, process (if appropriate) and pass to the next stream component with putnext(9F). 3. If it is not a high priority message (and therefore subject to flow control), attempt to send it to the next stream component with a srv() routine. Use bcanputnext(9F) to determine if this can be done. 4. If the message cannot be passed, put it back on the queue with putbq(9F). If it can be passed, process (if appropriate) and pass with putnext(). RETURN VALUES
Ignored. SEE ALSO
put(9E), bcanput(9F), bcanputnext(9F), canput(9F), canputnext(9F), getq(9F), nulldev(9F), putbq(9F), putnext(9F), putq(9F), qinit(9S), queue(9S) Writing Device Drivers STREAMS Programming Guide WARNINGS
Each stream module must specify a read and a write service srv() routine. If a service routine is not needed (because the put() routine processes all messages), a NULL pointer should be placed in module's qinit(9S) structure. Do not use nulldev(9F) instead of the NULL pointer. Use ofnulldev(9F) for a srv() routine can result in flow control errors. SunOS 5.10 12 Nov 1992 srv(9E)