Added documentation

Added a default version of SetMasks: it can be called from the destructor

1 files changed, 79 insertions, 22 deletions

diff --git a/comm/Multiplexer.cc b/comm/Multiplexer.cc
index 9f29f40..d3e39cb 100644
--- a/comm/Multiplexer.cc
+++ b/comm/Multiplexer.cc
@@ -49,25 +49,30 @@ extern int	errno;
 #endif
 
 
-/*?class UchMultiplexer
-An object of class \typ{UchMultiplexer} is a set of channels.
+/*?class UchBaseMultiplexer
+Multiplexers make it possible to handle several communication channels at the
+same time; their implementation is based on the Unix \com{select} system call
+or similar mechanisms. Multiplexers are also able to implement safe (ie. not
+interruption-based) timers and signal handlers.
 Some of the channels in the set are active, others can be inactive.
-A channel set can be scanned so that the functions \fun{HandleRead}
-and \fun{HandleWrite} are called for each active channel that is ready to read or write.
+A multiplexer can be scanned so that the functions \fun{HandleRead}
+and \fun{HandleWrite} are called for every active channel that is ready to read or write.
 The functions \fun{HandleSelect} of each channel is called before actually scanning
 so that each channel can perform a background task or buffer input/output.
-This provides a level of abstraction over the Unix \fun{select} system call.
+
+Multiplexers may have different implementations, depending on the environment.
+When no other library is involved, they are simply implemented on top of Unix.
+But if \uch\ channels have to be mixed with the X Toolkit for instance, the
+implementation uses the mechanisms provided by the X Toolkit to add new channels.
+The same holds for Tcl/Tk or other environments. Every such implentation corresponds
+to a derived class of \typ{UchBaseMultiplexer}, which offers a uniform interface
+that hides the implementation differences. See the class \typ{UchMultiplexer} for
+a ``pure \uch'' implementation of multiplexers.
+
 Note that the functions that take an integer file descriptor as argument can be passed
 a \typ{FILDES} or a \typ{UchChannel} because the corresponding conversion operators are defined.
-
-The class \typ{^{pCHAN_SET}} implements smart pointers to channel sets.
-Smart pointers behave like pointers but they manage a reference count on the
-pointed to objects for an automatic reclaim of dynamically allocated objects.
 ?*/
 
-//	constructor: initialize states
-//
-
 /*?
 Create an empty channel set.
 ?*/
@@ -122,7 +127,7 @@ UchBaseMultiplexer :: Add (UchChannel* chan)
 pUchChannel NIL_CHAN (0);
 
 /*?
-Remove a channel from the set.
+Remove a channel from the set. This function can be passed a \var{UchChannel}.
 ?*/
 void
 UchBaseMultiplexer :: Remove (int fd)
@@ -152,6 +157,7 @@ UchBaseMultiplexer :: RemoveAll ()
 /*?
 Change the mode of a channel in the set.
 Mode \var{IONone} makes the channel inactive (without removing it).
+This function can be passed a \var{UchChannel}.
 ?*/
 void
 UchBaseMultiplexer :: SetMode (int fd, IOMODE mode)
@@ -203,12 +209,27 @@ UchBaseMultiplexer :: HandleSignal (UchBaseSignalHandler& h)
 
 }
 
-
+/*!
+This virtual function is called the first time when a signal is received by a
+signal handler associated to the multiplexer. It makes it possible
+to call implementation-dependant functions that defer the handling to
+safer times.
+!*/
+/*
+Does not need to be defined in UchMultiplexer, because
+they use the flag SigFired.
+*/
+/*?hidden?*/
 void
 UchBaseMultiplexer :: AddSignalHook ()
 {
 }
 
+/*!
+This function triggers the handling of all deferred signals. It should be
+called when \fun{AddSignalHook} has been called and the times are safe.
+!*/
+/*?hidden?*/
 void
 UchBaseMultiplexer :: HandleDeferredSignals ()
 {
@@ -222,6 +243,12 @@ UchBaseMultiplexer :: HandleDeferredSignals ()
 		}
 }
 
+/*?hidden?*/
+void
+UchBaseMultiplexer :: SetMasks (int, IOMODE)
+{
+}
+
 static jmp_buf reset_run;
 
 class UchMpxAborter : public UchBaseSignalHandler {
@@ -230,6 +257,19 @@ public:
 	void	DeferredHandle (int)	{ MyMpx.Abort (); }
 };
 
+/*?
+Run a multiplexer: make it repeatedly scan its channels, and take the
+appropriate actions. This function will exit under a number of
+circumstances, reflected by its return value.
+\small
+\begin{tabular}{ll}
+\var{isMpxTerminated}&the method \fun{Close} has been called.\\
+\var{isMpxEmpty}&there are no more channels in the set.\\
+\var{isMpxAborted}&the method \fun{Abort} has been called,
+or signals SIGINT or SIGTERM were received.\\
+\var{isMpxError}&an error has occured.
+\end{tabular}
+?*/
 MPX_RES
 UchBaseMultiplexer :: Run ()
 {
@@ -242,20 +282,35 @@ UchBaseMultiplexer :: Run ()
 	return Loop ();
 }
 
+/*?
+Remove all channels from the multiplexer, thus stopping it if running.
+?*/
 void
-UchBaseMultiplexer :: Abort ()
+UchBaseMultiplexer :: Close ()
 {
-	if (Looping)
-		longjmp (reset_run, 1);
+	RemoveAll ();
+	Looping = FALSE;
 }
 
+/*?
+Stop the multiplexer, without cleaning it.
+?*/
 void
-UchBaseMultiplexer :: Close ()
+UchBaseMultiplexer :: Abort ()
 {
-	RemoveAll ();
-	Looping = FALSE;
+	if (Looping)
+		longjmp (reset_run, 1);
 }
 
+/*?class UchMultiplexer
+The class \typ{UchMultiplexer} is the default implementation of multiplexers,
+used when there are no compatibility needs. For historical reasons, it offers
+a number of additional methods.
+?*/
+
+/*?
+Build an empty multiplexer.
+?*/
 UchMultiplexer :: UchMultiplexer ()
 : UchBaseMultiplexer (),
   TimeOut (-1)
@@ -265,6 +320,7 @@ UchMultiplexer :: UchMultiplexer ()
 	FD_ZERO (&SelectMask);
 }
 
+/*?nodoc?*/
 UchMultiplexer :: ~UchMultiplexer ()
 {
 }
@@ -507,8 +563,6 @@ UchMultiplexer :: LoopScan (bool nointr)
 	return isMpxTerminated;
 }
 
-//	string repr
-//
 /*?nodoc?*/
 char*
 UchMultiplexer :: StrRepr (char* buf)
@@ -529,6 +583,7 @@ UchMultiplexer :: LoopEnd ()
 
 #endif /* DOC */
 
+/*?hidden?*/
 void
 UchMultiplexer :: SetTimeOut (Millisecond delay)
 {
@@ -536,12 +591,14 @@ UchMultiplexer :: SetTimeOut (Millisecond delay)
 	TimeOut = now + delay;
 }
 
+/*?hidden?*/
 void
 UchMultiplexer :: SuppressTimeOut ()
 {
 	TimeOut = -1;
 }
 
+/*?hidden?*/
 MPX_RES
 UchMultiplexer :: Loop ()
 {