OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 20 Oct 2008 01:22:50 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
Quick Links

Download

SCTP

SIGTRAN

SS7

Hardware

STREAMS

Asterisk

Related

Package

Manual

FAQ

Man Pages

Applications

SS7 Stack

ISDN Stack

SIGTRAN Stack

VoIP Stack

MG Stack

SS7/ISDN Devices

IP Transport

Embedded Systems

OS

Documentation

FAQ

SIGTRAN

Design

Conformance

Performance

References

Man Pages

Manuals

Papers

Home

Overview

Status

Documentation

Resources

About

News

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci


MI_ACQUIRE_SLEEP

Section: The OpenSS7 Project DDI/DKI (9)
Updated: Sat, 24 Jun 2017 19:50:45 GMT
Index Return to Main Contents

NAME

mi_acquire_sleep, mi_acquire_sleep_nosignal - acquire a lock on a queue private structure

SYNOPSIS

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

caddr_t mi_acquire_sleep(caddr_t ptr, caddr_t *ptrp, rwlock_t *lockp, unsigned long *flagsp);
caddr_t mi_acquire_sleep_nosignal(caddr_t ptr, caddr_t *ptrp, rwlock_t *lockp, unsigned long *flagsp);

ARGUMENTS

ptr

a pointer to the private structure of the queue pair requesting the lock.
ptrp
a pointer to the location where the pointer to the private structure to lock is located.
lockp
is a pointer to a write-locked read-write lock used to protect the passed in locking location (or NULL for no lock).
flagsp
is a pointer to a flags word that was used to store the processor flag word when the write-lock was locked (or NULL for no flag word).

INTERFACE

MPS®-specific DDI.

Linux Fast-STREAMS specific.

DESCRIPTION

mi_acquire(), mi_acquire_sleep(9), mi_acquire_sleep_nosignal(9), and mi_release(9) are a set of per queue pair Stream locking functions that can be used with the functions from the mi_open_comm(9) family.

mi_acquire_sleep() attempts to lock the private structure associated with the pointer, *ptrp. When successful, the function returns a pointer to the private structure. When the lock cannot be immediately required, the calling process is put to sleep awaiting the release of the lock and awoken either on a signal, upon acquiring the lock, or upon pointer, *ptrp, becoming NULL. When unsuccessful (the process is interrupted by a signal, or pointer *ptrp, has become NULL), the function returns NULL.

mi_acquire_sleep_nosignal () acts as does mi_acquire_sleep (), except that the sleep will not be interrupted by a signal.

Before sleeping, if the lock pointer, lockp, is non-NULL, the lock will be unlocked for write before the sleep and locked again for write after the sleep. If the flags word pointer, flagsp, is also non-NULL, flags will be restored and saved in the flags word when unlocking and locking. After reacquiring the lock, the private structure pointer, *ptrp, will be rechecked for NULL. When the function exits, the lock, if provided, will be write locked and any flags stored in the flags word pointer.

USAGE

mi_acquire_sleep() and mi_acquire_sleep_nosignal() simplify the implementation of private structure locks for fully MP-SAFE STREAMS(9) modules and drivers. The functions attempt to lock the private structure associated with pointer, *ptrp, and serialize access to the associated private structure. While the lock is held, access to the private structure is exclusive to the lock holder.

mi_acquire_sleep() or mi_acquire_sleep_nosignal() are called during a open or close routine when the routine wishes exclusive access to the private structure (perhaps to alter state variables).

When mi_acquire_sleep() or mi_acquire_sleep_nosignal() fail to acquire the lock, the caller will sleep. When the lock is released by the current lock holder, the sleeping process will be woken. mi_acquire_sleep() will also be woken by a signal.

RETURN

