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