From 058b0118a52061ad57694c01fc8763b22b789c4d Mon Sep 17 00:00:00 2001
From: rsc <devnull@localhost>
Date: Mon, 3 Jan 2005 06:40:20 +0000
Subject: Some man pages.

---
 man/man3/mux.3 | 154 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 154 insertions(+)
 create mode 100644 man/man3/mux.3

(limited to 'man/man3/mux.3')

diff --git a/man/man3/mux.3 b/man/man3/mux.3
new file mode 100644
index 00000000..cc8de4d2
--- /dev/null
+++ b/man/man3/mux.3
@@ -0,0 +1,154 @@
+.TH MUX 3
+.SH NAME
+Mux, muxinit, muxrpc, muxthreads \- protocol multiplexor
+.SH SYNOPSIS
+.B #include <mux.h>
+.PP
+.nf
+.B
+.ta +4n
+struct Mux
+{
+	uint mintag;
+	uint maxtag;
+	int (*settag)(Mux *mux, void *msg, uint tag);
+	int (*gettag)(Mux *mux, void *msg);
+	int (*send)(Mux *mux, void *msg);
+	void *(*recv)(Mux *mux);
+	void *aux;
+
+	\&...   /* private fields follow */
+};
+.ta +\w'\fLvoid* 'u
+.PP
+.B
+void	muxinit(Mux *mux);
+.PP
+.B
+void*	muxrpc(Mux *mux, void *request);
+.PP
+.B
+void	muxprocs(Mux *mux);
+.SH DESCRIPTION
+.I Libmux
+is a generic protocol multiplexor.
+A client program initializes a 
+.B Mux
+structure with information about the protocol
+(mainly in the form of helper functions)
+and can then use
+.I muxrpc
+to execute individual RPCs without worrying
+about details of multiplexing requests
+and demultiplexing responses.
+.PP
+.I Libmux
+assumes that the protocol messages contain a
+.I tag
+(or message ID) field that exists for the sole purpose of demultiplexing messages.
+.I Libmux
+chooses the tags and then calls a helper function
+to put them in the outgoing messages.
+.I Libmux
+calls another helper function to retrieve tags
+from incoming messages.
+It also calls helper functions to send and receive packets.
+.PP
+A client should allocate a
+.B Mux
+structure and then call
+.I muxinit
+to initialize the library's private elements.
+The client must initialize the following elements:
+.TP
+.I mintag\fR, \fPmaxtag
+The range of valid tags;
+.I maxtag
+is the maximum valid tag plus one, so that
+.IR maxtag \- mintag
+is equal to the number of valid tags.
+If
+.I libmux
+runs out of tags
+(all tags are being used for RPCs currently in progress),
+a new call to
+.IR muxrpc
+will block until an executing call finishes.
+.TP
+.I settag\fR, \fPgettag
+Set or get the tag value in a message.
+.TP
+.I send\fR, \fPrecv
+Send or receive protocol messages on the connection.
+.I Recv
+should block until a message is available and
+should return nil if the connection is closed.
+.I Libmux
+will arrange that only one call to
+.I recv
+is active at a time.
+.TP
+.I aux
+An auxiliary pointer for use by the client.
+.PD
+Once a client has initialized the
+.B Mux
+structure, it can call
+.I muxrpc
+to execute RPCs.
+The
+.I request
+is the message passed to
+.I settag
+and
+.IR send .
+The return value is the response packet,
+as provided by
+.IR recv ,
+or
+nil if an error occurred.
+.I Muxprocs
+allocates new procs 
+(see
+.IR thread (3))
+in which to run
+.I send
+and
+.IR recv .
+After a call to
+.IR muxprocs ,
+.I muxrpc
+will run
+.I send
+and
+.I recv
+in these procs instead of in the calling proc.
+This is useful if the implementation of
+either (particularly
+.IR recv )
+blocks an entire proc
+and there are other threads in the calling proc
+that need to remain active.
+.SH EXAMPLE
+See
+.B /usr/local/plan9/src/lib9pclient/fs.c
+for an example of using 
+.I libmux
+with
+9P
+(see
+.IR intro (9p)).
+.SH SOURCE
+.B /usr/local/plan9/src/libmux
+.SH SEE ALSO
+.IR thread (3),
+.IR intro (9p)
+.SH BUGS
+.I Libmux
+does not know how to free protocol messages,
+so message arriving with unexpected or invalid
+tags are leaked.
+.PP
+Using
+.I mintag
+other than zero is not well tested and probably buggy.
-- 
cgit v1.2.3