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