%
%	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$
%

\documentstyle[11pt,mydoc,twoside]{doc}

\pagestyle{ENTETE}
\makeindex

\namedoc{Unix Channel}
\def\uch{{\sc Uch}}

\begin{document}
\maketitle
\cleardoublepage
\tableofcontents

\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{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{UchMessage} is the abstract base class for the messages
to be exchanged between applications. A \typ{UchMessage} 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.
The class \typ{UchIOS} is a base class for input/output streams: message buffers,
channels, etc.

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}.

\section{Messages}
The basic entities used to transfer information are messages and buffers. Low level
mechanisms ensure the transmission of data and store it in a buffer. That raw data
is then extracted from the buffer, and used to initialize the fields of a message.
The emission of messages works in a similar way: the contents of a message are
copied to a buffer before being sent.

\subsection{Messages}
#iclass UchMessage

\subsection{Buffers}
#iclass UchMsgBuffer

\section{Files and channels}
#iclass UchFilDes
#iclass UchChannel

\section{Base IO streams}
#iclass UchIOS

\section{Multiplexing channels}
#iclass UchBaseMultiplexer
#iclass UchMultiplexer

\subsection{Adding timers}
#iclass UchBaseTimeOut
#iclass UchTimeOut

\subsection{Safe signal handling}
#iclass UchBaseSignalHandler
#iclass UchSignalHandler

\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{FIGURES/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{FIGURES/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{FIGURES/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]

\chapter{Error management}
#iclass UchError


\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}