Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MUX(3)			   Library Functions Manual			MUX(3)

       Mux, muxinit, muxrpc, muxthreads	- protocol multiplexor

       #include	<mux.h>

       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	*(*nbrecv)(Mux *mux);
	   void	*aux;

	   ...	 /* private fields follow */

       void  muxinit(Mux *mux);

       void* muxrpc(Mux	*mux, void *request);

       void  muxprocs(Mux *mux);

       Muxrpc*muxrpcstart(Mux *mux, void *request);

       void* muxrpccanfinish(Muxrpc *rpc);

       Libmux is a generic protocol multiplexor.  A client program initializes
       a Mux structure with information	about the protocol (mainly in the form
       of helper functions) and	can then use muxrpc to execute individual RPCs
       without worrying	about details of multiplexing  requests	 and  demulti-
       plexing responses.

       Libmux assumes that the protocol	messages contain a tag (or message ID)
       field that exists for the  sole	purpose	 of  demultiplexing  messages.
       Libmux chooses the tags and then	calls a	helper function	to put them in
       the outgoing messages.  Libmux calls another  helper  function  to  re-
       trieve  tags from incoming messages.  It	also calls helper functions to
       send and	receive	packets.

       A client	should allocate	a Mux structure	and then call muxinit to  ini-
       tialize the library's private elements.	The client must	initialize the
       following elements:

       mintag, maxtag
	      The range	of valid tags; maxtag is the maximum  valid  tag  plus
	      one, so that maxtag-mintag is equal to the number	of valid tags.
	      If libmux	runs out of tags (all tags are	being  used  for  RPCs
	      currently	in progress), a	new call to muxrpc will	block until an
	      executing	call finishes.

       settag, gettag
	      Set or get the tag value in a message.

       send, recv, nbrecv
	      Send or receive  protocol	 messages  on  the  connection.	  Recv
	      should  block until a message is available and should return nil
	      if the connection	is closed.  Nbrecv should not  block;  it  re-
	      turns  nil  if there is no message available to be read.	Libmux
	      will arrange that	only one call to recv or nbrecv	is active at a

       aux    An  auxiliary  pointer for use by	the client.  Once a client has
	      initialized the Mux structure, it	can  call  muxrpc  to  execute
	      RPCs.   The  request  is	the message passed to settag and send.
	      The return value is the response packet, as provided by recv, or
	      nil  if an error occurred.  Muxprocs allocates new procs (see in
	      which to run send	and recv.  After a call	 to  muxprocs,	muxrpc
	      will  run	send and recv in these procs instead of	in the calling
	      proc.  This is useful if the implementation of either  (particu-
	      larly recv) blocks an entire proc	and there are other threads in
	      the calling proc that need to remain active.

       Libmux also provides a  non-blocking  interface,	 useful	 for  programs
       forced  to use a	main loop.  Muxrpcstart	runs the first half of muxrpc:
       it assigns a tag	and sends the request, but does	not wait for  the  re-
       ply.   Instead  it  returns a pointer to	a Muxrpc structure that	repre-
       sents the in-progress call.  Muxrpccanfinish checks whether  the	 given
       call  can  finish.   If no mux procs have been started, muxrpccanfinish
       may call	nbrecv to poll for newly arrived responses.

       See /src/lib9pclient/fs.c for an	example	of using libmux	with  9P  (see



       Libmux does not know how	to free	protocol messages, so message arriving
       with unexpected or invalid tags are leaked.



Want to link to this manual page? Use this URL:

home | help