\documentstyle[times,11pt,moretext] {article}
\input macros
\input widen
\input psfig

\begin{document}
\centerline{\Large Washington University}
\centerline{\Large Department of Computer Science}
\bigskip
\centerline{\large CS523: Distributed Operating Systems}
%\smallskip
%\centerline{\large Spring 1995}
\bigskip
\centerline{\large Programming Project}
% \centerline{\large Due Tuesday, January $31^{st}$, 1995}

\section{Overview}

In this assignment, you will implement a distributed logging service
shown in Figure~\ref{logenv}.  Applications use this service to log
information (such as error notifications, debugging traces, and status
updates) in a distributed environment.  In this service, CORBA remote
operations are used to send logging records to a central logging
server.  The logging server outputs the logging records to a console,
a printer, a file, or a network management database, etc.

\section{Design and Implementation Issues}

The distributed logging service will be designed as a client/server
pair, containing the objects shown in Figure~\ref{simplog}.

\subsection{CORBA IDL Specification}
The following CORBA IDL specification defines the logging interface:

{
\small
\ls{0.9}
\begin{verbatim}
// IDL schema definition
interface Logger
{
  // Types of logging messages.
  enum Log_Priority {
      LM_DEBUG,   // Debugging messages
      LM_WARNING, // Warning messages
      LM_ERROR,   // Errors
      LM_EMERG    // A panic condition
  };

  // Format of the logging record.
  struct Log_Record {
    Log_Priority   type;      // Type of logging message.
    long           time;      // Time stamp at sender.
    long           app_id;    // Process ID of sender.
    long           host_addr; // IP address of the sender.
    sequence<char> msg_data;  // Sender-specific logging message.
  };

  // Transmit a Log_Record to the logging server.
  oneway void log (in Log_Record log_rec);

  // Toggle verbose formatting
  attribute char verbose; 
};
\end{verbatim}}

\begin{figure}
\center{\ \psfig{figure=graphics/logsimp.eps,width=13cm}\ }
\vspace{-0.12in}
\caption{Distributed Logging Service}
\label{logenv}
\end{figure}

You will use a CORBA IDL compiler to translate this specification into
client-side {\em stubs} and server-side {\em skeletons}.  The client
application (which you must write) will use the stubs as a {\em proxy}
to access the logging services provided by the server.  You must also
write the implementation of the server, which provides the logging
service.

\subsection{Client and Server Functionality}
For the purposes of the assignment, you can make the client driver
program very simple.  The client can read a line from its standard
input and send it to the logging server.  The server can then format
and print the line on its standard output.  For example, if you type
this line to the client:

\begin{verbatim}
To boldly go where no one has gone before
\end{verbatim}

\noindent Then the server should output something like this:

\begin{verbatim}
Jan 24 14:50:28 1995@tango.cs.wustl.edu@18352@LM_DEBUG
::To boldly go where no one has gone before
\end{verbatim}

\noindent Note that the server has printed out the logging message
timestamp, sender's hostname and process id, and the message priority,
followed by the logging message data.

\begin{figure}
\center{\ \psfig{figure=graphics/simplog.eps,width=13cm}\ }
\vspace{-0.12in}
\caption{CORBA-based Logger Design}
\label{simplog}
\end{figure}

Note that in order to pass the client's IP address (which is
represented as a 4-byte {\tt long}) in the logging message, you'll
need to learn about several other UNIX routines.  On the client-side
you'll need to use {\tt uname(2)} and {\tt gethostbyname(2)} to
determine the IP address of the client host.  On the server-side,
you'll need to use the {\tt gethostbyaddr(2)} function to convert the
4-byte IP host address into an ASCII version of the host name.  I
recommend that you check the manual pages and read Richard Steven's
book ``UNIX Network Programming'' for more details on using these
functions.

