# Performance Tuning Guide for JVMRS

This guide provides practical advice for optimizing JVMRS performance in different scenarios.

## Table of Contents

- [JIT Compilation](#jit-compilation)
- [Memory Management](#memory-management)
- [Class Loading](#class-loading)
- [Inline Caching](#inline-caching)
- [Garbage Collection](#garbage-collection)
- [Platform-Specific Optimizations](#platform-specific-optimizations)
- [Benchmarking](#benchmarking)

## JIT Compilation

### Tiered Compilation

JVMRS uses a tiered compilation strategy:
1. **Interpreter** - Cold code execution
2. **Baseline JIT** - After threshold invocations (default: 100)
3. **Optimized JIT** - Hot methods with advanced optimizations

### Configuration

```rust
use jvmrs::jit::TieredCompilationConfig;

let config = TieredCompilationConfig {
    baseline_threshold: 100,    // Method invocations before baseline JIT
    optimized_threshold: 1000,   // Method invocations before optimized JIT
    ..Default::default()
};
```

### Best Practices

- **Lower thresholds for short-lived applications** (CLI tools, lambda functions)
- **Higher thresholds for long-running applications** (server applications)
- **Monitor JIT compilation time** using the profiler

```bash
# Adjust JIT threshold at runtime
cargo run -- --jit-threshold 50 YourClass
```

## Memory Management

### Arena-Based Allocation

JVMRS uses arena allocators for improved cache locality:

```rust
use jvmrs::allocator::ArenaAllocator;

let arena = ArenaAllocator::new(1024 * 1024); // 1MB arena
```

### Memory Pooling

- Reuse objects when possible to reduce allocation pressure
- Use object pools for frequently allocated objects
- Consider using value types instead of reference types for small objects

### Stack vs Heap Allocation

Prefer stack allocation for short-lived objects:
- Local variables are stack-allocated in the JVM
- Arrays are always heap-allocated
- Objects are heap-allocated

## Class Loading

### Binary Cache Format (.jvmc)

JVMRS caches parsed classes in a binary format for fast loading:

```bash
# Enable class caching (default)
JVMRS_USE_CACHE=1 cargo run MyClass

# Disable class caching
JVMRS_USE_CACHE=0 cargo run MyClass
```

### Classpath Optimization

- Order classpath from most to least frequently used
- Avoid duplicate class entries
- Use explicit classpath instead of wildcard when possible

```bash
# Optimal classpath order
cargo run -- --classpath lib/common:lib/app:lib/utils MyClass
```

## Inline Caching

### Virtual Method Calls

JVMRS uses inline caching to optimize virtual method calls:

- **Monomorphic callsites**: One receiver type (fastest)
- **Polymorphic callsites**: Few receiver types (moderately fast)
- **Megamorphic callsites**: Many receiver types (fallback to regular dispatch)

### Cache Configuration

Inline caching is enabled by default. To disable:

```rust
use jvmrs::inline_cache::InlineCacheManager;

let manager = InlineCacheManager::new(false); // Disable caching
```

### Cache Statistics

Monitor cache effectiveness:

```rust
let stats = interpreter.get_inline_cache_stats();
for (site, cache_stats) in stats {
    println!("Call site: {:?}", site);
    println!("  Hit rate: {:.2}%", cache_stats.hit_rate);
}
```

## Garbage Collection

### Generational GC

JVMRS uses a generational garbage collector:

- **Young Generation**: Newly allocated objects (frequent GC)
- **Old Generation**: Long-lived objects (infrequent GC)

### GC Tuning

Adjust generation sizes for your workload:

```rust
use jvmrs::gc::GenerationalHeap;

let heap = GenerationalHeap::new(
    16 * 1024 * 1024,  // Young generation: 16MB
    64 * 1024 * 1024,  // Old generation: 64MB
);
```

### Parallel GC Sweep

Enable parallel GC sweep for multi-core systems (default: enabled):

```rust
let heap = GenerationalHeap::with_parallel_sweep(young_size, old_size, true);
```

### Monitoring GC

```rust
use jvmrs::profiler::Profiler;

let profiler = Profiler::new();
interpreter.set_profiler(Some(profiler));

// Run your application
interpreter.run_main("MyClass")?;

// Get GC statistics
let gc_stats = profiler.get_gc_stats();
println!("GC pauses: {} ({}ms total)", gc_stats.count, gc_stats.total_pause_ms);
```

## Platform-Specific Optimizations

### SIMD Operations

Enable SIMD for array operations:

```toml
[dependencies]
jvmrs = { version = "0.1", features = ["simd"] }
```

```rust
use jvmrs::simd::heap_array_copy_int;

// Zero-copy SIMD-accelerated array copy
heap_array_copy_int(&mut memory.heap, src_addr, dst_addr, length);
```

### WebAssembly (WASM)

For browser or edge deployment:

```bash
# Build WASM backend
cargo build --features wasm

# Emit WASM
cargo run --features wasm -- --wasm-output output.wasm MyClass
```

### Embedded Systems

For resource-constrained environments:

```bash
# Build no_std version
cargo build --features no_std --target thumbv7em-none-eabihf
```

## Benchmarking

### Built-in Benchmarks

JVMRS includes benchmark suites:

```bash
# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench --bench instruction_benchmarks
```

### Custom Benchmarks

Create custom benchmarks using `criterion`:

```rust
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn benchmark_method_invocation(c: &mut Criterion) {
    c.bench_function("invokevirtual", |b| {
        let mut interpreter = Interpreter::new();
        b.iter(|| {
            black_box(interpreter.run_main("BenchmarkClass"))
        });
    });
}

criterion_group!(benches, benchmark_method_invocation);
criterion_main!(benches);
```

### Profiling

Use the built-in profiler:

```rust
use jvmrs::profiler::Profiler;

let profiler = Profiler::new();
let mut interpreter = Interpreter::new();
interpreter.set_profiler(Some(profiler));

// Run workload
interpreter.run_main("MyWorkload")?;

// Generate flame graph
profiler.generate_flame_graph("flamegraph.svg")?;

// Get hot methods
let hot_methods = profiler.get_hot_methods(10);
for (method, time) in hot_methods {
    println!("{}: {}ms", method, time);
}
```

## Advanced Optimizations

### Escape Analysis

Enable escape analysis for stack allocation (experimental):

```rust
let config = TieredCompilationConfig {
    escape_analysis_enabled: true,
    ..Default::default()
};
```

### Method Inlining

Configure inlining behavior:

```rust
let config = TieredCompilationConfig {
    inline_max_size: 35,  // Max method size to inline (bytes)
    inline_max_depth: 9,  // Max inlining depth
    ..Default::default()
};
```

### Loop Optimization

Enable loop optimizations:

```rust
let config = TieredCompilationConfig {
    loop_unrolling: true,
    loop_vectorization: true,
    ..Default::default()
};
```

## Troubleshooting

### High Memory Usage

- Enable GC logging: `JVMRS_LOG_GC=1`
- Increase heap size: adjust generation sizes
- Check for memory leaks: use heap dump

- Slow Method Dispatch

- Check inline cache hit rate
- Increase cache size if needed
- Profile to identify megamorphic callsites

### Long GC Pauses

- Increase young generation size
- Enable parallel GC sweep
- Consider using concurrent GC (when available)

### Slow Startup

- Disable JIT for short-lived apps: `--no-jit`
- Increase JIT threshold: `--jit-threshold 500`
- Use AOT compilation for frequently used code

## References

- [Architecture Documentation](ARCHITECTURE.md)
- [Competitive Differentiation](docs/competitive-differentiation.md)
- [Developer Experience Guide](docs/developer-experience.md)
- [WASI and Deployment](docs/wasi-and-deployment.md)
