qwait(9f) - osol9

1qwait(9F)                Kernel Functions for Drivers                qwait(9F)
2
3
4

NAME

6       qwait, qwait_sig - STREAMS wait routines
7

SYNOPSIS

9       #include <sys/stream.h>
10       #include <sys/ddi.h>
11
12
13
14       void qwait(queue_t *q);
15
16
17       int qwait_sig(queue_t *q);
18
19

INTERFACE LEVEL

21       Solaris DDI specific (Solaris DDI).
22

PARAMETERS

24       qp    Pointer to the queue that is being opened or closed.
25
26

DESCRIPTION

28       qwait() and qwait_sig() are used to wait for a message to arrive to the
29       put(9E) or srv(9E) procedures. qwait() and qwait_sig() can also be used
30       to  wait  for  qbufcall(9F) or qtimeout(9F) callback procedures to exe‐
31       cute. These routines can be used in the open(9E) and  close(9E)  proce‐
32       dures in a STREAMS driver or module.
33
34
35       The  thread that calls close() does not necessarily have the ability to
36       receive signals, particularly when called by  exit(2).  In  this  case,
37       qwait_sig()   behaves  exactly  as  qwait().  Driver  writers  may  use
38       ddi_can_receive_sig(9F) to determine when this is the case, and, if so,
39       arrange  some  means  to  avoid  blocking indefinitely (for example, by
40       using qtimeout(9F).
41
42
43       qwait() and qwait_sig() atomically exit the inner and outer  perimeters
44       associated  with the queue, and wait for a thread to leave the module's
45       put(9E), srv(9E), or qbufcall(9F) / qtimeout(9F)  callback  procedures.
46       Upon return they re-enter the inner and outer perimeters.
47
48
49       This  can  be  viewed  as  there being an implicit wakeup when a thread
50       leaves a put(9E) or srv(9E) procedure or after a qtimeout(9F) or  qbuf‐
51       call(9F) callback procedure has been run in the same perimeter.
52
53
54       qprocson(9F) must be called before calling qwait() or qwait_sig().
55
56
57       qwait()  is  not interrupted by a signal, whereas qwait_sig() is inter‐
58       rupted by a signal. qwait_sig() normally returns non-zero, and  returns
59       zero when the waiting was interrupted by a signal.
60
61
62       qwait()  and  qwait_sig()  are  similar  to cv_wait() and cv_wait_sig()
63       except that the mutex is replaced by the inner and outer perimeters and
64       the  signalling  is  implicit when a thread leaves the inner perimeter.
65       See condvar(9F).
66

RETURN VALUES

68       0    For qwait_sig(), indicates that the condition was not  necessarily
69            signaled, and the function returned because a signal was pending.
70
71

CONTEXT

73       These  functions  can only be called from an open(9E) or close(9E) rou‐
74       tine.
75

EXAMPLES

77       Example 1 Using qwait()
78
79
80       The open routine sends down a T_INFO_REQ  message  and  waits  for  the
81       T_INFO_ACK.  The  arrival  of the T_INFO_ACK is recorded by resetting a
82       flag in the unit structure (WAIT_INFO_ACK). The  example  assumes  that
83       the module is D_MTQPAIR or D_MTPERMOD.
84
85
86         xxopen(qp, ...)
87                queue_t *qp;
88         {
89                    struct xxdata *xx;
90                     /* Allocate xxdata structure */
91                qprocson(qp);
92                /* Format T_INFO_ACK in mp */
93                putnext(qp, mp);
94                xx->xx_flags |= WAIT_INFO_ACK;
95                while (xx->xx_flags & WAIT_INFO_ACK)
96                               qwait(qp);
97                    return (0);
98         }
99         xxrput(qp, mp)
100                queue_t *qp;
101                mblk_t *mp;
102         {
103                struct xxdata *xx = (struct xxdata *)q->q_ptr;
104
105                    ...
106
107                    case T_INFO_ACK:
108                               if (xx->xx_flags & WAIT_INFO_ACK) {
109                                      /* Record information from info ack */
110                                      xx->xx_flags &= ~WAIT_INFO_ACK;
111                                      freemsg(mp);
112                                      return;
113                               }
114
115                    ...
116         }
117
118