# Does libCacheSim Support Concurrent or Parallel Trace Processing?

> Learn how libCacheSim handles concurrent trace processing. Discover its parallel simulation capabilities using GLib's thread pool for efficient performance analysis.

- Repository: [Juncheng Yang/libcachesim](https://github.com/1a1a11a/libcachesim)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Yes. libCacheSim executes multiple cache simulations in parallel by distributing each simulation to a separate worker thread using GLib's thread pool, with each thread operating on its own cloned trace reader.**

libCacheSim is a high-performance caching simulation library designed for batch experimentation. The library supports concurrent trace processing at the simulation level, allowing users to evaluate multiple cache algorithms, sizes, or policies simultaneously across multi-core CPUs.

## How Parallel Simulation Works in libCacheSim

The parallel execution capability is implemented in [`libCacheSim/profiler/simulator.c`](https://github.com/1a1a11a/libcachesim/blob/main/libCacheSim/profiler/simulator.c), where the simulator creates a thread pool and dispatches independent simulation tasks to worker threads.

### Thread Pool Creation

When running batch experiments, libCacheSim initializes a `GThreadPool` with a configurable number of workers. In [`simulator.c`](https://github.com/1a1a11a/libcachesim/blob/main/simulator.c), the function `g_thread_pool_new` creates a pool of `num_of_threads` workers to handle concurrent simulation tasks【/cache/repos/github.com/1a1a11a/libcachesim/develop/libCacheSim/profiler/simulator.c#L200-L207】.

### Per-Thread Execution and Trace Readers

Each worker thread executes the `_simulate` function, receiving its own **cloned trace reader** to avoid contention. This design allows every thread to walk the entire trace sequentially for its assigned cache instance without locking during I/O operations【/cache/repos/github.com/1a1a11a/libcachesim/develop/libCacheSim/profiler/simulator.c#L39-L56】.

This architecture means libCacheSim **does not split a single trace among threads** for individual cache instances. Instead, it parallelizes *multiple independent simulations* (different algorithms, sizes, or admission policies) over the same trace file.

### Thread-Safe Progress Coordination

To report overall progress while workers run independently, libCacheSim uses a `GMutex` to protect a shared progress counter. The mutex ensures atomic updates when threads complete their simulation segments【/cache/repos/github.com/1a1a11a/libcachesim/develop/libCacheSim/profiler/simulator.c#L30-L33】【/cache/repos/github.com/1a1a11a/libcachesim/develop/libCacheSim/profiler/simulator.c#L34-L38】.

## Enabling Concurrent Execution via Command Line

The `cachesim` CLI exposes parallel execution through the `--num-thread` option, advertised as **"automatic multi-threaded simulations"** in the documentation【/cache/repos/github.com/1a1a11a/libcachesim/develop/doc/quickstart_cachesim.md#L7-L8】.

Run multiple algorithms concurrently:

```bash

# Run four different eviction algorithms on the same trace

# Each algorithm gets its own thread (default: CPU core count)

./cachesim data/trace.vscsi vscsi fifo,lru,arc,qdlp 0.01 --ignore-obj-size=1

```

Limit parallelism explicitly:

```bash

# Limit to 2 concurrent threads

./cachesim data/trace.vscsi vscsi fifo,lru,arc,qdlp 0.01 \
    --ignore-obj-size=1 --num-thread=2

```

Run multiple cache sizes with controlled concurrency:

```bash

# Run 4 cache sizes for each of 4 algorithms, max 6 concurrent simulations

./cachesim data/trace.vscsi vscsi fifo,lru,arc,qdlp \
    1mb,16mb,256mb,8gb --ignore-obj-size=1 --num-thread=6

```

In each case, the underlying C code spawns a `GThreadPool` via `simulate_at_multi_sizes` in [`simulator.c`](https://github.com/1a1a11a/libcachesim/blob/main/simulator.c), distributing the workload across the specified number of threads.

## Key Implementation Files

- **[`libCacheSim/profiler/simulator.c`](https://github.com/1a1a11a/libcachesim/blob/main/libCacheSim/profiler/simulator.c)** – Core multi-threaded simulation engine. Implements thread pool creation, reader cloning, and the `_simulate` worker function.
- **[`libCacheSim/bin/cachesim/main.c`](https://github.com/1a1a11a/libcachesim/blob/main/libCacheSim/bin/cachesim/main.c)** – CLI entry point that parses `--num-thread` and forwards the parameter to the simulator.
- **[`libCacheSim/utils/mysys.c`](https://github.com/1a1a11a/libcachesim/blob/main/libCacheSim/utils/mysys.c)** – Provides low-level thread-affinity helpers using POSIX `pthread` APIs.
- **[`doc/quickstart_cachesim.md`](https://github.com/1a1a11a/libcachesim/blob/main/doc/quickstart_cachesim.md)** – User documentation covering the automatic multi-threading feature and `--num-thread` usage【/cache/repos/github.com/1a1a11a/libcachesim/develop/doc/quickstart_cachesim.md#L66-L69】.

## Summary

- libCacheSim supports **parallel trace processing** at the simulation level, not at the single-cache level.
- The implementation uses **GLib's `GThreadPool`** to distribute multiple independent simulations across worker threads.
- Each thread operates on a **cloned trace reader**, eliminating I/O contention and simplifying synchronization.
- A **`GMutex`** protects the shared progress counter for thread-safe status reporting.
- Users control concurrency via the **`--num-thread`** command-line option in the `cachesim` CLI.

## Frequently Asked Questions

### Does libCacheSim parallelize a single cache simulation across multiple threads?

No. libCacheSim assigns each cache configuration (algorithm, size, or policy) to a single thread. A single cache simulation runs sequentially on one thread, but multiple simulations run concurrently across the thread pool. This design maintains simple trace-reading logic while maximizing CPU utilization for batch experiments.

### How does libCacheSim handle trace file access in multi-threaded mode?

Each worker thread receives its own cloned trace reader instance before execution begins. This approach prevents file pointer contention and eliminates the need for locks during trace parsing, as each thread independently traverses the trace from start to finish.

### What is the default number of threads used by libCacheSim?

By default, libCacheSim uses the number of CPU cores available on the system. Users can override this with the `--num-thread` flag to limit resource consumption or match specific hardware constraints.

### Is there any performance overhead when running parallel simulations?

The primary overhead comes from cloning trace readers for each thread and the mutex contention on the progress counter. However, because each thread performs independent computation on identical trace data, the speedup scales linearly with the number of concurrent simulations up to the CPU core count.