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