Initial revision

1 files changed, 396 insertions, 0 deletions

diff --git a/comm/doc.main b/comm/doc.main
new file mode 100644
index 0000000..44abcd4
--- /dev/null
+++ b/comm/doc.main
@@ -0,0 +1,396 @@
+%
+%	The Unix Channel
+%
+%	by Michel Beaudouin-Lafon
+%
+%	Copyright 1990-1993
+%	Laboratoire de Recherche en Informatique (LRI)
+%
+%	User's Manual main file - to be updated
+%
+%	$Id$
+%	$CurLog$
+%
+
+\namedoc{Unix Channel}
+\def\uch{{\sc Uch}}
+
+\chapter{Introduction}
+%--------------------------------
+
+The Unix Channel library provides a set of classes to build distributed applications
+under Unix using sockets.
+
+The first level of the library, described in chapter \ref{General io}, defines basic
+classes: messages to be exchanged, buffers to hold data (usually messages),
+file descriptors that represent communication channels, and channel sets for
+multiplexing input/output.
+
+The second level, described in chapters \ref{Addresses} and \ref{Basics}, defines
+classes to build networks of processes exchanging messages.
+The different classes implement different transport protocols: datagrams (fast but
+unreliable), byte streams (reliable but without message boundaries), and streams
+(reliable delivery of messages).
+
+The third level is a specialized set of classes for implementing distributed
+applications using the client/server architecture. Chapter \ref{Servers} describes
+the server side, while chapter \ref{Clients} describes the server side.
+An application can be both a server and the client of other applications.
+
+Finally chapter \ref{Portserv} describes a set of classes to communicate
+addresses between the components of a distributed application.
+Most of the time th eoperating system allocates the channel addresses;
+a cumbersome part of the protocol often is for a client to know the physical address
+of a server from a logical name.
+The port server described in chapter \ref{Portserv} implements a service that maps 
+logical names to physical addresses with a context.
+
+The present documentation assumes some knowledge of the network facilities
+available under Unix, as described in the document
+``{\em A Socket-Based Interprocess Communication Tutorial}''.
+This document is part of the Unix documentation.
+
+Some knowledge of the {\em CCU} library is also needed.
+This library is described in the document
+``{\em CCU, the CENA C++ Utilities library}''.
+\uch\ uses that library mainly for {\em smart pointer} classes.
+Given a class \typ{A}, a smart pointer class to \typ{A}, usually named \typ{pA},
+implements a class that behaves like pointers to objects of class \typ{A} (\typ{A*}),
+with the following additional feature:
+the pointed to object maintains a count of the number of smart pointers
+pointing to it; when this reference count reaches zero and the object was
+allocated dynamically (with \fun{operator new}), it is automatically destroyed.
+
+
+\section{Using The Unix Channel}
+\uch\ is provided as 4 files~: 
+
+\begin{enumerate}
+
+  \item 
+  the header files \com{chan.h} and \com{uch.h}, usually installed in \com{/usr/include/CC},
+  contains the definitions for classes, functions and constants provided by \uch.
+  \com{chan.h} contains the classes described in chapter \ref{General io} and can be used
+  in simple applications.
+  \com{uch.h} contains all the classes and is to be used by advanced applications.
+  One of these files should be included in any file using the library.
+  As most of \uch\ functions are member functions, this file can
+  be used as a quick reference.
+  
+  \item
+  \samepage 
+  {the archive files \com{libUch.a} and \com{libChan.a}, which are usually installed in \com{/usr/lib} 
+  or in \com{/usr/loc\-al/lib}, contain the library procedures. One of these libraries must be loaded 
+  with the object files which use \uch. This is usually performed
+  by adding the flag \com{-lUch} or \com{-lChan} in the command line for your C++ compiler. 
+  \uch\ uses the utilities library, so \com{libutils++.a} must be included when loading an application.
+  \com{libUch.a} contain the object files for the whole library, while \com{libChan.a}
+  contains only the object files for the classes described in chapter \ref{General io},
+  corresponding to the header file \com{chan.h}.
+  For instance, you can type~:
+  \begin{center}
+  	\com{CC -o demo main.C -lUch -lCcu}
+  \end{center}}
+ 
+\end{enumerate}
+
+
+\chapter{Error management}
+
+#iclass UchError
+
+\chapter{General io}
+\label{General io}
+
+This chapter describes the very basic classes of \uch.
+
+Unix input/output is byte oriented: byte buffers can be read and written in file descriptors
+with the system calls \fun{read} and \fun{write}.
+\uch\ implements message oriented input/output,
+although byte io can be used if needed.
+The class \typ{Message} is the abstract base class for the messages
+to be exchanged between applications. A \typ{Message} only needs to
+know how to convert itself to and from a set of bytes in a \typ{MsgBuffer}.
+The class \typ{MsgBuffer} is used throughout \uch\ to buffer input and output.
+Buffering output can dramatically improve performances (especially if the
+messages are short), while buffering input is necessary to implement message
+delivery (a message can be received in several pieces that need to be gathered
+before actual delivery to the application).
+
+The following types are defined for machine independent handling of data:
+\begin{itemize}
+\item The type \typ{^{byte}} is defined as an 8-bit quantity. Buffers contain bytes.
+\item The type \typ{^{sword}} refers to a 16-bit quantity.
+\item The type \typ {^{lword}} refers to a 32-bit quantity.
+\end{itemize}.
+
+The class \typ{UchFilDes} encapsulates the Unix notion of file descriptor.
+The class \typ{UchChannel} derives from \typ{UchFilDes}, adding virtual functions
+for implementing multiplexing and communication protocols.
+The class \typ{UchMultiplexer} implements a set of channels for multiplexing
+input and output.
+
+These classes are not sufficient to write distributed applications because
+there is no way to establish a communication between two processes.
+However they can be used for traditional input/output to terminals and files.
+This is illustrated in section \ref{General io example}.
+
+#class UchMessage
+#class UchMsgBuffer
+#class UchFilDes
+#class UchChannel
+#class UchMultiplexer
+
+\section{Example}
+\label{General io example}.
+
+[to be done]
+
+\chapter{Addresses}
+\label{Addresses}
+
+Processes can communicate once a channel has been established
+between them. One of the process has to create the channel, and thus has to
+know the other process. More precisely, a process connects to an {\em address}
+on which the other process is listening.
+This chapter describes classes that represent such addresses.
+
+Addresses can be established in different {\em domains}.
+Think of e-mail addresses and surface mail addresses: they are
+completely different although both can be used to reach the same person.
+Two domains are implemented: Unix domain addresses, and internet domain addresses.
+
+A Unix domain address is represented by a file in the file system.
+A process only needs to open the file to connect to the process that created the address.
+An internet domain address is made of a host number and a port number.
+It makes it possible for processes on different machines to communicate.
+Unfortunately the port numbers of internet addresses are usually assigned by
+the system, so that a distant process cannot know this port number to
+establish the communication.
+The port server described in chapter \ref{Portserv} overcomes this problem.
+It is often used to create internet addresses from logical names,
+instead of the class \typ{UchInetAddress} described in this chapter.
+
+#class UchAddress
+#class UchUnixAddress
+#class UchInetAddress
+
+
+\chapter{Basic communications}
+%--------------------------------
+\label{Basics}
+
+This chapter describes the main classes for developing distributed applications.
+The communication between the processes is done by using Unix sockets.
+The class \typ{UchSocket} encapsulates such sockets, but it is an abstract base class.
+The classes \typ{UchDatagram} and \typ{UchStream} implement the two main
+protocols available under Unix, i.e. datagrams and streams.
+These protocols differ in the way the connection can be established and the way
+the data is transmitted between the processes.
+In particular, streams transfer bytes and do not know about messages.
+The class \typ{UchMsgStream} extends the stream protocol to transfer messages
+and not bytes.
+This is the class that will be used most of the time to build distributed applications,
+as illustrated in section \ref{Basics example}
+
+\fig{socketclasses}{Hierarchy of classes}
+
+Figure \ref{fig:socketclasses} shows the derivation tree for the classes described
+in this chapter. All derivations are public. This means that the member functions
+of a base class are available in its derived classes, although they appear in the
+documentation only for the base class.
+
+#class UchSocket
+#class UchDatagram
+#class UchStream
+#class UchMsgStream
+#class UchDGRAM
+
+\section{Example}
+\label{Basics example}
+
+[to be done]
+
+\chapter{Servers}
+%--------------------------------
+\label{Servers}
+
+This chapter describes the classes \typ{UchServer} and \typ{UchClient} to be used
+to implement a server.
+A server is a process that accepts connections from several clients,
+and processes their requests.
+
+When implementing a server, there is one object of class \typ{UchServer},
+and one object of class \typ{UchClient} for each connected client.
+Each such \typ{UchClient} object is connected to another process where
+a corresponding \typ{Service} object exists (see figure \ref{fig:clientserver}).
+We call these processes the clients of the server:
+a \typ{UchClient} represents a connected client in the server,
+while a \typ{Service} represents the server in a client.
+
+\fig{clientserver}{Objects in a client-server system}
+
+The class \typ{Service} is useful only if your application follows an
+event/request protocol.
+If this is not the case, you can create your own class, derived from
+class \typ{MsgStream}.
+The class \typ{Service} and the associated classes for managing
+events are described in chapter \ref{Clients}.
+
+#class UchServer
+#class UchClient
+
+\chapter{Clients}
+\label{Clients}
+
+An object of a class derived from \typ{UchMsgStream} must exist in a client process to communicate
+with its server (implemented by an object of class \typ{UchClient} in the server process).
+
+The class \typ{UchService} described here can be used when the protocol between the
+server and its clients is of the event/request type.
+
+\fig{evreq}{Event / request protocol model.}
+
+In the event/request model (see figure \ref{fig:evreq}),
+a client communicates with a server by sending requests.
+These requests are generally asynchronous, thus allowing buffered i/o.
+Some requests may need an answer from the server: those requests are synchronous by nature.
+The server sends events to its clients; 
+events are asynchronous by nature: a server never waits for an answer from a client,
+for this would potentially block it.
+
+Incoming requests are stored in an event queue for later processing by the client:
+usually the client reads an event in its top-level loop, and responds to it;
+this may involve sending requests to the server, that in turn will generate events.
+
+A single client may want to be connected to several servers.
+The class \typ{UchService} makes this possible by allowing to share an event queue
+between several services.
+Thus incoming events are multiplexed, and the top level loop of the client is of the
+same form as above.
+Each event contains the server that sent it so that it can be easily dispatched by the client.
+
+Events are messages. They are implemented by the virtual base class \typ{EventMsg}.
+The event queue of a service is implemented by the class \typ{UchEvtMsgQueue}.
+
+#class UchService
+#class UchEventMsg
+#class UchGenEvtMsg
+#class UchEvtMsgQueue
+
+\chapter{Port registration server}
+\label{Portserv}
+
+A client and a server need to agree on an address to establish a communication.
+Internet addresses are generally allocated by the system by passing a null port number;
+thus, there is no simple way for the clients to know on which address the server is listening.
+
+The standard solution to this problem is to use the services database of Unix,
+to associate a given port number to a service name.
+This database is not designed to be updated easily (it is the job of the system administrator),
+so it is not possible for a server to register its address in this database each time the server is launched.
+Instead, for a given service, the database holds the service name and port number of a daemon,
+and this daemon maintains the address of the server currently implementing this service.
+Several servers may use the same daemon, for instance if a given service
+needs one server per different user.
+
+The port server is such a daemon.
+The port server is a separate process that stores associations between keys and addresses.
+Each such association represents a server that is available.
+The key can encode the service name, user, etc...
+Servers register themselves by entering their address with a key and an identification
+(usually their process number);
+they can (they should) remove their entry from the port server whenever they die.
+In order to connect to a server, a client inquires the address to the port server by sending it the key.
+It is also possible to ask the port server a set of keys based on a regular expression.
+
+The port server itself is run by the following command:
+\begin{ccode}
+portserv [ service [ file [ savetime ] ] ]
+\end{ccode}
+\var{service} is the name of the service as stored in the services database (default is ``\com{portserv}'').
+\var{file} is the name of a file to store the state of the port server.
+Reloading such a file is not currently implemented.
+If \var{file} is ``$-$'', standard output is used, if it is ``$--$'', standard error is used.
+If \var{file} is not specified, the saving feature is disabled.
+If \var{savetime} is specified, it determines how many seconds after a modification
+the new state is saved. If it is not specified, the state is saved immediately after each modification.
+The save time is intended for port servers that are heavily used in order to reduce file accesses.
+
+#class UchPortServer
+
+\section{Testing the port server}
+
+\com{porttest} is a simple program that can be used to interact with a port server.
+Each call to \com{porttest} connects to a port server and executes an operation on it,
+depending on the arguments of the command.
+The port server that \com{porttest} connects to has name ``\com{portserv}'',
+and is on the local host by default.
+If the first argument is of the form \com{=}\var{service},
+it connects to a service named \var{service} instead of \com{portserv}.
+If the first or second argument is of the form \com{:}\var{host},
+it connects to a portserv on the machine \var{host} instead of the local host.
+
+The different commands are the following:
+\begin{itemize}
+\item
+	\com{porttest [=service] [:host]}\\
+	Ask the port server to dump its state on its standard error.
+\item
+	\com{porttest [=service] [:host] quit}\\
+	Make the port server exit.
+\item
+	\com{porttest [=service] [:host] key}\\
+	Inquire \var{key}. If found, it is printed with its associated address,
+	else an error message is printed.
+\item
+	\com{porttest [=service] [:host] ?rekey}\\
+	Inquire all keys matching \var{rekey}.
+\item
+	\com{porttest [=service] [:host] key portnumber}\\
+	Register \var{key} with an address made of port \var{portnumber} on the local host.
+	\com{porttest} provides its own identification for registration.
+\item
+	\com{porttest [=service] [:host] key -portnumber}\\
+	Remove \var{key}, if bound to the address made of port \var{portnumber} on the local host.
+\end{itemize}
+
+\section{Sample usage}
+
+[to be done]
+
+\newpage
+\appendix
+
+\chapter{Class List}
+
+This chapter contains the list of the classes defined in \uch.
+The first section contains the inheritance tree of \uch\ classes.
+The second section contains for each class the ordered list of its base classes.
+The section number indicated after each class refers to the
+documentation of that class. The class names that appear in italic
+are defined in other libraries. Classes defined in \uch\ but
+which are not documented do not appear in the lists.
+
+\section{Inheritance Tree}
+This section contains the set of classes defined in \uch.
+Each base class is followed by the indented list of its subclasses.
+
+\input{inhtree.tex}
+
+\newpage
+\section{Inheritance List}
+This section contains the set of classes defined in \uch.
+Each class is followed by its base class, recursively.
+Thus, from a given class, one can follow the inheritance link
+and thus refer to the documentation for the inherited methods.
+
+\begin{inhlist}{XXXXXXXXXXXXXXXX}
+\input{inhlist.tex}
+\end{inhlist}
+
+\begin{theindex}
+\indexinc
+\end{theindex}
+
+\end{document}