1 .TH MUX 3
2 .SH NAME
3 Mux, muxinit, muxrpc, muxthreads \- protocol multiplexor
4 .SH SYNOPSIS
5 .B #include <mux.h>
6 .PP
7 .nf
8 .B
9 .ta +4n
10 .ft B
11 struct Mux
12 {
13 	uint mintag;
14 	uint maxtag;
15 	int (*settag)(Mux *mux, void *msg, uint tag);
16 	int (*gettag)(Mux *mux, void *msg);
17 	int (*send)(Mux *mux, void *msg);
18 	void *(*recv)(Mux *mux);
19 	void *(*nbrecv)(Mux *mux);
20 	void *aux;
21 
22 	\&...   /* private fields follow */
23 };
24 .ta +\w'\fLvoid* 'u
25 .PP
26 .B
27 void	muxinit(Mux *mux);
28 .PP
29 .B
30 void*	muxrpc(Mux *mux, void *request);
31 .PP
32 .B
33 void	muxprocs(Mux *mux);
34 .PP
35 .B
36 Muxrpc*	muxrpcstart(Mux *mux, void *request);
37 .PP
38 .B
39 void*	muxrpccanfinish(Muxrpc *rpc);
40 .SH DESCRIPTION
41 .I Libmux
42 is a generic protocol multiplexor.
43 A client program initializes a 
44 .B Mux
45 structure with information about the protocol
46 (mainly in the form of helper functions)
47 and can then use
48 .I muxrpc
49 to execute individual RPCs without worrying
50 about details of multiplexing requests
51 and demultiplexing responses.
52 .PP
53 .I Libmux
54 assumes that the protocol messages contain a
55 .I tag
56 (or message ID) field that exists for the sole purpose of demultiplexing messages.
57 .I Libmux
58 chooses the tags and then calls a helper function
59 to put them in the outgoing messages.
60 .I Libmux
61 calls another helper function to retrieve tags
62 from incoming messages.
63 It also calls helper functions to send and receive packets.
64 .PP
65 A client should allocate a
66 .B Mux
67 structure and then call
68 .I muxinit
69 to initialize the library's private elements.
70 The client must initialize the following elements:
71 .TP
72 .I mintag\fR, \fPmaxtag
73 The range of valid tags;
74 .I maxtag
75 is the maximum valid tag plus one, so that
76 .IR maxtag \- mintag
77 is equal to the number of valid tags.
78 If
79 .I libmux
80 runs out of tags
81 (all tags are being used for RPCs currently in progress),
82 a new call to
83 .IR muxrpc
84 will block until an executing call finishes.
85 .TP
86 .I settag\fR, \fPgettag
87 Set or get the tag value in a message.
88 .TP
89 .I send\fR, \fPrecv\fR, \fPnbrecv
90 Send or receive protocol messages on the connection.
91 .I Recv
92 should block until a message is available and
93 should return nil if the connection is closed.
94 .I Nbrecv
95 should not block; it returns nil if there is no
96 message available to be read.
97 .I Libmux
98 will arrange that only one call to
99 .I recv
100 or
101 .I nbrecv
102 is active at a time.
103 .TP
104 .I aux
105 An auxiliary pointer for use by the client.
106 .PD
107 Once a client has initialized the
108 .B Mux
109 structure, it can call
110 .I muxrpc
111 to execute RPCs.
112 The
113 .I request
114 is the message passed to
115 .I settag
116 and
117 .IR send .
118 The return value is the response packet,
119 as provided by
120 .IR recv ,
121 or
122 nil if an error occurred.
123 .I Muxprocs
124 allocates new procs 
125 (see
126 .MR thread (3) )
127 in which to run
128 .I send
129 and
130 .IR recv .
131 After a call to
132 .IR muxprocs ,
133 .I muxrpc
134 will run
135 .I send
136 and
137 .I recv
138 in these procs instead of in the calling proc.
139 This is useful if the implementation of
140 either (particularly
141 .IR recv )
142 blocks an entire proc
143 and there are other threads in the calling proc
144 that need to remain active.
145 .PP
146 .I Libmux
147 also provides a non-blocking interface, useful for programs forced
148 to use a
149 .MR select (3) -based
150 main loop.
151 .I Muxrpcstart
152 runs the first half of
153 .IR muxrpc :
154 it assigns a tag and sends the request,
155 but does not wait for the reply.
156 Instead it returns a pointer to a
157 .B Muxrpc
158 structure that represents the in-progress call.
159 .I Muxrpccanfinish
160 checks whether the given call
161 can finish.
162 If no mux procs have been started,
163 .I muxrpccanfinish
164 may call
165 .I nbrecv
166 to poll for newly arrived responses.
167 .SH EXAMPLE
168 See
169 .B \*9/src/lib9pclient/fs.c
170 for an example of using 
171 .I libmux
172 with
173 9P
174 (see
175 .IR intro (9p)).
176 .SH SOURCE
177 .B \*9/src/libmux
178 .SH SEE ALSO
179 .MR thread (3) ,
180 .IR intro (9p)
181 .SH BUGS
182 .I Libmux
183 does not know how to free protocol messages,
184 so message arriving with unexpected or invalid
185 tags are leaked.