From 8b8b81f26d73b02cccd0fb2a3220b154945c446d Mon Sep 17 00:00:00 2001
From: Ilkka Seppala <iluwatar@gmail.com>
Date: Sun, 17 May 2015 21:45:20 +0300
Subject: [PATCH] Added code comments.

---
 .../src/main/java/com/iluwatar/App.java       | 24 +++++++++++++++++++
 .../java/com/iluwatar/CoffeeMakingTask.java   |  5 ++++
 .../java/com/iluwatar/PotatoPeelingTask.java  |  5 ++++
 .../src/main/java/com/iluwatar/Task.java      |  5 ++++
 .../src/main/java/com/iluwatar/Worker.java    |  5 ++++
 5 files changed, 44 insertions(+)

diff --git a/thread-pool/src/main/java/com/iluwatar/App.java b/thread-pool/src/main/java/com/iluwatar/App.java
index 101dde037..9bd539425 100644
--- a/thread-pool/src/main/java/com/iluwatar/App.java
+++ b/thread-pool/src/main/java/com/iluwatar/App.java
@@ -5,12 +5,27 @@ import java.util.List;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 
+/**
+ * 
+ *  Thread Pool pattern is where a number of threads are created to perform a number of tasks, 
+ *  which are usually organized in a queue. The results from the tasks being executed might 
+ *  also be placed in a queue, or the tasks might return no result. Typically, there are many 
+ *  more tasks than threads. As soon as a thread completes its task, it will request the next 
+ *  task from the queue until all tasks have been completed. The thread can then terminate, or 
+ *  sleep until there are new tasks available.
+ *  
+ *  In this example we create a list of tasks presenting work to be done. Each task is then 
+ *  wrapped into a Worker object that implements Runnable. We create an ExecutorService with
+ *  fixed number of threads (Thread Pool) and use them to execute the Workers.
+ *
+ */
 public class App {
 	
     public static void main( String[] args ) {
     	
     	System.out.println("Program started");
     	
+    	// Create a list of tasks to be executed
     	List<Task> tasks = new ArrayList<>();
     	tasks.add(new PotatoPeelingTask(3));
     	tasks.add(new PotatoPeelingTask(6));
@@ -28,11 +43,20 @@ public class App {
     	tasks.add(new PotatoPeelingTask(4));
     	tasks.add(new PotatoPeelingTask(5));
     	
+    	// Creates a thread pool that reuses a fixed number of threads operating off a shared 
+    	// unbounded queue. At any point, at most nThreads threads will be active processing 
+    	// tasks. If additional tasks are submitted when all threads are active, they will wait 
+    	// in the queue until a thread is available.
     	ExecutorService executor = Executors.newFixedThreadPool(3);
+    	
+    	// Allocate new worker for each task
+    	// The worker is executed when a thread becomes
+    	// available in the thread pool
     	for (int i=0; i<tasks.size(); i++) {
 	    	Runnable worker = new Worker(tasks.get(i));
 	    	executor.execute(worker);
     	}
+    	// All tasks were executed, now shutdown
     	executor.shutdown();
     	while (!executor.isTerminated()) {
     	}
diff --git a/thread-pool/src/main/java/com/iluwatar/CoffeeMakingTask.java b/thread-pool/src/main/java/com/iluwatar/CoffeeMakingTask.java
index fb4f5924b..9117b4691 100644
--- a/thread-pool/src/main/java/com/iluwatar/CoffeeMakingTask.java
+++ b/thread-pool/src/main/java/com/iluwatar/CoffeeMakingTask.java
@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * CoffeeMakingTask is a concrete task
+ * 
+ */
 public class CoffeeMakingTask extends Task {
 
 	private static int TIME_PER_CUP = 300;
diff --git a/thread-pool/src/main/java/com/iluwatar/PotatoPeelingTask.java b/thread-pool/src/main/java/com/iluwatar/PotatoPeelingTask.java
index 671c736d9..51b77444f 100644
--- a/thread-pool/src/main/java/com/iluwatar/PotatoPeelingTask.java
+++ b/thread-pool/src/main/java/com/iluwatar/PotatoPeelingTask.java
@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * PotatoPeelingTask is a concrete task
+ *
+ */
 public class PotatoPeelingTask extends Task {
 
 	private static int TIME_PER_POTATO = 500;
diff --git a/thread-pool/src/main/java/com/iluwatar/Task.java b/thread-pool/src/main/java/com/iluwatar/Task.java
index d6e925df5..378bb432d 100644
--- a/thread-pool/src/main/java/com/iluwatar/Task.java
+++ b/thread-pool/src/main/java/com/iluwatar/Task.java
@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * Abstract base class for tasks
+ *
+ */
 public abstract class Task {
 
 	private static int nextId = 1;
diff --git a/thread-pool/src/main/java/com/iluwatar/Worker.java b/thread-pool/src/main/java/com/iluwatar/Worker.java
index 6044ac62c..8dab04063 100644
--- a/thread-pool/src/main/java/com/iluwatar/Worker.java
+++ b/thread-pool/src/main/java/com/iluwatar/Worker.java
@@ -1,5 +1,10 @@
 package com.iluwatar;
 
+/**
+ * 
+ * Worker implements Runnable and thus can be executed by ExecutorService
+ *
+ */
 public class Worker implements Runnable {
 	
 	private Task task;