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