mt-streams(9f)

1mt-streams(9F)           Kernel Functions for Drivers           mt-streams(9F)
2
3
4

NAME

6       mt-streams - STREAMS multithreading
7

SYNOPSIS

9       #include <sys/conf.h>
10
11

INTERFACE LEVEL

13       Solaris DDI specific (Solaris DDI).
14

DESCRIPTION

16       STREAMS  drivers  configure the degree of concurrency using the cb_flag
17       field in the cb_ops structure (see cb_ops(9S)). The corresponding field
18       for STREAMS modules is the f_flag in the fmodsw structure.
19
20
21       For the purpose of restricting and controlling the concurrency in driv‐
22       ers/modules, we define the concepts of inner and  outer  perimeters.  A
23       driver/module  can  be configured either to have no perimeters, to have
24       only an inner or an outer perimeter, or to have both an  inner  and  an
25       outer  perimeter.  Each  perimeter acts as a readers-writers lock, that
26       is, there can be multiple concurrent readers or a single writer.  Thus,
27       each  perimeter  can be entered in two modes: shared (reader) or exclu‐
28       sive (writer). The mode depends on the perimeter configuration and  can
29       be  different  for  the  different  STREAMS  entry  points  ( open(9E),
30       close(9E), put(9E), or srv(9E)).
31
32
33       The concurrency for the different entry  points  is  (unless  specified
34       otherwise)  to  enter  with exclusive access at the inner perimeter (if
35       present) and shared access at the outer perimeter (if present).
36
37
38       The perimeter configuration consists of flags that define the  presence
39       and  scope  of the inner perimeter, the presence of the outer perimeter
40       (which can only have one scope), and flags that modify the default con‐
41       currency for the different entry points.
42
43
44       All MT safe modules/drivers specify the D_MP flag.
45
46   Inner Perimeter Flags
47       The  inner  perimeter presence and scope are controlled by the mutually
48       exclusive flags:
49
50       D_MTPERQ             The module/driver has an  inner  perimeter  around
51                            each queue.
52
53
54       D_MTQPAIR            The  module/driver  has  an inner perimeter around
55                            each read/write pair of queues.
56
57
58       D_MTPERMOD           The module/driver  has  an  inner  perimeter  that
59                            encloses all the module's/driver's queues.
60
61
62       None of the above    The module/driver has no inner perimeter.
63
64
65   Outer Perimeter Flags
66       The outer perimeter presence is configured using:
67
68       D_MTOUTPERIM    In  addition  to any inner perimeter, the module/driver
69                       has an outer  perimeter  that  encloses  all  the  mod‐
70                       ule's/driver's  queues.  This  can be combined with all
71                       the inner perimeter options except D_MTPERMOD.
72
73
74
75       Note that acquiring exclusive access at the outer perimeter  (that  is,
76       using qwriter(9F) with the PERIM_OUTER flag) can incur significant per‐
77       formance penalties,  which  grow  linearly  with  the  number  of  open
78       instances of the module or driver in the system.
79
80
81       The default concurrency can be modified using:
82
83       D_MTPUTSHARED    This  flag  modifies the default behavior when put(9E)
84                        procedure are invoked so that the inner  perimeter  is
85                        entered shared instead of exclusively.
86
87
88       D_MTOCEXCL       This  flag modifies the default behavior when open(9E)
89                        and close(9E) procedures  are  invoked  so  the  outer
90                        perimeter is entered exclusively instead of shared.
91
92                        Note  that  drivers  and  modules  using this flag can
93                        cause significant system performance degradation  dur‐
94                        ing  stream  open  or close when many instances of the
95                        driver or module are in use simultaneously.  For  this
96                        reason,  use  of  this  flag  is discouraged. Instead,
97                        since open(9E) and close(9E) both  execute  with  user
98                        context,  developers are encouraged to use traditional
99                        synchronization routines such  as  cv_wait_sig(9F)  to
100                        coordinate  with other open instances of the module or
101                        driver.
102
103
104
105       The module/driver can use qwait(9F) or qwait_sig() in the open(9E)  and
106       close(9E) procedures if it needs to wait "outside" the perimeters.
107
108
109       The  module/driver  can  use  qwriter(9F)  to upgrade the access at the
110       inner or outer perimeter from shared to exclusive.
111
112
113       The use and semantics of qprocson() and qprocsoff(9F) is independent of
114       the inner and outer perimeters.
115

NAME

SYNOPSIS

INTERFACE LEVEL

DESCRIPTION

SEE ALSO