libCacheSim Node.js Bindings

Node.js bindings for libCacheSim - A high-performance cache simulator and analysis library supporting LRU, FIFO, S3-FIFO, Sieve and other caching algorithms.

Features

• High Performance: Built on the optimized libCacheSim C library
• Multiple Algorithms: Support for LRU, FIFO, LFU, ARC, Clock, S3-FIFO, Sieve, and more
• Various Trace Types: Support for vscsi, csv, txt, binary, and oracle trace formats
• Pre-compiled Binaries: Fast installation with no build tools required
• Cross-platform: Support for Linux (x64) and macOS (x64, ARM64)

Installation

npm install libcachesim-node

The package includes pre-compiled binaries for supported platforms. No additional build tools or dependencies are required for end users.

Supported Platforms

• Linux: x64 (Ubuntu 18.04+, other distributions with compatible glibc)
• macOS: x64 (Intel) and ARM64 (Apple Silicon)

If pre-compiled binaries are not available for your platform, please check the releases page for updates or submit an issue.

Quick Start

const { runSimulation, getSupportedAlgorithms } = require('libcachesim-node');

// Get supported algorithms
console.log('Supported algorithms:', getSupportedAlgorithms());

// Run a cache simulation
const result = runSimulation(
  '/path/to/trace.vscsi',  // Path to trace file
  'vscsi',                 // Trace type
  's3fifo',                // Cache algorithm
  '1mb'                    // Cache size
);

console.log('Simulation results:', result);

API Reference

getVersion()

Get the version of the libCacheSim Node.js binding.

Returns: String containing the version number (e.g., "1.0.1")

runSimulation(tracePath, traceType, algorithm, cacheSize)

Run a cache simulation with specified parameters.

Parameters:

• tracePath (string): Path to the trace file
• traceType (string): Type of trace file ('vscsi', 'csv', 'txt', 'binary', 'oracle')
• algorithm (string): Cache replacement algorithm
• cacheSize (string): Cache size (e.g., '1mb', '512kb', '2gb')

Returns: Object containing simulation results including hit rate, miss count, etc.

getSupportedAlgorithms()

Get a list of supported cache algorithms.

Returns: Array of algorithm names

getSupportedTraceTypes()

Get a list of supported trace file types.

Returns: Array of trace type names

Cache Algorithms

The following cache replacement algorithms are supported:

• LRU (Least Recently Used)
• FIFO (First In, First Out)
• LFU (Least Frequently Used)
• ARC (Adaptive Replacement Cache)
• Clock (Clock/Second Chance)
• S3-FIFO (Simple, Scalable, Scan-resistant FIFO)
• Sieve (Eviction algorithm with lazy promotion)

Trace File Formats

• vscsi: VMware vSCSI trace format
• csv: Comma-separated values format
• txt: Plain text format
• binary: Binary trace format
• oracle: Oracle optimal algorithm simulation

Command Line Interface

The package includes a command-line interface:

# Install globally for CLI access
npm install -g libcachesim-node

# Run simulation from command line
cachesim-js --trace /path/to/trace.vscsi --algorithm s3fifo --size 1mb

# Check version
cachesim-js --version

Development

Building from Source

If you need to build from source or contribute to development:

# Clone the repository
git clone https://github.com/1a1a11a/libCacheSim.git
cd libCacheSim/libCacheSim-node

# Install dependencies
npm install

# Build from source (requires cmake, build tools)
npm run build-from-source

# Run tests
npm test

Requirements for Building from Source

• Node.js 14+
• CMake 3.10+
• C/C++ compiler (GCC, Clang, or MSVC)
• System dependencies:
  • Linux: build-essential cmake libglib2.0-dev libzstd-dev
  • macOS: cmake glib zstd (via Homebrew)

Version Synchronization

The Node.js binding version is automatically synchronized with the main libCacheSim project version. To manually sync versions, run:

python3 scripts/sync_node_version.py

This ensures that the Node.js binding version in package.json matches the version in the main project's version.txt file.

Architecture

This package uses prebuild-install for binary distribution:

1. Pre-compiled Binaries: Automatically downloaded from GitHub releases during installation
2. Automated Building: GitHub Actions automatically builds binaries for all supported platforms
3. Standard Tooling: Uses industry-standard prebuild and prebuild-install packages

Troubleshooting

Installation Issues

If installation fails, try the following:

# Clear npm cache
npm cache clean --force

# Reinstall with verbose logging
npm install libcachesim-node --verbose

# Force source compilation
npm install libcachesim-node --build-from-source

Binary Loading Issues

If you see binary loading errors:

1. Ensure your platform is supported
2. Check that the prebuilds directory exists and contains your platform's binary
3. Try reinstalling the package
4. Check Node.js version compatibility (requires Node.js 14+)

Build from Source Issues

If source compilation fails:

1. Install required system dependencies (including ninja-build)
2. Ensure CMake 3.10+ is available
3. Check that libCacheSim builds successfully: cd .. && mkdir _build && cd _build && cmake -G Ninja .. && ninja

Contributing

Contributions are welcome! Please see the main libCacheSim repository for contribution guidelines.

License

MIT License - see the LICENSE file for details.

Related Projects

• libCacheSim - The core C library
• libCacheSim Python bindings - Python interface

Citation

If you use libCacheSim in your research, please cite:

@misc{libcachesim,
  title={libCacheSim: A High-Performance Cache Simulator},
  author={Tian, Murphy and others},
  year={2023},
  url={https://github.com/1a1a11a/libCacheSim}
}