| <head> |
| <title>mux(3) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>MUX(3)</b><td align=right><b>MUX(3)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Mux, muxinit, muxrpc, muxthreads – protocol multiplexor<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <mux.h> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| struct Mux<br> |
| {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| uint mintag;<br> |
| uint maxtag;<br> |
| int (*settag)(Mux *mux, void *msg, uint tag);<br> |
| int (*gettag)(Mux *mux, void *msg);<br> |
| int (*send)(Mux *mux, void *msg);<br> |
| void *(*recv)(Mux *mux);<br> |
| void *aux;<br> |
| ... /* private fields follow */<br> |
| |
| </table> |
| };<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <tt><font size=+1>void muxinit(Mux *mux);<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void* muxrpc(Mux *mux, void *request);<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void muxprocs(Mux *mux);<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <i>Libmux</i> is a generic protocol multiplexor. A client program initializes |
| a <tt><font size=+1>Mux</font></tt> structure with information about the protocol (mainly in |
| the form of helper functions) and can then use <i>muxrpc</i> to execute |
| individual RPCs without worrying about details of multiplexing |
| requests and demultiplexing responses. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Libmux</i> assumes that the protocol messages contain a <i>tag</i> (or message |
| ID) field that exists for the sole purpose of demultiplexing messages. |
| <i>Libmux</i> chooses the tags and then calls a helper function to put |
| them in the outgoing messages. <i>Libmux</i> calls another helper function |
| to retrieve tags from incoming messages. |
| It also calls helper functions to send and receive packets. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| A client should allocate a <tt><font size=+1>Mux</font></tt> structure and then call <i>muxinit</i> |
| to initialize the library’s private elements. The client must |
| initialize the following elements:<br> |
| <i>mintag</i>, <i>maxtag<br> |
| </i> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| The range of valid tags; <i>maxtag</i> is the maximum valid tag plus |
| one, so that <i>maxtag</i>–<i>mintag</i> is equal to the number of valid tags. |
| If <i>libmux</i> runs out of tags (all tags are being used for RPCs currently |
| in progress), a new call to <i>muxrpc</i> will block until an executing |
| call finishes.<br> |
| |
| </table> |
| <i>settag</i>, <i>gettag<br> |
| </i> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Set or get the tag value in a message.<br> |
| |
| </table> |
| <i>send</i>, <i>recv<br> |
| </i> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Send or receive protocol messages on the connection. <i>Recv</i> should |
| block until a message is available and should return nil if the |
| connection is closed. <i>Libmux</i> will arrange that only one call to |
| <i>recv</i> is active at a time.<br> |
| |
| </table> |
| <i>aux</i> An auxiliary pointer for use by the client. Once a client has |
| initialized the <tt><font size=+1>Mux</font></tt> structure, it can call <i>muxrpc</i> to execute RPCs. |
| The <i>request</i> is the message passed to <i>settag</i> and <i>send</i>. The return |
| value is the response packet, as provided by <i>recv</i>, or nil if an |
| error occurred. <i>Muxprocs</i> allocates new procs (see |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man3/thread.html"><i>thread</i>(3)</a>) in which to run <i>send</i> and <i>recv</i>. After a call to <i>muxprocs</i>, |
| <i>muxrpc</i> will run <i>send</i> and <i>recv</i> in these procs instead of in the |
| calling proc. This is useful if the implementation of either (particularly |
| <i>recv</i>) blocks an entire proc and there are other threads in the |
| calling proc that need to remain active. |
| |
| </table> |
| |
| </table> |
| <p><font size=+1><b>EXAMPLE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| See <tt><font size=+1>/usr/local/plan9/src/lib9pclient/fs.c</font></tt> for an example of using |
| <i>libmux</i> with 9P (see <i>intro</i>(9p)).<br> |
| |
| </table> |
| <p><font size=+1><b>SOURCE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>/usr/local/plan9/src/libmux<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man3/thread.html"><i>thread</i>(3)</a>, <i>intro</i>(9p)<br> |
| |
| </table> |
| <p><font size=+1><b>BUGS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <i>Libmux</i> does not know how to free protocol messages, so message |
| arriving with unexpected or invalid tags are leaked. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| Using <i>mintag</i> other than zero is not well tested and probably buggy.<br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
