<!--
  - Authors:
  -   Christian Schulte <schulte@ps.uni-sb.de>
  -
  - Contributors (sgml translation):
  -   Daniel Simon <dansim@ps.uni-sb.de>
  -   Andy Walter <anwalt@ps.uni-sb.de>
  -
  - Copyright:
  -   Christian Schulte, 1998
  -
  - Last change:
  -   $Date: 1999-01-21 11:01:50 +0100 (Thu, 21 Jan 1999) $ by $Author: schulte $
  -   $Revision: 10566 $
  -
  - This file is part of Mozart, an implementation
  - of Oz 3
  -    http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -    http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->


<chapter id="chapter.sockets">
<title/Sockets/

<p>
A frequent need in programming open applications is to connect different
operating system processes such that they are able to exchange
data.  A tool for solving this problem are sockets. This chapter 
explains how to use sockets from Mozart.

<p>
Before starting to describe how to use them, we explain some basic
concepts. The explanation is short; for more detailed information see
for example <Ptr to="Stevens.90">.

<section id="section.sockets.nutshell">
  <title/Sockets in a Nutshell/

<p>
A socket is a data structure which can be used for communication between
operating system processes on possibly different computers connected by
a network.
<p>

<subsection id="section.domain">
<title/Domain/
<index scope="section.domain"/domain/

<p>
Unix based operating systems offers two domains for sockets: The <def/
Internet/ <index /domain<and>Internet/ domain and the <def/
Unix/<index /domain <and> Unix/ domain. The first can be used for
communication all over the world, whereas the latter is only applicable
within one Unix system. Other systems might offer only sockets for the
Internet domain. Mozart supports sockets for the
Internet domain.

</subsection>
<subsection id="section.type">
<title/Type/
<p>
<index scope="section.type"/type (of a socket)/

<p>
Sockets we are going to describe here are either of type <def /
stream/
<index /type (of a socket)<and>stream/ or of type <def/
datagram/ <index /type (of a socket)<and>datagram/. There are more than
these types of sockets, which are used by the operating system
internally for implementing stream and datagram sockets themselves. See
for instance <file/socket(2)/.

<p>
A <def /stream/ socket is connection-oriented: Two processes 
establish a one-to-one connection in using a socket. After the
connection has been established a stream socket has the following
features: 
<list enum>
<item> Stream oriented: Character codes are incrementally sent and
received.
<item> Duplex: Both processes have sending and receiving access to the
stream. The data passed are <def /bytes/, &ie; small integers between
0 and 255.
<item> Reliability: No data will be lost in most cases. 
<item> Sequencing: The order of data sent will not be changed.
</list>

<p>
A <def /datagram/ has only the feature of being duplex: It
provides no reliability and no sequencing (messages may arrive in any
order). It supports sending and receiving data packets of a (usually)
small size. 
<p>
</subsection>

<subsection>
<title/Protocol/
<index /protocol/

<p>
The protocol of a socket gives services used for performing
communication on it. For example, the usual protocols for
the Internet domain are TCP<index /protocol <and> TCP/ (Internet Transmission
Control Protocol) for stream sockets and UDP<index /protocol <and> UDP/
(Internet User Datagram Protocol) for datagram sockets.

</subsection>
</section>

<section id="section.sockets.stream">
<title/Stream Sockets/
<p>
Instead of giving detailed explanations, we will follow an example
tailored to understand how stream sockets for the Internet.
For this purpose, we use the class <<Open.socket>>. 

<subsection>
<title/Initiating a Connection/

<p>
Before any data between the server and the client can be exchanged, they
must initiate a connection. How to obtain a connection is shown in
<Ptr to="opprog-fig-stream">. We will perform the different steps
shown in the figure as an example.

