Manpage of MPS_BECOME_WRITER

MPS_BECOME_WRITER

Section: OpenSS7 STREAMS Compatibility DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

mps_become_writer - STREAMS mutex upgrade

SYNOPSIS

#define _MAC_SOURCE
#include <sys/ddi.h>
#include <sys/macddi.h>

typedef void (*proc_ptr_t)(queue_t *, mblk_t *);
void mps_become_writer(queue_t *q, mblk_t *mp, proc_ptr_t proc);

ARGUMENTS

q: a pointer to the queue for which to upgrade to writer.
mp: a STREAMS message to pass to the call-out function.
proc: a function that will be called when write access has been acheived.

DESCRIPTION

mps_become_writer() schedules the call-out function, proc, to be executed with the specified queue pair, q, and the passed in message, mp, once the driver or module queue can be entered exclusively.

If there is no synchronization in effect for the queue, q, then this function has the same effect as calling proc directly with q and mp as arguments.

USAGE

mps_become_writer() allows non-STREAMS software to safely call STREAMS utilities. Non-STREAMS code can call mps_become_writer(), passing it a function and a queue pointer, q. OpenSS7 STREAMS Compatibility runs the function as it it were the queue's qi_putp(9) procedure. The function can safely manipulate the queue and access the same data structure as the queue's qi_putp(9) procedure. mps_become_writer() passes q and mp to proc. The caller must pass a valid message block pointer, mp, because OpenSS7 STREAMS Compatibility uses fields in the message block not visible to the STREAMS programmer.

RETURN

When mps_become_writer() succeeds, it returns true (1); when it fails, it returns false (0).

ERRORS

mps_become_writer() fails when q or mp are invalid.

CONTEXT

mps_become_writer() can be called from any context.

MP-STREAMS

msp_become_writer() is MP-safe and was intended to support MP-safe operation in the SMP environment.

Considerations should be given when writing the call-out function that the function may execute in parallel with asynchronous entry points, callbacks, call-outs and interrupt service procedures.

However, in OpenSS7 STREAMS Compatibility, the call-out function is scheduled on the same CPU and the CPU which called mps_become_writer(). This means that mps_become_writer() will return before the call-out function executes when called on the ICS. Also, when called on the ICS, the call-out function will not execute before the calling function returns or the next preemption point is encountered.

When called from any other context, the call-out function will execute before the call returns.

NOTICES

mps_become_writer() is a MacOT®-specific function: _MAC_SOURCE must be defined before including DDI/DKI include files to expose this symbol. OpenSS7 STREAMS Compatibility must also have been compiled with CONFIG_STREAMS_COMPAT_MAC or CONFIG_STREAMS_COMPAT_MAC_MODULE defined.

IMPLEMENTATION

OpenSS7 STREAMS Compatibility uses a single mechanism, __strwrit(), for supporting all queue writer functions such as qwriter(9) and mps_become_writer(), and a single mechanism, __strfunc(), for supporting all queue put function such as streams_put(9).

When called on the ICS, execution of the call-out function is deferrred until the next run of the STREAMS scheduler, strqsched(9), and the function simply returns. When called from any other context, synchronization is performed and the call-out function is executed immediately thereafter and before returning. See mp-streams(9) for more information.

BUGS

mps_become_writer() has no known bugs.

COMPATIBILITY

mps_become_writer() is compatible with MacOT® with the following portability considerations:

---: mps_become_writer() is an MacOT®-specific function and should not be used by portable STREAMS drivers and modules. The standard freezestr(9) and put(9) functions should be used in its stead.
---: mps_become_writer() is provided for source level compatibility with MacOT® for the purpose of porting MacOT® drivers to Linux. Because internal structures and definitions for OpenSS7 STREAMS Compatibility[1] differ from that of MacOT®, binaries are incompatible.
---: mps_become_writer() only provides functionality comparable to MacOT® for use by STREAMS drivers and modules. Any and all functionality provided by mps_become_writer() in support of non-STREAMS devices are not supported.

See maccompat(9) and STREAMS(9) for additional compatibility considerations.

CONFORMANCE

MacOT® DDI documentation[2, 3].

HISTORY

mps_become_writer() first appeared in MacOT®. mps_become_writer() is probably a Mentat, Inc. function that goes all the way back to the pre-OSF/1 Mentat implementations.

REFERENCES

[1]: strcompat-0.9.2, STREAMS Compatibility Modules (strcompat) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[2]: Mac OS 9, Open Transport Reference, 2003, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macros/opentransport/>
[3]: Revision 1.5d2, Open Transport Module Developer Note, June 18, 1996, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macos/opentransport/>

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

OpenSS7 STREAMS Compatibility: Package strcompat version 0.9.2.7 released 2008-10-31.

Index

NAME
SYNOPSIS
ARGUMENTS
DESCRIPTION
USAGE
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
IMPLEMENTATION
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 03:38:27 GMT, May 22, 2013