OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 28 Apr 2008 16:47:03 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manpage of MI_ACQUIRE
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

Manpage of MI_ACQUIRE

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

Section: The OpenSS7 Project DDI/DKI (9)
Updated: Tue, 22 Aug 2017 20:31:35 GMT
Index Return to Main Contents

NAME

mi_acquire - try to lock a queue private structure

SYNOPSIS

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

caddr_t mi_acquire(caddr_t ptr, queue_t *q);

ARGUMENTS

ptr

a pointer to the private structure that is to be acquired (locked).
q
a pointer to the active queue of the queue pair requesting the lock.

INTERFACE

MPS®-specific DDI.

Linux Fast-STREAMS specific.

DESCRIPTION

mi_acquire(), mi_acquire_sleep(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() attempts to lock the private structure associated with the pointer, ptr. When successful, the function returns a pointer to the private stucture. When unsuccessful, the queue q, is scheduled to be enabled with qenable(9) when the structure is unlocked by the current lock holder, and NULL is returned.

USAGE

mi_acquire() simplifies the implementation of private structure locks for fully MP-safe STREAMS(9) modules and drivers. The function attempts to lock the private structure associated with the private structure pointer, ptr, and serializes access to the associated private structure. While the lock is held, access to the private structure is exclusive to the lock holder.

mi_acquire() is called at the beginning of put or service procedure execution when the procedure wishes exclusive access to the private structure (perhaps to alter state variables).

When mi_acquire() fails, the caller should cause any message that was to be processed under the lock to be placed (back) onto message queue, q. When the lock is released by the current lock holder, the message queue, q, will be enabled.

RETURN

When mi_acquire() succeeds, it returns a pointer to the locked private structure ptr; when unsuccessful, it returns NULL and schedules queue, q, for later service processing.

ERRORS

mi_acquire() fails and returns NULL when there is no private structure associated with pointer, ptr; or, when it was not possible to immediately lock the structure. The difference can be determined by examining ptr for NULL.

CONTEXT

mi_acquire() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines.

MP-STREAMS

mi_acquire() is MP-safe, however, it is the responsibility of the caller to ensure the validity of passed in pointers across the call. See EXAMPLES .

NOTICES

mi_acquire() 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(9) should have a queue service procedure.

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

The lock acquired by mi_acquire() on the private structure associated with pointer, ptr, is not a recursive lock. That is, if mi_acquire() is called twice for the same pointer, ptr, and with no intervening mi_release(9), and the first call to mi_acquire() succeeds, the second call will fail. This is the best behaviour for STREAMS(9) put and service procedures which are seldomly written with reentrancy in mind.

IMPLEMENTATION

mi_acquire() is implemented using basic lock functions. See LOCK(9) and TRYLOCK(9) for more information.

EXAMPLES

The following is an example of the canonical use of mi_acquire():

static inline int
do_r_proto(queue_t *q, mblk_t *mp)
{
    struct priv *priv = PRIV(q);
read_lock(&mux_lock);
    if (!mi_acquire((caddr_t) priv->other, q)) {
        read_unlock(&mux_lock);
        return (EAGAIN);
    }
    read_unlock(&mux_lock);
/* ... */
    /* process the message */
    /* ... */
mi_release((caddr_t) priv->other);
    return (0);
}
static inline int
do_msg(queue_t *q, mblk_t *mp)
{
    switch (DB_TYPE(mp)) {
    case M_FLUSH:
        do_r_flush(q, mp);
    case M_PROTO:
        do_r_proto(q, mp);
    default:
        putnext(q, mp);
    }
}
static streamscall int
do_rput(queue_t *q, mblk_t *mp)
{
    if ((pcmsg(DB_TYPE(mp))
         && (q->q_first || (q->q_flag & QSVCBUSY)))
        || do_msg(q, mp))
        putq(q, mp);
    return (0);
}
static streamscall int
do_rsrv(queue_t *q)
{
    mblk_t *mp;
while ((mp = getq(q))) {
        if (do_msg(q, mp)) {
            putbq(q, mp);
            break;
        }
    }
    return (0);
}

SEE ALSO

mi_acquire_sleep(9), mi_release(9), TRYLOCK(9), mpscompat(9), aixcompat(9), maccompat(9), STREAMS(9).

BUGS

mi_acquire() has no known bugs.

COMPATIBILITY

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

---
mi_acquire() is an OpenSS7 Project specific implementation of an MPS®-compatible function and should not be used by portable STREAMS drivers and modules.
---
mi_acquire() is provided for use with SS7 drivers and modules that need some automatic locking of queue pair private structure for speed and efficiency.
---
mi_acquire() does 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() is new for The OpenSS7 Project. It is 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 Tue, 22 Aug 2017 20:31:35 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
EXAMPLES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 20:31:35 GMT, August 22, 2017
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manpage of MI_ACQUIRE
Last modified: Mon, 28 Apr 2008 16:47:03 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.