#    Copyright (c) 1998 University of Southern California.
#    All rights reserved.                                            
#                                                                   
#    Redistribution and use in source and binary forms are permitted
#    provided that the above copyright notice and this paragraph are
#    duplicated in all such forms and that any documentation, advertising
#    materials, and other materials related to such distribution and use
#    acknowledge that the software was developed by the University of
#    Southern California, Information Sciences Institute.  The name of the
#    University may not be used to endorse or promote products derived from
#    this software without specific prior written permission.
#    
#    THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
#    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
#    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.


LSAM OBJECT SCHEDULING
======================
Document Version 1.0 (3/25/98)
More Information: http://www.isi.edu/lsam/scheduling


Introduction
------------
The LSAM server supports different service classes for requests. Requests may 
either be foreground (FG) or background (BG) requests. Responses to requests 
may be sent in the FG or BG as well. This can be thought of as a form of
differentiated services.

FG requests and responses are being received, processed and/or sent out
using the normal apache methods. BG requests and responses, however, are
dealt with in a special way as to minimize their impact on FG performance.
This may include delaying them longer or maybe not processing them altogether,
depending on the FG load.

BG requests and responses will be used for cache preloading in the future.

The current version of the object scheduler is limited in the following ways:

Unicast Only: 
	Responses can only be unicast, there is no support for multicast yet.

Distinguishing between FG and BG requests:
	There is currently no inherent way to distinguish a FG from a BG
	request. Instead, the server listens on two ports, a "FG port" and
	a "BG port". All requests arriving on the FG port are assumed to
	be FG requests and treated as such, while all requests arriving at
	the BG port are treated as BG requests.

These limitations are due to the fact that this version of the scheduler was
implemented as a way to experiment with several different methods of processing
background requests and sending out BG responses with minimal impact on FG
performance. Code for all of them is included in the distribution. Setting 
_LSAM_BG_UCAST will set up the BG sending method we consider best at this time.

This server will create three extra processes in the process pool that only 
serve BG requests. The three servers will run at a lowered priority (20). 
Their combined send rate is limited to 1.0 Mbit/sec (actual combined send
rate for BG traffic may be lower.) 


Compilation
-----------
1. Modify src/Configuration such that EXTRA_CFLAGS defines _LSAM_BG_UCAST.
   One way of doing this is to add this line:
   EXTRA_CFLAGS+=-D_LSAM_BG_UCAST

2. Run the apache configuration utility.

3. Recompile.

4. Modify conf/httpd.conf to make apache listen on a second port.
   This is done by adding a listen statement, for example:
   Listen 8001

   If you want to use a different port than 8001, modify 
   src/object_scheduling.h accordingly.

   There seems to be a bug in apache that causes it to only listen on ports
   listed in listen statements, even if they are listed in a port statement,
   too. To circumvent that, add a listen statement for your main server port.
   For example if your port statement reads "Port 80", add the following line:
   Listen 80

   It is a good idea to also add "LogLevel debug" to the configuration file.
   It helps somewhat if things go wrong.

5. Test the server. For example, with the server host being lsam with a FG port
   of 80 and a BG port of 8001, http://lsam:80/ would be processed as a FG
   request, while http://lsam:8001/ would be processed as a BG request.


Configuration
-------------
To play around with the different BG sending methods, read and modify 
src/main/object_scheduling.h.


Execution
---------
Run the server normally.


Upcoming Features
---------------
	* easier configuration through the configuration file
	* support for multicast responses
	* improved ways of processing and sending BG traffic