From ba066c34dde204aa192d03a23a81356374d93731 Mon Sep 17 00:00:00 2001 From: chatty Date: Wed, 7 Apr 1993 11:50:31 +0000 Subject: Initial revision --- comm/doc.main | 396 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 396 insertions(+) create mode 100644 comm/doc.main (limited to 'comm/doc.main') 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} -- cgit v1.1