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 struct Mux
11 {
12 	uint mintag;
13 	uint maxtag;
14 	int (*settag)(Mux *mux, void *msg, uint tag);
15 	int (*gettag)(Mux *mux, void *msg);
16 	int (*send)(Mux *mux, void *msg);
17 	void *(*recv)(Mux *mux);
18 	void *aux;
19 
20 	\&...   /* private fields follow */
21 };
22 .ta +\w'\fLvoid* 'u
23 .PP
24 .B
25 void	muxinit(Mux *mux);
26 .PP
27 .B
28 void*	muxrpc(Mux *mux, void *request);
29 .PP
30 .B
31 void	muxprocs(Mux *mux);
32 .SH DESCRIPTION
33 .I Libmux
34 is a generic protocol multiplexor.
35 A client program initializes a 
36 .B Mux
37 structure with information about the protocol
38 (mainly in the form of helper functions)
39 and can then use
40 .I muxrpc
41 to execute individual RPCs without worrying
42 about details of multiplexing requests
43 and demultiplexing responses.
44 .PP
45 .I Libmux
46 assumes that the protocol messages contain a
47 .I tag
48 (or message ID) field that exists for the sole purpose of demultiplexing messages.
49 .I Libmux
50 chooses the tags and then calls a helper function
51 to put them in the outgoing messages.
52 .I Libmux
53 calls another helper function to retrieve tags
54 from incoming messages.
55 It also calls helper functions to send and receive packets.
56 .PP
57 A client should allocate a
58 .B Mux
59 structure and then call
60 .I muxinit
61 to initialize the library's private elements.
62 The client must initialize the following elements:
63 .TP
64 .I mintag\fR, \fPmaxtag
65 The range of valid tags;
66 .I maxtag
67 is the maximum valid tag plus one, so that
68 .IR maxtag \- mintag
69 is equal to the number of valid tags.
70 If
71 .I libmux
72 runs out of tags
73 (all tags are being used for RPCs currently in progress),
74 a new call to
75 .IR muxrpc
76 will block until an executing call finishes.
77 .TP
78 .I settag\fR, \fPgettag
79 Set or get the tag value in a message.
80 .TP
81 .I send\fR, \fPrecv
82 Send or receive protocol messages on the connection.
83 .I Recv
84 should block until a message is available and
85 should return nil if the connection is closed.
86 .I Libmux
87 will arrange that only one call to
88 .I recv
89 is active at a time.
90 .TP
91 .I aux
92 An auxiliary pointer for use by the client.
93 .PD
94 Once a client has initialized the
95 .B Mux
96 structure, it can call
97 .I muxrpc
98 to execute RPCs.
99 The
100 .I request
101 is the message passed to
102 .I settag
103 and
104 .IR send .
105 The return value is the response packet,
106 as provided by
107 .IR recv ,
108 or
109 nil if an error occurred.
110 .I Muxprocs
111 allocates new procs 
112 (see
113 .IR thread (3))
114 in which to run
115 .I send
116 and
117 .IR recv .
118 After a call to
119 .IR muxprocs ,
120 .I muxrpc
121 will run
122 .I send
123 and
124 .I recv
125 in these procs instead of in the calling proc.
126 This is useful if the implementation of
127 either (particularly
128 .IR recv )
129 blocks an entire proc
130 and there are other threads in the calling proc
131 that need to remain active.
132 .SH EXAMPLE
133 See
134 .B \*9/src/lib9pclient/fs.c
135 for an example of using 
136 .I libmux
137 with
138 9P
139 (see
140 .IR intro (9p)).
141 .SH SOURCE
142 .B \*9/src/libmux
143 .SH SEE ALSO
144 .IR thread (3),
145 .IR intro (9p)
146 .SH BUGS
147 .I Libmux
148 does not know how to free protocol messages,
149 so message arriving with unexpected or invalid
150 tags are leaked.
151 .PP
152 Using
153 .I mintag
154 other than zero is not well tested and probably buggy.