When mi_acquire_sleep() or mi_acquire_sleep_nosignal() succeed, they returns a pointer to the locked private structure associated with pointer, *ptrp; when unsucessful, it returns NULL. When mi_acquire_sleep() or mi_acquire_sleep_nosignal() fail, it fails either because a signal was caught, or the pointer, *ptrp, has become NULL. The caller can determine which by testing *ptrp for NULL.

ERRORS

mi_acquire_sleep() fails and returns NULL when the process' sleep is interrupted by a signal. When mi_acquire_sleep() fails and returns NULL, the caller has the option of simply reinvoking mi_acquire_sleep().

CONTEXT

mi_acquire_sleep() and mi_acquire_sleep_nosignal() can be called from any blockable context, including user context, and module open and close procedures.

MP-STREAMS

mi_acquire_sleep() and mi_acquire_sleep_nosignal() are MP-safe, however, the caller is responsible for ensuring the validity of the passed in pointers across the call.

NOTICES

mi_acquire_sleep() or mi_acquire_sleep_nosignal() must only be called for a private structure that was allocated with mi_alloc(9) or mi_alloc_sleep(9), or one of the other private structure allocation functions from the mi_open_comm(9) family of functions.

Any queue that uses mi_acquire_sleep(9) or mi_acquire_sleep_nosignal(9) should have a queue service procedure.

Each successful call to mi_acquire_sleep() or mi_acquire_sleep_nosignal() must be matched with a corresponding call to mi_release(9) or processor or process deadlock may occur.

The lock acquired by mi_acquire_sleep() or mi_acquire_sleep_nosignal() on the private structure associated with pointer, *ptrp, is not a recursive lock. That is, if mi_acquire_sleep() or mi_acquire_sleep_nosignal() is called twice for the same pointer, *ptrp, and with no intervening mi_release(9), and the first call to mi_acquire_sleep() or mi_acquire_sleep_nosignal() succeeds, the second call will sleep indefinitely This is the best behaviour for STREAMS(9) open and close procedures which are seldomly written with reentrancy in mind.

IMPLEMENTATION

mi_acquire_sleep() and mi_acquire_sleep_nosignal() are implemented using synchronization variable lock functions. See SV_WAIT_SIG(9) and SV_WAIT(9) for more information.

SEE ALSO

mi_acquire(9), mi_release(9), SV_WAIT_SIG(9), mpscompat(9), aixcompat(9), maccompat(9), STREAMS(9).

BUGS

mi_acquire_sleep() and mi_acquire_sleep_nosignal() have no known bugs.

COMPATIBILITY

mi_acquire_sleep() and mi_acquire_sleep_nosignal() are compatible with MPS®, AIX®, MacOT®, and Solaris®, with the following portability considerations:

---
mi_acquire_sleep() and mi_acquire_sleep_nosignal() are OpenSS7 Project specific implementations of an MPS®-compatible function and should not be used by portable STREAMS drivers and modules.
---
mi_acquire_sleep() and mi_acquire_sleep_nosignal() are provided for use with SS7 drivers and modules that need some automatic locking of queue pair private structure for speed and efficiency.
---
mi_acquire_sleep() and mi_acquire_sleep_nosignal() do not exist in any other MPS® implementation other than Linux Fast-STREAMS.

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

CONFORMANCE

Conforms to OpenSS7 documentation.

HISTORY

mi_acquire_sleep() and mi_acquire_sleep_nosignal() are new for The OpenSS7 Project. They are largely equivalent to the ss7_trylock(9) SS7 common function that appeared in early releases of the strss7 package and is also contained in The OpenSS7 Project.

IDENTIFICATION

The OpenSS7 Project: Package OpenSS7 version 0.9.2 released Sat, 24 Jun 2017 19:50:45 GMT.

Copyright©1997-2008OpenSS7 Corp.
All Rights Reserved.
(See roff source for permission notice.)



Index

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

This document was created by man2html, using the manual pages.
Time: 19:50:45 GMT, June 24, 2017
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
Last modified: Mon, 20 Oct 2008 01:22:50 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.