\subsection{Invoking the Client and Server}
Once the client and server components are written, compiled, and
linked together you will use the {\tt putit} command to register the
server with the Orbix daemon.  You'll then need to start up a copy of
{\tt orbixd} (if there isn't already one running).  {\tt orbixd}
serves as the Object Request Broker for the local endpoint.

A client will bind to the {\tt Logger} interface via the generated
{\tt Logger::\_bind} method.  There are two general ways to use this
method.  The first is to explicitly pass in the name of the server
where {\tt orbixd} is running (your client should accept a
command-line argument that is the name of the server, {\em e.g.,}
``tango.cs.wustl.edu'').

The second method is to use the CORBA locator service to get an object
reference for the logging service.  You'll need to read the Orbix
documentation to learn how to set up a location file.  This file will
enable you to omit the name of the server in the call to {\tt
Logger::\_bind}.  By using the locator server, your clients can bind
to object's implicitly.  Make sure that your solution will work for
either implicit or explicit service location.

Once the client application has bound (either explicitly or
implicitly) to an object reference for the {\tt Logger}, it can log
messages by calling the {\tt log} method via the object reference
proxy.

\subsection{Performance Measurement}

An important part of developing distributed systems is understanding
the performance implications of different design approaches.  In order
to measure the performance overhead of using CORBA to build the
Logger, you will write a simple extension to the original {\tt Logger}
interface, as follows:

{
\small
\ls{0.9}
\begin{verbatim}
// IDL schema definition
interface Profile_Logger 
  : Logger // Profile_Logger IS-A Logger
{
  // Stores the amount of time that has elapsed.
  struct Elapsed_Time
  {
    double real_time;
    double user_time;
    double system_time;
  };
 
  // Activate the timer.
  void start_timer (void);

  // Deactivate the timer and return the elapsed time.
  void stop_timer (out Elapsed_Time et);
};
\end{verbatim}}

\noindent You will need to modify your client program so that it can
time a series of {\tt Logger::log} operations for various sizes of
logging messages.  This will help us understand the performance
overhead of CORBA.

The main benchmarking should take place within a loop in your client
program.  Basically, your client call {\tt
Profile\_Logger::start\_timer} just before sending the first of the
logging messages.  After a suitable number of iterations (defined on
the command-line), you client will call {\tt
Profile\_Logger::stop\_timer} to determine and report the elapsed time
to the user.  You should print out the ``real'' time, as well as the
``system $+$ user'' times.  Make sure that you print out the
throughput in terms of megabits/sec (rather than bytes/sec or
kbytes/sec).  Be sure to include the fixed-sized {\tt Log\_Record}
object, as well as the variable-sized {\tt msg\_data} portion in your
computations.

The number of iterations and the size of the messages sent by the
client should be parameterizable on the command-line.  Make sure that
your timing tests are run between processes on two different machines
(rather than processes on the same machine).  If possible, try to run
the client and server processes on two machines on the same subnet.

When you are finished with your timing test, you should explain the
timing results and indicate trends that you observed.

\section{Learning and Using CORBA}

To help you learn how CORBA works, I will be making copies of the
Orbix programmer's manual available for a small reproduction fee.
This manual explains how to program in CORBA.  I will announce in
class where this will be available.

We will be using IONA's Orbix CORBA Object Request Broker (ORB)
implementation.  The libraries, executables, CORBA IDL compiler, and
example demo applications are located in {\tt
/project/adaptive/Orbix}.  Please note that this is an automounted
directory, so you will need to {\tt cd} directly to it in order to see
the contents.  To configure Orbix for your environment, copy the {\tt
/project/adaptive/Orbix/Orbix.cfg} file to your account.  You'll need
to set the environment variable {\tt IT\_CONFIG\_PATH} to the complete
path where this file is located.

\section{Concluding Remarks}
In office hours and in class, we will discuss how to use C++ and CORBA
in order to develop your solutions.  Note that this assignment will
teach you many skills required to become adept at network programming.
However, it also will require a great deal of thought and planning.
Please make sure you start early, come to office hours, and ask lots
of questions.

\end{document}