BUFCALL

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

NAME

bufcall - install a buffer callback

SYNOPSIS

#include <sys/stream.h>

bcid_t bufcall(unsigned size, int pri, void (*func)(long), long arg);

ARGUMENTS

size

The size of the requested data buffer.

pri

The priority of the requested message. The priority can be one of the following values:

BPRI_LO	requests a low priority buffer.
BPRI_MED	requests a medium priority buffer.
BPRI_HI	requests a high priority buffer.
BPRI_WAITOK	requests a low priority buffer and can block.

The pri argument is ignored by SVR 4.2[1] and later implementations.

func

The callback function to call when a buffer of the requested size and message of the requested priority becomes available. This is normally the qi_srvp(9) procedure which failed a call to allocb(9) or it is a function pointer to qenable(9).

arg

The argument to pass to the callback function. This is normally a pointer to the queue whose qi_srvp(9) procedure failed the allocb(9).

INTERFACE

STREAMS.

DESCRIPTION

When allocation of a buffer fails as a result of a failed call to allocb(9), the qi_srvp(9) procedure should place the message that invoked the allocb(9) call back on the queue with putbq(9) and call the bufcall() function with the queue's qi_srvp(9) procedure as the func argument and a pointer to the queue as the arg argument to the call. The size and pri arguments should be the same as the size and pri arguments that were issued to allocb(9).

In this way, the queue qi_srvp(9) procedure will be recalled once there is sufficient memory to allocate the requested buffer and message blocks.

RETURN

bufcall() returns a bcid_t defined as follows:


typedef int bcid_t;
typedef int bufcall_id_t;

Upon success, bufcall() returns a non-zero bufcall id and the specified func will be called with the specified arg at a later time when buffers of the necessary size become available.

Upon failure, bufcall() returns zero (0) and no call will be generated to the specified func.

ERRORS

When bufcall() encounters an error, it returns zero (0).

bufcall() returns zero (0) when the function pointer to the callback function, func is NULL, or bufcall() cannot allocate the necessary internal structures.

CONTEXT

bufcall() can be called from any context, including user context, qi_qopen(9), qi_qclose(9), qi_putp(9), qi_srvp(9) procedures, bufcall(9), qbufcall(9), timeout(9), qtimeout(9) callbacks, and interrupt service routines.

MP-STREAMS

bufcall() is MP-safe.

Considerations should be given when writing the callback function that a bufcall() callback function could execute at the same time as any qi_qopen(9), qi_qclose(9), qi_putp(9), or qi_srvp(9) procedure, bufcall(9), qbufcall(9), timeout(9), qtimeout(9) callback or interrupt service routine.

Nevertheless, the bufcall() callback function will be serviced by the same thread as the thread from which the bufcall() was issued. Therefore, the callback function will not execute until after bufcall() returns. Because the servicing thread and the current thread are the same, the bufcall() callback will not be invoked until after the function that called bufcall() returns. This means that it is safe to store the returned bufcall id in global variables accessed by the callback function. This is the same situation for qtimeout(9), qbufcall(9), timeout(9), bufcall(9) and esbbcall(9) functions.

However, if the bufcall() was generated from a qi_qopen(9), qi_qclose(9), qi_putp(9) or qi_srvp(9) procedure, or was generated from within a mi_bufcall(9), qbufcall(9), qtimeout(9), callback, or other queue referenced bufcall(), esbbcall(9), timeout(9), callback, then the STREAMS executive is aware of the queue to which the callback function is to be referenced and will generate a buffer call internally that is referenced against the queue within whose synchronization context the call was invoked. This makes the bufcall() function safer than the normal SVR 4.2 MP equivalent.

See mp-streams(9) for additional information.

NOTICES

bcid_t and bufcall_id_t should be treated as an opaque type that can be tested to equality to zero. The value should not otherwise be manipulated. bufcall() implements bufcall id values internally as a compressed out dating pointer to a strevent structure containing the bufcall callback function and argument. On 64-bit architectures this value should not be stored as an int, nor converted to any integer type with less bits than a pointer.

All outstanding buffer calls allocated with bufcall() must be cancelled with a call to unbufcall(9) before invalidating any of the references passed as an argument to the callback function. When the argument is a queue(9) pointer, all outstanding buffer calls must be cancelled with unbufcall(9) before the queue is deallocated (i.e. before returning from the qi_qclose(9)) procedure.

EXAMPLES

It is typical to see bufcall() used to merely enable a queue from a qi_srvp(9) procedure as follows:


int xxx_srvp(queue_t *q)
{
   mblk_t *mp, *dp;
   while ((mp = get(q))) {
      switch (mp->b_datap->db_type) {
      case M_PROTO:
         if ((dp = allocb(somesize, BPRI_MED)) == NULL) {
            putbq(mp);
            bufcall(somesize, BPRI_MED, (void *) qenable,
                    (long) q);
            return (0);
         }
      ...
      }
   }
   return (0);
}

BUGS

bufcall() has no known bugs.

COMPATIBILITY

bufcall() is compatible with SVR 4.2 MP DDI/DKI[2], and systems based on SVR 4[3] with the folllowing portability considerations:

---: bufcall() allocates a strevent structure which is then linked into the strbcalls system variable and set the strbcwait flag which causes kmem_free(9) to set the qrunflag. The bufcall list is thus scheduled to run on the next invocation of runqueues(9). This procedure is consistent with that described for SVR 4[4].
: Under LiS, bufcall() does not actually generate a callback function once a buffer of the appropriate size becomes available. Instead LiS starts a timer. When the timer expires, the ability to allocate the necessary buffers is checked and the callback function invoked if it is now possible to allocate the necessary structures and buffers. This is not entirely consistent with SVR 4.2[1] operation.
---: bufcall() assign a packed out dating pointer into the integer bcid_t returned. This pointer is a sequenced pointer to a strevent object that expires when the event's sequence number is incremented. This permits unpacking and dereferencing of the pointer instead of searches for id numbers in strevent lists for speed.
: LiS builds a linked list of buffer call structures and assigns an integer id to each structure. Searches for unique buffer ids when ids are assigned and searches for buffer ids when unbufcall(9) is called are linear searches that are slow and inefficient. In fact, ``The Magic Garden'' explains that in SVR 4.2[1] a bufcall() results in the creation of a strevent structure which is linked to the strbcalls system variable and sets the strbcwait flag which is then causes kmem_free() to set the qrunflag. At no point in this process is an integer id assigned to the strevent structure. This means that LiS meaninglessly assigns an integer id to the buffer call structure and the inefficiencies of linear searches are pointless.
---: Depending on the system, bufcall() returns int, bcid_t, bufcall_id_t or even toid_t. Linux Fast-STREAMS assigns a type of int to bcid_t, bufcall_id_t and toid_t to avoid compatibility issues.
---: IRIX® documents[5] bufcall() as returning a toid_t. Linux Fast-STREAMS also defines a toid_t as int. See timeout(9).
---: IRIXRg documents[5] that the callback function will be called with local STREAMS driver interrupts disabled.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[2].

HISTORY

bufcall() appears as part of SVR 4.0 STREAMS[3].

bufcall() first appeared in SVR 3[6].

REFERENCES

[1]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[4]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9]
[5]: IRIX® 6.5.17, IRIX 6.5 Manual Pages, 2003, (Mountainview, California), Silicon Graphics, Inc., SGI Technical Publications. <http://techpubs.sgi.com/>
[6]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

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

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

Index

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

This document was created by man2html, using the manual pages.
Time: 08:50:20 GMT, June 19, 2013

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