canputnext(D3DK) —

.IX \f4canputnext\fP(D3DK)
.IX STREAMS message queues
.IX message (STREAMS)

NAME

canputnext − test for flow control in a stream

SYNOPSIS

#include <sys/stream.h>
int canputnext(queue_t ∗q);

ARGUMENTS

qPointer to a message queue.

DESCRIPTION

canputnext searches through the stream (starting at q->q_next) until it finds a queue containing a service routine, or until it reaches the end of the stream. If found, the queue containing the service routine is tested to see if there is room for a message in the queue. If the queue is full, canputnext marks the queue to automatically back-enable the caller’s service routine when the amount of data in messages on the queue has reached its low water mark.

It is possible because of race conditions to test for room using canputnext and get an indication that there is room for a message, and then have the queue fill up before subsequently enqueuing the message, causing a violation of flow control. This is not a problem since the violation of flow control in this case is bounded.

RETURN VALUE

canputnext returns 1 if a message can be sent in the stream, or 0 if the stream is flow-controlled. If canputnext reaches the end of the stream without finding a queue with a service routine, then it returns 1.

LEVEL

Base or Interrupt.

NOTES

Does not sleep. The driver writer is responsible for both testing a queue with canputnext and refraining from placing a message on the queue if canputnext fails. Driver defined basic locks, read/write locks, and sleep locks may be held across calls to this function. The q argument may not reference q_next (e.g. an argument of q->q_next is erroneous on a multiprocessor and is disallowed by the DDI/DKI). canputnext(q) is provided as a multiprocessor-safe equivalent to the common call canput(q->q_next), which is no longer allowed.

Museum