Quasar Fibers vs Platform Threads: A JVM Concurrency Decision Guide

Decision: use Quasar fibers when platform threads are too expensive

Your service must handle tens of thousands of concurrent tasks or connections on the JVM. Mapping each task to a platform thread consumes a fixed stack—commonly around one megabyte—and forces the operating system to context-switch between them. At high volume, heap and CPU spend more on thread bookkeeping than on your business logic.

Useful takeaway: Quasar fibers multiplex many lightweight tasks onto a small pool of JVM threads. A fiber suspends at a blocking point and resumes later without holding an OS thread. The cost is bytecode instrumentation through a Java agent, which can conflict with security managers and makes stack traces harder to read. Choose Quasar when you cannot use JDK virtual threads and thread-per-task will not scale.

Constraints to check first

• JVM release: Quasar targets Java 8 and later; confirm your runtime version.
• Agent permissions: the application must be allowed to run a Java agent and modify bytecode.
• Security policy: some application servers and security managers block agent attachment.
• Team readiness: debugging fiber stacks requires different tools than standard thread dumps.

Supported options compared

Option	Concurrency model	Instrumentation	Best suited for	Main caveat
Quasar fibers	Thousands of fibers multiplexed on fewer JVM threads	Java agent / bytecode manipulation	Older JVMs needing high concurrency without virtual threads	Agent setup; non-standard call stacks
JDK virtual threads	Lightweight threads scheduled by the JVM	None, built into JDK 21 and later	New applications on recent LTS releases	Not available on Java 8–17
Platform threads	One OS thread per task	None	Low concurrency or blocking legacy code	Memory and context-switch cost at scale

Trade-offs

Memory and throughput

Fibers use much less memory per concurrent task than platform threads because they do not reserve a full OS stack. The scheduler adds a small coordination cost, so fibers are not automatically faster for CPU-bound work with few tasks.

Blocking operations

Quasar documentation describes blocking calls inside a fiber as transparently converted to non-blocking operations so the underlying JVM thread can run other fibers. Treat this as library behavior to verify in your environment, not a guarantee for every I/O library.

Mailbox safety

Mailbox-based actors encapsulate state and pass messages instead of sharing mutable memory. An unbounded mailbox can still grow without limit under backpressure, risking memory exhaustion. Bound the mailbox or apply backpressure.

Observability

Standard thread dumps show JVM threads, not individual fibers. Suspension points break the expected call stack, so stack-based profilers and debuggers may show incomplete or confusing frames.

Implementation pattern: fiber-backed actor

This example is structural. Method names and package paths depend on the Quasar version; verify against your release before copying into production.

<dependency>
  <groupId>co.paralleluniverse</groupId>
  <artifactId>quasar-core</artifactId>
  <version>{quasar.version}</version>
</dependency>

Start the JVM with the Quasar agent. Replace the placeholder path with the actual agent jar for your JDK:

java -javaagent:/path/to/quasar-core-{quasar.version}-jdk8.jar -jar app.jar

A minimal actor receives messages from a channel and processes them one at a time:

import co.paralleluniverse.fibers.Fiber;
import co.paralleluniverse.strands.channels.Channel;

public class MailboxActor {
    private final Channel<String> mailbox = new Channel<>(1024);

    public void start() {
        new Fiber<Void>(() -> {
            for (String message : mailbox) {
                process(message);
            }
            return null;
        }).start();
    }

    public void send(String message) {
        mailbox.send(message);
    }

    private void process(String message) {
        // Business logic here. Avoid blocking calls unless the runtime
        // can suspend the fiber safely.
    }
}

Run the actor from a main method or framework integration point. The channel capacity of 1024 is a placeholder; choose a bound based on your expected backpressure.

Diagnostic check

1. Start the application under load.
2. Find the JVM process ID, for example with jps or ps.
3. Run jstack <pid> and count platform threads. The number should remain close to your configured thread pool, not the number of concurrent fibers.
4. Optionally run ps -o threads -p <pid> to confirm OS thread count stays flat as fiber count rises.

Required permissions: read access to the target process for jstack; typically the same user that owns the JVM process. Risk: thread dumps on a heavily loaded production JVM can briefly pause or slow the application.

Limitations

• Quasar is external to the JDK, so you own dependency updates and compatibility testing.
• Bytecode agents may fail under security managers or restricted application servers.
• Debugging is harder because fiber stacks are not standard JVM thread stacks.
• Unbounded actor mailboxes can exhaust memory under sustained load.

Practical verification (run before production)

1. Add the Quasar dependency and agent argument to a staging service.
2. Launch more than 10,000 concurrent fiber tasks and confirm the application starts without OutOfMemoryError from thread stacks.
3. Capture jstack output and verify platform thread count does not scale linearly with task count.
4. Exercise a blocking I/O call inside a fiber and confirm other fibers continue running.

These steps are unverified claims from the planning brief; execute them in staging and adjust for your Quasar version.

Rollback

Because adding a dependency and JVM agent changes build and startup state, revert by removing the Quasar dependency, removing the -javaagent argument, and restarting the application on platform threads or virtual threads.