From 23354451255fa756eaa317f49813a1f666ae42ee Mon Sep 17 00:00:00 2001 From: chatty Date: Mon, 29 Nov 1993 10:38:20 +0000 Subject: Added documentation Added a default version of SetMasks: it can be called from the destructor --- comm/Multiplexer.cc | 101 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 79 insertions(+), 22 deletions(-) (limited to 'comm/Multiplexer.cc') 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 () { -- cgit v1.1