man/man9f/qwriter.9f

         te
 Copyright (c) 1993, Sun Microsystems, Inc., All Rights Reserved
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 QWRITER 9F "Mar 1, 1993"
 NAME
qwriter - asynchronous STREAMS perimeter upgrade
 SYNOPSIS
#include <sys/stream.h>
#include <sys/ddi.h>


void qwriter(queue_t *qp, mblk_t *mp, void (*func)(), int perimeter);


 INTERFACE LEVEL
illumos DDI specific (illumos DDI).
 PARAMETERS
qp

Pointer to the queue.


mp

Pointer to a message that will be passed in to the callback function.


func

A function that will be called when exclusive (writer) access has been acquired
at the specified perimeter.


perimeter

Either PERIM_INNER or PERIM_OUTER.


 DESCRIPTION
qwriter() is used to upgrade the access at either the inner or the outer
perimeter from shared to exclusive and call the specified callback function
when the upgrade has succeeded. See mt-streams(9F). The callback function
is called as:
(*func)(queue_t *qp, mblk_t *mp);


qwriter() will acquire exclusive access immediately if possible, in which
case the specified callback function will be executed before qwriter()
returns. If this is not possible, qwriter() will defer the upgrade until
later and return before the callback function has been executed. Modules should
not assume that the callback function has been executed when qwriter()
returns. One way to avoid dependencies on the execution of the callback
function is to immediately return after calling qwriter() and let the
callback function finish the processing of the message.

When qwriter() defers calling the callback function, the STREAMS
framework will prevent other messages from entering the inner perimeter
associated with the queue until the upgrade has completed and the callback
function has finished executing.
 CONTEXT
qwriter() can only be called from an put(9E) or srv(9E)
routine, or from a qwriter(), qtimeout(9F), or qbufcall(9F)
callback function.
 SEE ALSO
put(9E), srv(9E), mt-streams(9F), qbufcall(9F),
qtimeout(9F)

STREAMS Programming Guide

Writing Device Drivers