<p>
<figure id="opprog-fig-stream">
<caption/Initiating a Stream Connection./
<picture latex>
\begin{center}
\unitlength .45cm
\thicklines
\begin{picture}(24,20)
\multiput( 4, 1)( 0, 4){5}{\oval(8,2)}
\multiput(20, 1)( 0, 4){3}{\oval(8,2)}
\multiput( 4, 4)( 0, 4){4}{\vector(0,-1){2}}
\multiput(20, 4)( 0, 4){2}{\vector(0,-1){2}}
\put( 0,18){\makebox(8,2){\large\bf Server}}
\put( 1,16){\makebox(6,2){Created}}
\put(4.5,14){\makebox(4,2)[l]{\texttt{init}}}
\put( 1,12){\makebox(6,2){Locally Initialized}}
\put(4.5,10){\makebox(4,2)[l]{\texttt{bind}}}
\put( 1, 8){\makebox(6,2){Globally Named}} 
\put(4.5, 6){\makebox(4,2)[l]{\texttt{listen}}}
\put( 1, 4){\makebox(6,2){Willing to Connect}}
\put(4.5, 2){\makebox(4,2)[l]{\texttt{accept}}}
\put( 1, 0){\makebox(6,2){Wait for Connection}}
\put(16,10){\makebox(8,2){\large\bf Client}}
\put(17, 8){\makebox(6,2){Created}} 
\put(20.5, 6){\makebox(4,2)[l]{\texttt{init}}}
\put(17, 4){\makebox(6,2){Locally Initialized}}
\put(20.5, 2){\makebox(4,2)[l]{\texttt{connect}}}
\put(17, 0){\makebox(6,2){Try to Connect}}
\put(12, 1){\vector(-1,0){4}}
\put(12, 1){\vector(1,0){4}}
\put( 8, 1){\makebox(8,1){Establish Connection}}
\end{picture}
\end{center}
</picture>
</figure>

<p>
The starting point for server and client are the topmost ovals on
the two sides of the figure. We first turn our attention to the
<<Server>> object. Basic initialization is performed by:
<chunk class=anonymous><title/server init/
Server = {New Open.socket init}
</chunk>
<index class=module/Open<and>socket/
<index class=module/Open<and>socket<and>init/

<p>
After execution of this message, <<Server>> has initialized the
local data structures it needs. 

<p>
After locally initializing the socket we have to provide it with a
global name. We use this global name for connecting our client to
this server. Feed:
<chunk class=anonymous><title/server bind/
{Server bind(port:{Browse})}
</chunk>

<index class=module/Open<and>socket<and>bind/

<p>
The Internet protocol services generate a so-called port number. The
port number is shown in the browser window. We refer to this number as
<<OurPort>> later on.

<p>
The combination of the host computer on which &Oz; is running and the
generated port number gives a unique address within the Internet
domain. So any other party in the Internet domain may use this pair to
refer unambiguously to this socket.

<p>
As next step, we signal that our socket is willing to accept
connections from another socket. To do so, we feed:
<chunk class=anonymous><title/server listen/
{Server listen}
</chunk>
<index class=module/Open<and>socket<and>listen/

