Assignment 4 Guide: Campus Print Spooler

1. What Was Given

Build a thread-safe, bounded, cancellable print spooler — the kind of software that accepts print jobs from many users and dispatches them to a limited number of printer workers (like a shared campus lab printer).

Total marks: 70, split across three grading areas:

A template project was provided with the full API layer (interfaces, records, enum) already written. The student implements three classes: BoundedJobQueue, JobRegistry, and SpoolerImpl. PrintWorker and JobRecord were given and work once the TODOs are complete.

Allowed concurrency topics

• Thread, Runnable
• synchronized blocks and methods
• volatile fields
• wait() / notifyAll()
• ExecutorService / Executors.newFixedThreadPool(...)
• AtomicLong (and similar atomics)
• (Optional, only if covered in tutorial) ReentrantLock / tryLock

No external concurrency frameworks (Akka, Reactor, RxJava, etc.) are allowed.

2. Project Structure

assignment4_print_spooler/
  pom.xml                              // Maven build file (Java 17)
  DESIGN.md                            // Your design rationale (submit this)
  scripts/
    run_tests.sh                       // Shortcut: compile + run JUnit tests
    run_bench.sh                       // Shortcut: compile + run benchmark
  src/
    main/java/edu/iitg/cs/concurrency/printspooler/
      api/                             // --- PROVIDED (do NOT modify) ---
        Spooler.java                   // Interface: submitBlocking, trySubmit, cancel, status, metrics, close
        PrintJob.java                  // Value class: owner, pages, pageMillis
        JobStatus.java                 // Enum: QUEUED, PRINTING, DONE, CANCELLED
        SpoolerMetrics.java            // Record: totalSubmitted, totalCompleted, totalCancelled, maxQueueDepth
      impl/                            // --- STUDENT IMPLEMENTS ---
        BoundedJobQueue.java           // TODO 1: bounded blocking queue (synchronized + wait/notifyAll)
        JobRegistry.java               // TODO 2: thread-safe job state machine
        SpoolerImpl.java               // TODO 3: dispatcher, pool, submit, cancel, close
        PrintWorker.java               // Given: page-by-page printing with cancel check
        JobRecord.java                 // Given: stores jobId, PrintJob, status, volatile cancelRequested
      runtime/
        SpoolerBench.java              // Benchmark runner (given)
    test/java/.../
      PublicSpoolerTest.java           // Public tests (must pass)

API vs impl packages

The api package defines the contract: the Spooler interface, the PrintJob value class, the JobStatus enum, and the SpoolerMetrics record. These are read-only — you never modify them. The impl package contains the working code. All classes there are package-private (final class, no public) except SpoolerImpl which is public because it implements the Spooler interface and is instantiated from the test and benchmark code.

3. How to Compile & Run

# Navigate to the project root
cd cs331_a4_170101025/assignment4_print_spooler

# Run all JUnit tests via the helper script
bash scripts/run_tests.sh

# Run the benchmark (default: 4 workers, 20 capacity, 8 producers, 50 jobs each)
bash scripts/run_bench.sh

# Or with custom arguments: workers capacity producers jobsPerProducer
bash scripts/run_bench.sh 2 10 2 10

# Run tests directly with Maven
mvn -q clean test

# Compile and run the benchmark manually
mvn -q -DskipTests package && java -cp "target/classes" edu.iitg.cs.concurrency.printspooler.runtime.SpoolerBench

# Benchmark with custom arguments
mvn -q -DskipTests package && java -cp "target/classes" edu.iitg.cs.concurrency.printspooler.runtime.SpoolerBench 2 10 2 10

Prerequisite: Java 17 (java -version) and Apache Maven (mvn -version) must be installed. On Ubuntu: sudo apt install -y openjdk-17-jdk maven.

Expected benchmark output

submitted=400 completed=400 cancelled=0 maxQueue=20
throughput=482.16 jobs/s

4. API Layer Explained

JobStatus enum

public enum JobStatus { QUEUED, PRINTING, DONE, CANCELLED }

Four possible states for every print job. A job is born QUEUED, transitions to PRINTING when a worker picks it up, then reaches a terminal state: DONE (printed successfully) or CANCELLED (cancelled by user or interrupted). Once terminal, the status never changes.

PrintJob class

public final class PrintJob {
    private final String owner;        // who submitted ("student-0")
    private final int pages;            // number of pages to print
    private final long pageMillis;      // simulated print time per page
    // constructor validates: pages > 0, pageMillis >= 0
    // accessor methods: owner(), pages(), pageMillis()
}

