README.txt

————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
—														       —
- 	      Using Thread Pools & Micro Batching to Manage and Load Balance Active Network Connections		       —
—														       —
—														       —
—				      Jason D Stock - stock - 830635765 - Mar 05, 2019	    			       —
—														       —
————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————


This README.txt contains the following sections:

	- OVERVIEW

	- STARTUP

	- NOTES

	- STRUCTURE


——————OVERVIEW——————

Gradle is used for build automation, and can be executing manually with `gradle clean; gralde build`. The application
is constructed within a multi-layer package under `cs455.scaling`. Thus, the build directory will be constructed
with the compiled class files under `/build/classes/java/main`, and then the command-line arguments and the order in
which they should be specified for the server and the client nodes can be run by:  

	java cs455.scaling.server.Server server-port thread-pool-size batch-size batch-time
	java cs455.scaling.client.Client server-host server-port message-rate

Once the server is started on the `server-host`, multiple clients can be instantiated on multiple or a single machine. 


——————STARTUP——————

To simplify the process of instantiating multiple instances, the provided run script can be used. Within this script,
it is possible to configure the 'registry-host' and 'registry-port' to start the Registry on. There is a default for 
these values, but can be changed.

	1. (Optional) modify the application configurations in the 'run.sh' script

		HOST=indianapolis
		PORT=5001
		RATE=3

		POOL_SIZE=10
		BATCH_SIZE=50
		BATCH_TIME=5

	2. Add or remove desired clients to the application. Each machine should be on a new line, and can all be
	   unique or the same. Default is 25 machines
		
		vim machine_list
	
	3. Build the project using gradle

		gradle build

	4. Using the terminal, execute the run script to start the server and clients. (Optional) add an argument,
 	   integer, to launch more than one instance on a given host.

		./run.sh 2

At this point, there will be three terminals open; the original terminal, gnome-terminal for the server, and a 
gnome-terminal with tabs for each client instance.


——————NOTES——————

- The message-rate must be a a valid integer equal to or greater than 1.

——————STRUCTURE——————

cs455.scaling.client: consists of classes responsible for starting new clients, sending messages to the server, and
collecting statistics.

	- Client.java
		
		There are multiple Clients in the system that send and receive data
		to the server.
	 
		A client provides the following functionalities:
	
		- Connect and maintain an active connection to the server.
 		- Regularly send data packets to the server. The pay loads for these
		  data packets are 8 KB of randomly generated bytes. The rate at
		  which each connection will generate packets is R per-second.
		- The client will track hash codes of the data packets that it has
		  sent to the server. A server will acknowledge every packet that it
		  has received by sending the computed hash code back to the
		  respective client.
 	
		@author stock

	- ClientStatistics.java

		Hold statistics for the client that pertain to the number of sent
		and received messages. This class extends TimerTask, and is executed
		by the client ( specifying timer duration ).
	
		@author stock

	- SenderThread.java

		The sender thread will run continuously sending messages from the
		respective client to the server.
	
		@author stock

cs455.scaling.server: consists of classes responsible for the server, thread pool, and server-side statistics.

	- Server.java

		Only one server node in the system to manage incoming connections /
		messages.
 
		A server node will spawn a new thread pool manager with a set
		number of threads. The following functionalities will be provided,
		and rely on this thread pool:
		
		- Accept incoming network connections from the clients.
		- Accept incoming traffic from these connections.
		- Groups data from the clients together into batches.
		- Replies to clients by sending back a hash code for each message
		  provided.
		
		@author stock

	- ServerStatistics.java

	 	Server statistics for managing clients and throughput. This class
		extends TimerTask, and is executed by the server ( specifying
		timer duration ).

		@author stock

	- ThreadPoolManager.java

		A manager for the thread pool that creates the specified number of
		threads, and holds the queue of tasks that are needed to execute.
 
		@author stock

	- WorkerThread.java
		
		Working thread that processes objects off of the queue.
	
		When a new task is available on the queue it will be processed by
		the thread.
 	
		@author stock

cs455.scaling.server.taks: A task interface contains classes for receiving and writing data.

	- Task.java

		Public interface to delegate tasks to available working threads.
		This can include; registering new clients with {@link Register},
		reading data from clients via the {@link Receiver}, and sending
		data back to clients with the {@link Sender}.
	 
		@author stock

	- Register.java

		Task to delegate registration of a client with the server
 		(selector).

		@author stock
	
	- Receiver.java

		Processes data as received from the clients.
	
		The server will check a set of SelectionKeys, and upon one being
		readable, a new receiver will be made to manage that data. In turn
		adding the data to a collection of buffered data received from all
		clients in the system.
	
		@author stock

	- Sender.java

		New tasks, containing a list of data, will be processed and sent
 		back to the clients.
	
		A sender task contains the data and the respective clients for
		where to respond to data. When a new thread is available in thread
		pool manager, a thread will execute this task.
	
		@author stock

cs455.scaling.util: Package for application utilities, and reused code.

	- Logger.java
		
		Class used to print <b>info</b> and <b>error</b> logs to the
		console.
	
		@author stock

	- TransmissionUtilities.java

		Utilities class that are shared between the client and the server.
	
		@author stock


-- 

THANK YOU!!

Jason D. Stock