Manpage of MI_TIMER_Q_SWITCH

MI_TIMER_Q_SWITCH

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

NAME

mi_timer_q_switch - switch STREAMS queues for a timer message

SYNOPSIS

#define _MPS_SOURCE
#include <sys/stream.h>
#include <sys/ddi.h>
#include <sys/mpsddi.h>

void mi_timer_q_switch(mblk_t *mp, queue_t *q, mblk_t *new_mp);

ARGUMENTS

mp: a pointer to the existing timer message.
q: a pointer to the STREAMS queue to which the timer message is to be switched.
new_mp: a pointer to a new timer message in case the old one cannot be cancelled.

INTERFACE

MPS®-specific DDI.

DESCRIPTION

mi_timer_q_switch() switches the timer message, mp, from its current queue to the new queue specified by the q argument. Because it might not be possible to cancel the current timer, mp, a new timer message, new_mp, must be provided to the function for use the case that mp, cannot be cancelled. mi_timer_q_switch () will return the pointer to the message that represents the new timer.

USAGE

mi_timer_q_switch() is similar to mi_timer_move(9); however, mi_timer_move(9) is far easier to use. mi_timer_q_switch() can be used in the same circumstances as mi_timer_move(9), that is, whenever it is desired to move timers from their original targeted queue to a new one.

mi_timer_q_switch() is a little more cumbersome in that it requires the pre-allocation of a fallback timer message, should it be impossible to cancel the existing one, and the handling of the disposition of these timer messages after the call returns.

RETURN

mi_timer_q_switch() returns a pointer to the new timer message block (either mp or new_mp).

ERRORS

mi_timer_q_switch() is always successful. If mi_timer_q_switch() is passed NULL or invalid pointers, or pointers to invalid structures, as arguments, the kernel may become unstable and a kernel panic may ensue.

CONTEXT

mi_timer_q_switch() can be called from any context; however, it is intended to be called from a STREAMS driver or module qi_putp(9) or qi_srvp(9) procedure, or qi_qopen(9) or qi_qclose(9) routine.

MP-STREAMS

mi_timer_q_switch() is MP-safe. It uses atomic exchanges to guarantee atomicity of timer state.

NOTICES

mi_timer_q_switch() is an MPS®-specific function: _MPS_SOURCE, _AIX_SOURCE or _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_MPS, CONFIG_STREAMS_COMPAT_MPS_MODULE, CONFIG_STREAMS_COMPAT_AIX, CONFIG_STREAMS_COMPAT_AIX_MODULE, CONFIG_STREAMS_COMPAT_MAC or CONFIG_STREAMS_COMPAT_MAC_MODULE defined.

IMPLEMENTATION

mi_timer_q_switch() attempts to cancel the existing timer message, mp, using mi_timer_cancel(9). If the timer was cancelled and is not queued, it is restarted using mi_timer(9) for the time remaining on the timer but with the new queue as a target, and the existing message pointer will be returned.

If the timer message, mp, was queued at the time that it was cancelled, the new timer message will be started for the time remaining on the timer at cancellation and the new message pointer will be returned.

BUGS

mi_timer_q_switch() has no known bugs.

COMPATIBILITY

mi_timer_q_switch() is compatible with MPS®, AIX®, MacOT®, and Solaris®, with the following portability considerations:

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

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

CONFORMANCE

MPS® DDI documentation, MacOT® DDI documentation[2, 3], AIX® documentation[4].

HISTORY

mi_timer_q_switch() first appeared in MPS®. mi_timer_q_switch() is a Mentat, Inc. function that goes all the way back to the pre-OSF/1 Mentat implementations. mi_timer_q_switch() appears in MacOT®[3] and AIX®[4]. An undocumented version of mi_timer_q_switch() appears in Solaris®.

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/>
[4]: AIX® 5L Version 5.1, AIX Communications Programming Concepts, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>

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
INTERFACE
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: 08:10:22 GMT, May 25, 2013