An immutable value class. The benchmark creates jobs with 1–5 pages and 5–15 ms per page. The pageMillis field simulates real printer latency via Thread.sleep(pageMillis) inside PrintWorker.

Spooler interface

public interface Spooler extends AutoCloseable {
    long submitBlocking(PrintJob job) throws InterruptedException;
    long trySubmit(PrintJob job, long timeoutMs) throws InterruptedException;
    boolean cancel(long jobId);
    JobStatus status(long jobId);
    SpoolerMetrics metrics();
    @Override void close() throws Exception;
}

SpoolerMetrics record

public record SpoolerMetrics(
    long totalSubmitted,    // jobs that entered the queue
    long totalCompleted,    // jobs that finished printing
    long totalCancelled,    // jobs that were cancelled
    int maxQueueDepth       // peak occupancy of the bounded queue
) {}

A Java record — immutable data carrier with auto-generated toString, equals, hashCode, and accessor methods. Used by the benchmark to print the final summary line.

5. Component 1: BoundedJobQueue

What it does

A classic bounded blocking queue of job IDs (longs). Producers block when the queue is full; the dispatcher blocks when it is empty. This is the textbook monitor pattern using synchronized + wait() + notifyAll().

Full code walkthrough

final class BoundedJobQueue {
    private final int capacity;
    private final Deque<Long> q = new ArrayDeque<>();   // underlying storage
    private int maxDepth = 0;                           // tracks peak occupancy

    BoundedJobQueue(int capacity) {
        if (capacity <= 0) throw new IllegalArgumentException("capacity must be > 0");
        this.capacity = capacity;
    }

    int maxDepthObserved() {
        synchronized (this) { return maxDepth; }         // safe read for metrics
    }

putBlocking — block until space available

    synchronized void putBlocking(long jobId) throws InterruptedException {
        while (q.size() >= capacity) wait();   // 1. WAIT while full
        q.addLast(jobId);                        // 2. Enqueue at tail
        if (q.size() > maxDepth) maxDepth = q.size();  // 3. Track peak
        notifyAll();                              // 4. Wake blocked consumers
    }

1. while, not if: After wait() returns, another thread may have filled the queue again (spurious wakeup or another producer acted first). The while re-checks the condition.
2. Adds the job ID to the back of the deque (FIFO order).
3. Updates maxDepth for the metrics snapshot.
4. notifyAll() wakes any thread blocked in takeBlocking() waiting for items.

takeBlocking — block until item available

    long takeBlocking() throws InterruptedException {
        synchronized (this) {
            while (q.isEmpty()) wait();         // block while empty
            long id = q.pollFirst();             // dequeue from head (FIFO)
            notifyAll();                          // wake blocked producers
            return id;
        }
    }

Mirror image of putBlocking. Blocks when empty, dequeues when available, wakes producers who may be waiting for space.

putWithTimeout — bounded wait with deadline

    boolean putWithTimeout(long jobId, long timeoutMs) throws InterruptedException {
        synchronized (this) {
            long deadline = System.currentTimeMillis() + timeoutMs;  // 1. absolute deadline
            while (q.size() >= capacity) {
                long remaining = deadline - System.currentTimeMillis();  // 2. how much time left?
                if (remaining <= 0) return false;                       // 3. timed out
                wait(remaining);                                          // 4. wait at most remaining ms
            }
            q.addLast(jobId);
            if (q.size() > maxDepth) maxDepth = q.size();
            notifyAll();
            return true;
        }
    }

1. Absolute deadline: Compute once at the start. This avoids the classic bug of passing a relative timeout to wait() inside a loop, which would reset the timer after every spurious wakeup.
2. After each wakeup, recalculate remaining time from the fixed deadline.
3. If the deadline has passed, give up and return false.
4. wait(remaining) sleeps for at most the remaining time. On spurious wakeup, the loop re-checks capacity.

removeIfPresent — cancel support

    boolean removeIfPresent(long jobId) {
        synchronized (this) {
            boolean removed = q.remove(jobId);   // O(n) scan and remove
            if (removed) notifyAll();             // freed a slot; wake producers
            return removed;
        }
    }

Called by SpoolerImpl.cancel(). If the job is still in the queue (not yet picked up by the dispatcher), remove it and wake any producers waiting for space.

6. Component 2: JobRegistry

What it does

A thread-safe registry that stores JobRecord objects and enforces the job state machine. Every state transition is atomic and guarded by synchronized.

The state machine

// Legal transitions:
  QUEUED  →  PRINTING  →  DONE
  QUEUED  →  CANCELLED
  PRINTING  →  CANCELLED
// Illegal: DONE → anything (terminal), CANCELLED → anything (terminal)

JobRecord (given, not a TODO)

final class JobRecord {
    final long jobId;
    final PrintJob job;
    volatile boolean cancelRequested = false;   // cross-thread visibility
    JobStatus status = JobStatus.QUEUED;            // protected by JobRegistry sync
}

cancelRequested is volatile so that when markCancelled() sets it to true, the PrintWorker running on a different thread sees the update immediately without needing to acquire the registry lock.

Full code walkthrough

final class JobRegistry {
    private final Map<Long, JobRecord> jobs = new HashMap<>();

