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