1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
<head>
<title>mux(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>MUX(3)</b><td align=right><b>MUX(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
Mux, muxinit, muxrpc, muxthreads – protocol multiplexor<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include <mux.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
struct Mux<br>
{<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
uint mintag;<br>
uint maxtag;<br>
int (*settag)(Mux *mux, void *msg, uint tag);<br>
int (*gettag)(Mux *mux, void *msg);<br>
int (*send)(Mux *mux, void *msg);<br>
void *(*recv)(Mux *mux);<br>
void *aux;<br>
... /* private fields follow */<br>
</table>
};<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<tt><font size=+1>void muxinit(Mux *mux);<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void* muxrpc(Mux *mux, void *request);<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void muxprocs(Mux *mux);<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Libmux</i> is a generic protocol multiplexor. A client program initializes
a <tt><font size=+1>Mux</font></tt> structure with information about the protocol (mainly in
the form of helper functions) and can then use <i>muxrpc</i> to execute
individual RPCs without worrying about details of multiplexing
requests and demultiplexing responses.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Libmux</i> assumes that the protocol messages contain a <i>tag</i> (or message
ID) field that exists for the sole purpose of demultiplexing messages.
<i>Libmux</i> chooses the tags and then calls a helper function to put
them in the outgoing messages. <i>Libmux</i> calls another helper function
to retrieve tags from incoming messages.
It also calls helper functions to send and receive packets.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A client should allocate a <tt><font size=+1>Mux</font></tt> structure and then call <i>muxinit</i>
to initialize the library’s private elements. The client must
initialize the following elements:<br>
<i>mintag</i>, <i>maxtag<br>
</i>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
The range of valid tags; <i>maxtag</i> is the maximum valid tag plus
one, so that <i>maxtag</i>–<i>mintag</i> is equal to the number of valid tags.
If <i>libmux</i> runs out of tags (all tags are being used for RPCs currently
in progress), a new call to <i>muxrpc</i> will block until an executing
call finishes.<br>
</table>
<i>settag</i>, <i>gettag<br>
</i>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
Set or get the tag value in a message.<br>
</table>
<i>send</i>, <i>recv<br>
</i>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
Send or receive protocol messages on the connection. <i>Recv</i> should
block until a message is available and should return nil if the
connection is closed. <i>Libmux</i> will arrange that only one call to
<i>recv</i> is active at a time.<br>
</table>
<i>aux</i> An auxiliary pointer for use by the client. Once a client has
initialized the <tt><font size=+1>Mux</font></tt> structure, it can call <i>muxrpc</i> to execute RPCs.
The <i>request</i> is the message passed to <i>settag</i> and <i>send</i>. The return
value is the response packet, as provided by <i>recv</i>, or nil if an
error occurred. <i>Muxprocs</i> allocates new procs (see
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/thread.html"><i>thread</i>(3)</a>) in which to run <i>send</i> and <i>recv</i>. After a call to <i>muxprocs</i>,
<i>muxrpc</i> will run <i>send</i> and <i>recv</i> in these procs instead of in the
calling proc. This is useful if the implementation of either (particularly
<i>recv</i>) blocks an entire proc and there are other threads in the
calling proc that need to remain active.
</table>
</table>
<p><font size=+1><b>EXAMPLE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
See <tt><font size=+1>/usr/local/plan9/src/lib9pclient/fs.c</font></tt> for an example of using
<i>libmux</i> with 9P (see <i>intro</i>(9p)).<br>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/libmux<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/thread.html"><i>thread</i>(3)</a>, <i>intro</i>(9p)<br>
</table>
<p><font size=+1><b>BUGS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<i>Libmux</i> does not know how to free protocol messages, so message
arriving with unexpected or invalid tags are leaked.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
Using <i>mintag</i> other than zero is not well tested and probably buggy.<br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>
|