bufcall(D3)

NAME
     bufcall - call a function when a buffer becomes available

SYNOPSIS
     #include <sys/types.h>
     #include <sys/stream.h>
     #include <sys/ddi.h>
     toid_t bufcall(uint_t size, int pri, void (*func)(), long arg);

   Arguments
     size
        Number of bytes in the buffer to be allocated (from the failed
        allocb(D3) request).

     priPriority of the allocb allocation request.

     func
        Function or driver routine to be called when a buffer becomes
        available.

     argArgument to the function to be called when a buffer becomes available.

DESCRIPTION
     When a buffer allocation request fails, the function bufcall can be used
     to schedule the routine, func, to be called with the argument, arg, when
     a buffer of at least size bytes becomes available.  bufcall serves, in
     effect, as a timeout call of indeterminate length.

   Return Values
     On success, bufcall returns a non-zero value that identifies the
     scheduling request.  On failure, bufcall returns 0.

USAGE
     When func runs, all interrupts from STREAMS devices will be blocked.  On
     multiprocessor systems, when func runs all interrupts from STREAMS
     devices will be blocked on the processor on which func is running.  func
     will have no user context and may not call any function that sleeps.

     Even when func is called, allocb can still fail if another module or
     driver had allocated the memory before func was able to call allocb.

     The pri argument is no longer used but is retained for compatibility.

     The non-zero identifier returned by bufcall may be passed to
     unbufcall(D3) to cancel the request.

   Level
     Base or Interrupt.

   Synchronization Constraints
     Does not sleep.

     Driver-defined basic locks, read/write locks, and sleep locks may be held
     across calls to this function.

    Example
     The purpose of this service routine [see srv(D2)] is to add a header to
     all M_DATA messages.  We assume only M_DATA messages are added to its
     queue.  Service routines must process all messages on their queues before
     returning, or arrange to be rescheduled.

     While there are messages to be processed (line 19), we check to see if we
     can send the message on in the stream.  If not, we put the message back
     on the queue (line 21) and return.  The STREAMS flow control mechanism
     will re-enable us later when messages can be sent.  If canput(D3)
     succeeded, we try to allocate a buffer large enough to hold the header
     (line 24).  If no buffer is available, the service routine must be
     rescheduled later, when a buffer is available.  We put the original
     message back on the queue (line 26) and use bufcall to attempt the
     rescheduling (lines 27 and 28).  If bufcall succeeds, we set the m_type
     field in the module's private data structure to BUFCALL.  If bufcall
     failed, we use itimeout(D3) to reschedule us instead (line 30).  modcall
     will be called in about a half second [drv_usectohz(500000)].  When the
     rescheduling has been done, we return.

     When modcall runs, it will set the m_type field to zero, indicating that
     there is no outstanding request.  Then the queue's service routine is
     scheduled to run by calling qenable(D3).

     If the buffer allocation is successful, we initialize the header (lines
     37-39), make the message type M_PROTO (line 41), link the M_DATA message
     to it (line 42), and pass it on (line 43).

     See unbufcall(D3) for the other half of this example.

      1  struct hdr {
      2    uint_t    h_size;
      3    int    h_version;
      4  };
      5  struct mod {
      6    long    m_id;
      7    char    m_type;
         ...
      8  };
      9  #define TIMEOUT    1
     10  #define BUFCALL    2
         ...
     11  modsrv(q)    /* assume only M_DATA messages enqueued here */
     12        queue_t *q;
     13  {
     14    mblk_t *bp;
     15    mblk_t *mp;
     16    struct hdr *hp;
     17    struct mod *modp;
     18    modp = (struct mod *)q->q_ptr;
     19    while ((mp = getq(q)) != NULL) {
     20        if (!canput(q->q_next)) {
     21            putbq(q, mp);
     22            return;
     23        }
     24        bp = allocb(sizeof(struct hdr), BPRI_MED);
     25        if (bp == NULL) {
     26            putbq(q, mp);
     27            modp->m_id = bufcall(sizeof(struct hdr), BPRI_MED,
     28                                 modcall, (long)q);
     29            if (modp->m_id == 0) {
     30               modp->m_id = itimeout(modcall, (long)q,
     31                                     drv_usectohz(500000), plstr);
     32               modp->m_type = TIMEOUT;
     33            } else {
     34               modp->m_type = BUFCALL;
     35            }
     36            return;
     37        }
     38        hp = (struct hdr *)bp->b_wptr;
     39        hp->h_size = msgdsize(mp);
     40        hp->h_version = 1;
     41        bp->b_wptr += sizeof(struct hdr);
     42        bp->b_datap->db_type = M_PROTO;
     43        bp->b_cont = mp;
     44        putnext(q, bp);
     45    }
     46  }
     47  modcall(q)
     48   queue_t *q;
     49  {
     50   struct mod *modp;
     51   modp = (struct mod *)q->q_ptr;
     52   modp->m_type = 0;
     53   qenable(q);
     54  }

REFERENCES
     allocb(D3), esballoc(D3), esbbcall(D3), itimeout(D3), unbufcall(D3)