    synchronized JobRecord create(long jobId, PrintJob job) {
        JobRecord r = new JobRecord(jobId, job);     // status = QUEUED
        jobs.put(jobId, r);
        return r;
    }

    synchronized JobRecord get(long jobId) {
        return jobs.get(jobId);                     // safe read under lock
    }

    synchronized boolean markPrinting(long jobId) {
        JobRecord r = jobs.get(jobId);
        if (r == null) return false;
        if (r.status != JobStatus.QUEUED) return false;   // already printing/done/cancelled
        if (r.cancelRequested) {                           // CANCEL RACE CHECK
            r.status = JobStatus.CANCELLED;                // cancel arrived between dequeue and print start
            return false;
        }
        r.status = JobStatus.PRINTING;
        return true;
    }

    synchronized void markDone(long jobId) {
        JobRecord r = jobs.get(jobId);
        if (r != null && r.status == JobStatus.PRINTING)
            r.status = JobStatus.DONE;                     // only PRINTING → DONE is legal
    }

    synchronized boolean markCancelled(long jobId) {
        JobRecord r = jobs.get(jobId);
        if (r == null) return false;
        if (r.status == JobStatus.DONE) return false;     // can't cancel a finished job
        r.status = JobStatus.CANCELLED;
        r.cancelRequested = true;                         // volatile write: visible to PrintWorker
        return true;
    }

    synchronized JobStatus status(long jobId) {
        JobRecord r = jobs.get(jobId);
        return r == null ? null : r.status;
    }
}

7. Component 3: SpoolerImpl

What it does

The main orchestrator. Wires together the queue, registry, a dispatcher thread, and a fixed thread pool. Implements the Spooler interface.

Full code walkthrough

public final class SpoolerImpl implements Spooler {
    private final AtomicLong idGen     = new AtomicLong(1);   // unique job ID generator
    private final AtomicLong submitted = new AtomicLong(0);   // metric counters
    private final AtomicLong completed = new AtomicLong(0);
    private final AtomicLong cancelled = new AtomicLong(0);

    private final JobRegistry registry = new JobRegistry();
    private final BoundedJobQueue queue;
    private final ExecutorService pool;
    private final Thread dispatcher;

    private volatile boolean closed = false;            // visibility flag for shutdown

Constructor — starts the dispatcher thread

    public SpoolerImpl(int capacity, int workers) {
        this.queue = new BoundedJobQueue(capacity);
        this.pool  = Executors.newFixedThreadPool(workers);

        this.dispatcher = new Thread(() -> {
            while (!closed) {
                try {
                    long jobId = queue.takeBlocking();    // blocks until job available
                    pool.submit(() -> {                    // hand to thread pool
                        new PrintWorker(jobId, registry).run();
                        JobStatus st = registry.status(jobId);
                        if (st == JobStatus.DONE) completed.incrementAndGet();
                        else if (st == JobStatus.CANCELLED) cancelled.incrementAndGet();
                    });
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();     // restore flag
                    break;                                  // exit loop on shutdown
                } catch (RuntimeException e) {
                    // swallow to keep dispatcher alive
                }
            }
        }, "spooler-dispatcher");
        this.dispatcher.start();
    }

The dispatcher is a single dedicated thread that loops forever: take a job ID from the queue, submit a PrintWorker to the pool. The pool has workers threads, so up to that many jobs print in parallel. The catch (InterruptedException) is how close() cleanly stops the dispatcher.

submitBlocking & trySubmit

    @Override
    public long submitBlocking(PrintJob job) throws InterruptedException {
        if (closed) throw new IllegalStateException("spooler closed");
        long id = idGen.getAndIncrement();      // 1. generate unique ID
        registry.create(id, job);                // 2. register (status = QUEUED)
        queue.putBlocking(id);                   // 3. enqueue (blocks if full)
        submitted.incrementAndGet();             // 4. bump metric counter
        return id;
    }

