srv Utility

Purpose

Services queued messages for STREAMS modules or drivers.

Syntax

#include <sys/types.h> 
#include <sys/stream.h>
#include <sys/stropts.h>

Parameters

Description

The optional service (<prefix>srv) routine can be included in a STREAMS module or driver for one or more of the following reasons:

• To provide greater control over the flow of messages in a stream
• To make it possible to defer the processing of some messages to avoid depleting system resources
• To combine small messages into larger ones, or break large messages into smaller ones
• To recover from resource allocation failure. A module's or driver's put 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 routine, which may or may not do some processing. It must then either:

• Pass the message to the next stream component with putnext
• If a srv routine has been included, it may call putq to place the message on the queue

Once a message has been enqueued, the STREAMS scheduler controls the invocation of the service routine. Service routines are called in FIFO order by the scheduler. No guarantees can be made about how long it will take for a srv routine to be called except that it will happen before any user level process is run.

Every stream component (stream head, module or driver) has limit values it uses to implement flow control. Tunable high and low water marks should be checked 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 minimum, a stream must distinguish between normal (priority zero) messages and high priority messages (such as M_IOCACK). High priority messages 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 on the implementation, the direction of flow (upstream or downstream), and whether it is for a module or a driver.

1. Use getq to get the next enqueued message.
2. If the message is high priority, process it (if appropriate) and pass it to the next stream component with putnext.
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 canput or bcanput to determine if this can be done.
4. If the message cannot be passed, put it back on the queue with putbq. If it can be passed, process it (if appropriate) and pass it with putnext.

Rules for service routines:

1. Service routines must not call any kernel services that sleep or are not interrupt safe.
2. Service routines are called by the STREAMS scheduler with most interrupts enabled.

   Note: 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 structure. Do not use nulldev instead of the NULL pointer. Use of nulldev for a srv routine may result in flow control errors.

   Prior to AIX 4.1, STREAMS service routines were permitted which were not coded to specification (that is, the service routine called sleep or called kernel services that slept, other possibilities). In AIX 4.1, this behavior will cause a system failure because the STREAMS scheduler is executed with some interrupts disabled. Modules or drivers can force the old style scheduling by setting the sc_flags field of the kstrconf_t structure to STR_Q_NOTTOSPEC. This structure is passed to the system when the module or driver calls the str_install STREAMS service. This flag will cause STREAMS to schedule the module's or driver's service routines with all interrupts enabled. There is a severe performance penalty for this type of STREAMS scheduling and future releases of AIX may not support STR_Q_NOTTOSPEC.

Return Values

Ignored.

Related Information

put, bcanput, canput, getq, putbq, putnext, putq utilities.

The queue structure in /usr/include/sys/stream.h.

The STREAMS Entry Points article in InfoExplorer.