<p>
Now we are ready to accept our connection. Typing:
<chunk class=anonymous><title/server accept/
{Browse H#": "#P}
{Server accept(host:H port:P)}
</chunk>
<index class=module/Open<and>socket<and>accept/
does nothing at the moment. But if a connection request is signaled
at port <<OurPort>> the connection is accepted. In this case 
<<H>> is bound to a string giving the name of the
computer the connection request was received from. In the same way
<<P>> is bound to the respective port.

<p>
The next step connects the <<Client>> to the <<Server>>.
<chunk class=anonymous><title/client init/
Client = {New Open.socket init}
</chunk>
<index class=module /Open<and>socket/
initializes our client object<index class=module/Open<and>socket<and>init/.

<p>
By typing
<chunk class=anonymous><title/client connect/
{Client connect(host:localhost port:OurPort)}
</chunk>
<index class=module /Open<and>socket<and>connect/
our client connects to the port <<OurPort>> on the same computer
(thus the virtual string <<localhost>>)<index /localhost/. 

<p>
Since our server suspended on a connection request at port
<<OurPort>> it now resumes, and the name of the host and the port
appears in the Browser window.
</subsection>

<subsection>
<title/Convenient Connection Establishment/

<p>
This was the whole story in detail, but for convenience we provide
two methods, which perform the complete connection establishment.

<p>
Instead of the various method applications, the following suffices
for the server:
<<<{Server server(host:?_{H} port:?_{P})}>>>
<index class=module/Open<and>socket<and>server/
Here ?_{P} is bound to the automatically generated port number. After a
connection has been accepted on this port, ?_{H} is bound to the string
containing the name of the connecting host.

<p>
Symmetrically, for the client side, one simply can use:
<<<{Client client(host: ?_{HostToConnectTo}
               port: ?_{PortToConnectTo})}>>>
<index class=module/Open<and>socket<and>client/
</subsection>

<subsection>
<title/Exchanging Data/

<p>
Now we can await data at our server by feeding
<chunk class=anonymous><title/server read/
{Server read(list:{Browse})}
</chunk>
<index class=module/Open<and>socket<and>read/

<p>
Sending data from our client can be accomplished via
<chunk class=anonymous><title/client write/
{Client write(vs:'Hello, good'#" old Server!")}
</chunk>
<index class=module/Open<and>socket<and>write/
and in the browser window (on the server side) the message appears.

<p>
By simply flipping <<Server>> and <<Client>> in the last two expressions
fed, you can send data from the server to the client.

<p>
Notice, however, that in this example server and client are created in
the same operating system process on the same host computer. Instead we
could have used two different processes and two different host
computers even running two different operating systems.

<p>
</subsection>

<subsection>
<title/Concurrency Issues/

<p>
Both reading and writing to a socket might not be possible
immediately. Possible reasons include:
<list enum>
<item> The data to be written is not yet bound to a virtual string.
<item> There is no data to be read at the moment.
<item> The socket can not transfer data over the network at the moment.
</list>

<p>
In this case access to the socket has to be synchronized in some
way. The following invariant is kept: all <<read>> messages are
performed in the order they were received by the object. The same holds
for all <<write>> messages. But there is no order between <<read>>s or
<<write>>s. Both the <<read>> and the <<write>> method reduce only when
the request can be served. 

<p>
If you want to make sure that both all <<read>> and <<write>> requests are
finished, you can use the method <<flush>>.
</subsection>

<subsection>
<title/Disconnecting/

<p>
If there is no further data to be exchanged between client and server, they
should be disconnected. The simplest way to do so is by feeding
<chunk class=anonymous><title/close/
{Server close}
{Client close}
</chunk>
<index class=module/Open<and>socket<and>close/

<p>
Suppose that the server closes before the client, and the client is
still sending data to the server. In this case the data will still arrive
at the socket. And only after some time the data will be thrown
away, consuming valuable memory resources. To prevent from this, you
can signal that you are not interested in receiving any messages, simply
by typing (before closing the object!)
<<<{Server shutDown(how: [receive])}>>>
<index class=module/Open<and>socket<and>shutDown/

<p>
If we are not interested in sending data anymore, we can inform
the operating system that we are indeed not willing to send anything
more, thus
<<<{Server shutDown(how: [send])}>>>
<index class=module/Open<and>socket<and>shutDown/

<p>
Both applications could have been combined into
<<<{Server shutDown(how: [receive send])}>>>
<index class=module/Open<and>socket<and>shutDown/
</subsection>

<subsection>
<title/Exceptions/

<p>
The methods of the class <<Open.socket>> might raise exceptions of the same
format as already described for the class <<Open.file>>, see
<Ptr to="section.files.basic">.
</subsection>
</section>

<section  id="section.sockets.accept">
<title/Accepting Multiple Connections/

<p>
A frequently occuring situation is to have a single server with a port
number known to several clients and that all these clients want to
connect to that server.  For this purpose sockets have the possibility to
accept more than a single connection.

<p>
The first step is to create the server socket <<S>> with a port number
<<P>>:
<chunk class=anonymous><title/server multi/
S={New Open.socket init}
P={S bind(port:$)}
{S listen}
</chunk>
The clients can connect later to this socket with the port number <<P>>.
<p>

<figure class=Program id="fig.setup.server">
<caption/Accepting multiple connections./
<chunk class=anonymous><title/Accept/
class Accepted from Open.socket
   meth report(H P)
      {Browse read(host:H port:P read:{self read(list:$)})}
      {self report(H P)}
   end
end

proc {Accept}
   H P A
in
   {S accept(acceptClass:Accepted
             host:?H port:?P accepted:?A)}
   thread 
      {A report(H P)} 
   end
   {Accept}
end
</chunk>
</figure>

<p>
How to set up the server is shown in <Ptr to="fig.setup.server">. The
procedure <<Accept>>  waits until the server socket <<S>> accepts a
connection. When a connection is accepted, the variable <<A>> is bound to
a newly created object. The object <<A>> is created from the class
<<Accepted>>, this is specified by the feature <<acceptClass>>. The newly
created object is already connected: Applying the object to the message
<<report(H P)>>  waits that on the accepted connection data arrives.

<p>
The loop to accept connections is started by applying the procedure
<<Accept>>:
<chunk class=anonymous><title/{Accept}/
{Accept}
</chunk>

<p>
Let us assume that we have two clients <<C1>> and <<C2>> that need to
connect to the socket with port number ?_{P}:
<chunk class=anonymous><title/multi client/
C1={New Open.socket client(port:P)} 
C2={New Open.socket client(port:P)}
</chunk>

<p>
After the clients are connected, sending data from the clients is as
usual:
<chunk class=anonymous><title/multi write/
{C1 write(vs:'hello from C1')}
</chunk>

<p>
As soon as the socket object created by the procedure <<Accept>> receives
the data sent from a client, the data appears in the Browser.
</section>

<section  id="section.sockets.datagram">
<title/Datagram Sockets/

<p>
Datagram sockets are for connectionless use. This implies that there is
no distinction between server and client. The basic patterns of use are
as follows.

<p>
<subsection>
<title/Initialization/

<p>
First we create and initialize two socket objects <<S>> and <<T>> with the
type <<datagram>>:
<chunk class=anonymous><title/datagram init/
S={New Open.socket init(type:datagram)}
T={New Open.socket init(type:datagram)}
</chunk>
<index class=module/Open<and>socket<and>init/

<p>
Both sockets can be named in the Internet domain as follows:
<chunk class=anonymous><title/datagram bind/
SPN={S bind(port:$)}
TPN={T bind(port:$)}
</chunk>
<index class=module/Open<and>socket<and>bind/
</subsection>

<subsection>
<title/Exchanging Data/

<p>
To send the virtual string
<<'really '#"great">> from socket <<S>> to socket <<T>>, we feed
<chunk class=anonymous><title/send/
{S send(vs:'really '#"great" port:TPN)}
</chunk>
<index class=module/Open<and>socket<and>send/

<p>
Data can be received as follows:
<chunk class=anonymous><title/receive/
{T receive(list:?Is port:?P)}
{Browse Is#' from: '#P}
</chunk>
<index class=module/Open<and>socket<and>receive/
and <<Is>> is bound to the string <<"really great">> and
<<P>> to the port number <<SPN>>.
The roles of sender and receiver may be toggled as you like.

<p>
To send to a socket on a different computer, the hostname of the
computer can be specified. For example, 
<<<{S send(vs:'donald' host:'duck.somewhere' port:4711)}>>>
would send <<'donald'>> to the socket with port number <<4711>> on the
computer <<duck.somewhere>>. Similarly, by using the field
<<host>> for the <<receive>> method the sending computer can be found out.
</subsection>

<subsection>
<title/Peer/

<p>
An additional feature of the datagram socket is the
ability to declare a socket as <def /peer/
<index /peer<and>of a socket/. Suppose we want to declare socket <<S>> as a peer of socket
<<T>>. This is done by 
<<<{S connect(port:TPN)}>>>
<index class=module/Open<and>socket<and>connect/

<p>
Now any message sent from socket <<S>> is received by socket
<<T>>. Furthermore, it suffices to specify just the data to be
sent. Hence
<<<{S send(vs:"really great")}>>>
<index class=module/Open<and>socket<and>send/
has the same effect as the previous example. As an additional
effect, only data sent by socket <<T>> is received at socket
<<S>>. After a peer has been assigned, you can even use the 
methods <<read>> and <<write>>.

<p>
Disconnecting is the same as for stream sockets.

<p>
</subsection>
</section>

<section  id="section.sockets.finger">
<title/Example: Are We Working Right Now?/

<p>
As an example, we show how to use the <file /finger/ service from &Oz;.
Services<index /service/ are programs running on a host, where
communication is provided by a socket connection. A well known example
is the <file /finger/ <index/<file /finger// service.

<p>
Services use the Internet domain, thus for connecting to them we need
the name of the host computer (&ie;its Internet address) and the port
of the socket. For this reason there is the procedure
<<OS.getServByName>><index /OS<and>getServByName/ (see
<Ptr.Extern to="ozdoc:system" key="chapter.os">) which gives the port of the socket
on which the service is available. Feeding 
<chunk class=anonymous><title/FingerPort/
FingerPort={OS.getServByName finger tcp}
</chunk>
binds <<FingerPort>> to the port number of the service. 

<p>
Note that one has to specify the protocol<index /protocol/ the service
uses, here the TCP protocol<index /protocol <and> TCP/ (as specified by the
virtual string <<tcp>>). The port number of a service is unique for all
computers, so this number does not depend on your localhost.

<p>
To get the information from this service we have to connect to the
finger service. If you want to know whether the author is working right
now, then you can connect to one of our computers with the Internet
address <<wallaby.ps.uni-sb.de>> on the <<FingerPort>>. This is done by
feeding the code shown in Program <Ptr to="Prog.finger">.

<p>
<Figure class=Program id="Prog.finger">
<caption/The finger client <<FC>>./
<index /FingerClient/
<chunk class=anonymous><title/FingerClient/
class FingerClient from Open.socket
   meth getInfo($)
      Is Ir 
   in
      if {self read(list:Is tail:Ir len:$)}==0 then nil
      else {self getInfo(Ir)} Is
      end
   end
end
FC = {New FingerClient client(host:'wallaby.ps.uni-sb.de' 
                              port:FingerPort)}
</chunk>
</figure>
<p>
For discovering whether the author is logged in, you have to send his
username (in this example <<schulte>>) followed by
a newline to the service, and then receive the information:
<chunk class=anonymous><title/schulte/
{FC write(vs:'schulte\n')}
{Browse {FC getInfo($)}}
</chunk>

<p>
For receiving the information we use the method <<getInfo>> which reads
the entire information from the socket until it is closed (the
finger service closes the connection automatically after sending its
information).
</section>


<![ %EXTRA; [
<section><title/NONE/
<p>
<chunk><title/EXAMPLES/
%%%
%%% Chapter: Sockets
%%%

%%
%% Stream Sockets
%%


%% Initiating a Connection
declare
<chunk.ref/server init/

<chunk.ref/server bind/

<chunk.ref/server listen/

declare H P in
<chunk.ref/server accept/

declare
<chunk.ref/client init/

%% 
%% YOU HAVE TO ENTER THE PORT NUMBER: OurPort
%%
declare
OurPort = ????
<chunk.ref/client connect/


%% Exchanging Data
<chunk.ref/server read/

<chunk.ref/client write/


%% Disconnecting
<chunk.ref/close/



%%
%% Accepting Multiple Connections
%%

declare
<chunk.ref/server multi/

declare
<chunk.ref/Accept/

<chunk.ref/{Accept}/

declare
<chunk.ref/multi client/

declare
<chunk.ref/multi write/



%%
%% Datagram Sockets
%%

declare
<chunk.ref/datagram init/

declare
<chunk.ref/datagram bind/

<chunk.ref/send/

declare Is P
<chunk.ref/receive/



%%
%% Example: Are We Working Right Now?
%%

declare
<chunk.ref/FingerPort/

declare
<chunk.ref/FingerClient/

<chunk.ref/schulte/



</chunk>
]]>


</chapter>