    @Override
    public long trySubmit(PrintJob job, long timeoutMs) throws InterruptedException {
        if (closed) throw new IllegalStateException("spooler closed");
        long id = idGen.getAndIncrement();
        registry.create(id, job);
        boolean ok = queue.putWithTimeout(id, timeoutMs);
        if (!ok) {
            registry.markCancelled(id);           // timed out → mark cancelled
            return -1;
        }
        submitted.incrementAndGet();
        return id;
    }

cancel

    @Override
    public boolean cancel(long jobId) {
        queue.removeIfPresent(jobId);             // 1. try to yank from queue
        boolean marked = registry.markCancelled(jobId);  // 2. set status to CANCELLED
        if (marked) cancelled.incrementAndGet();           // 3. bump metric
        return marked;
    }

Two-step cancellation: first attempt to remove from the queue (if still queued), then mark cancelled in the registry. If the job is already printing, removeIfPresent returns false (job is not in the queue), but markCancelled still sets cancelRequested = true, which the worker checks between pages.

status & metrics

    @Override
    public JobStatus status(long jobId) {
        JobStatus s = registry.status(jobId);
        return s == null ? JobStatus.CANCELLED : s;    // unknown ID → treat as cancelled
    }

    @Override
    public SpoolerMetrics metrics() {
        return new SpoolerMetrics(
            submitted.get(), completed.get(),
            cancelled.get(), queue.maxDepthObserved()
        );
    }

close — the shutdown sequence

    @Override
    public void close() throws Exception {
        closed = true;                            // 1. volatile write: reject new submits
        dispatcher.interrupt();                    // 2. unblock takeBlocking() via InterruptedException
        dispatcher.join();                         // 3. wait for dispatcher to die
        pool.shutdown();                           // 4. stop accepting new tasks
        if (!pool.awaitTermination(5, TimeUnit.SECONDS)) {
            pool.shutdownNow();                    // 5. force-stop if workers hang
        }
    }

1. Set closed = true (volatile write). Any subsequent submitBlocking call throws IllegalStateException.
2. Interrupt the dispatcher. It is blocked in queue.takeBlocking() → wait(), so the interrupt throws InterruptedException, which causes the dispatcher loop to break.
3. dispatcher.join() ensures the dispatcher has fully exited before we proceed.
4. pool.shutdown() stops accepting new tasks but lets already-submitted workers finish.
5. If workers do not finish within 5 seconds, shutdownNow() interrupts them. Workers handle InterruptedException by marking the job CANCELLED.

8. Component 4: PrintWorker

What it does

Simulates printing one job page by page. Checks for cancellation between pages and handles interruption during sleep. This class was given (not a TODO), but understanding it is critical for the viva because it shows how cancellation propagates.

Full code walkthrough

final class PrintWorker implements Runnable {
    private final long jobId;
    private final JobRegistry registry;

    PrintWorker(long jobId, JobRegistry registry) {
        this.jobId = jobId;
        this.registry = registry;
    }

    @Override
    public void run() {
        JobRecord r = registry.get(jobId);          // 1. look up the job record
        if (r == null) return;                     // shouldn't happen

        if (!registry.markPrinting(jobId)) return;  // 2. try to transition QUEUED → PRINTING
                                                     //    fails if already cancelled

        PrintJob job = r.job;
        for (int p = 1; p <= job.pages(); p++) {   // 3. page-by-page loop
            if (r.cancelRequested) {                 // 4. check volatile flag before each page
                registry.markCancelled(jobId);
                return;
            }
            try {
                Thread.sleep(job.pageMillis());       // 5. simulate printing one page
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();   // 6. restore interrupt flag
                registry.markCancelled(jobId);        //    mark cancelled on shutdown
                return;
            }
        }
        registry.markDone(jobId);                     // 7. all pages printed successfully
    }
}

1. Look up the record: The worker needs the JobRecord to read the job's page count, page time, and the cancelRequested flag.
2. Transition to PRINTING: markPrinting is atomic. If a cancel request arrived before this point, markPrinting returns false (it moves the status to CANCELLED internally) and the worker exits immediately.
3. Page loop: Iterates from page 1 to job.pages().
4. Cancel check: Reads the volatile cancelRequested flag before printing each page. This is how in-flight cancellation works — the worker discovers the flag and stops cooperatively.
5. Sleep: Simulates the time to print one page. This is what the timing tests measure.
6. InterruptedException: If shutdownNow() interrupts the worker thread during sleep, the worker marks the job cancelled and exits. It also restores the interrupt flag (Thread.currentThread().interrupt()) so that the thread pool framework knows this thread was interrupted.
7. Mark done: If the loop completes without cancellation or interruption, the job transitions PRINTING → DONE.

9. Design Decisions for Viva

10. Key Concepts for Viva