Runtime Configuration - Quick Reference

What Does "Lock-Free" Mean?

With Locks (Old):

Thread 1: Lock → Do Work → Unlock
Thread 2: [WAITING...] Lock → Do Work → Unlock  ← Blocked!

One thread blocks others.

Lock-Free (New):

Thread 1: Do Work (atomic operations)
Thread 2: Do Work (atomic operations)  ← No blocking!

Multiple threads work simultaneously.

Benefits:

• No waiting - threads never block each other
• Lower overhead - eliminates mutex lock/unlock operations
• Scalable - performance improves with more cores

Integrated Optimizations

What Was Implemented

1. Lock-Free Message Pools
   • TLS pools have no mutex
   • Zero contention on hot path
   • Automatic per-thread allocation
2. Lock-Free Mailboxes
   • SPSC (Single Producer Single Consumer) atomic queue
   • 64-byte cache line padding
   • Runtime switchable
3. Runtime Configuration API
   • Control optimizations via flags
   • Auto-detect CPU features
   • Enabled by default without manual configuration

Usage

Option 1: Auto-Detect (Recommended)

#include "runtime/aether_runtime.h"

int main() {
    // One line - automatically enables best optimizations
    aether_runtime_init(0, AETHER_FLAG_AUTO_DETECT);
    
    // Your code here...
    
    aether_runtime_shutdown();
}

Example output on a modern CPU:

• Lock-free mailboxes: ENABLED
• Lock-free pools: ENABLED
• MWAIT idle: ENABLED
• AVX2 SIMD: ENABLED

Option 2: Manual Control

// Explicit flags - full control
aether_runtime_init(8,
    AETHER_FLAG_LOCKFREE_MAILBOX |  // Use lock-free mailboxes
    AETHER_FLAG_LOCKFREE_POOLS   |  // Use lock-free TLS pools
    AETHER_FLAG_ENABLE_SIMD      |  // Use AVX2 vectorization
    AETHER_FLAG_ENABLE_MWAIT);      // Use MWAIT for idle

Option 3: Compatibility Mode

// No optimizations - works on any CPU
aether_runtime_init(4, 0);  // 4 cores, no flags

Option 4: Debug/Verbose

// Print configuration on startup
aether_runtime_init(0, 
    AETHER_FLAG_AUTO_DETECT | 
    AETHER_FLAG_VERBOSE);

// Output:
// ========================================
//   Aether Runtime Configuration
// ========================================
// CPU: <detected processor>
// Active Optimizations:
//   Lock-free mailbox: ENABLED
//   Lock-free pools:   ENABLED
//   ...

Available Flags

Combine flags with bitwise OR:

int flags = AETHER_FLAG_LOCKFREE_MAILBOX | 
            AETHER_FLAG_LOCKFREE_POOLS;
aether_runtime_init(8, flags);

Performance Expectations

Performance varies by hardware and workload. Use the profiling tools to measure throughput on your target platform.

See benchmarks/cross-language for detailed measurements.

Examples

Example 1: Simple Program

Actors are produced by the Aether compiler: an actor block becomes a struct carrying a mailbox, and the runtime flags below decide which mailbox and pool implementations it uses. A C program embedding the runtime configures it and then drives compiler-generated actors, or its own structs built on the mailbox API in runtime/actors/actor_state_machine.h.

#include "runtime/aether_runtime.h"
#include "runtime/actors/actor_state_machine.h"

typedef struct Counter {
    int id;
    atomic_int active;
    Mailbox mailbox;
    int count;
} Counter;

int main() {
    // Initialize with auto-detect
    aether_runtime_init(0, AETHER_FLAG_AUTO_DETECT);

    Counter c = {0};
    mailbox_init(&c.mailbox);

    Message msg = {1, 0, 42, NULL};
    mailbox_send(&c.mailbox, msg);
    if (mailbox_receive(&c.mailbox, &msg)) {
        c.count++;
    }

    aether_runtime_shutdown();
    return 0;
}

Example 2: Query Configuration

const AetherRuntimeInitConfig* config = aether_runtime_get_config();

if (config->use_lockfree_mailbox) {
    printf("Using lock-free mailboxes!\n");
}

if (config->use_simd) {
    printf("AVX2 SIMD enabled\n");
}

Example 3: Feature Check

if (aether_runtime_has_feature(AETHER_FLAG_ENABLE_MWAIT)) {
    printf("MWAIT is enabled\n");
}

Testing

Check CPU Features

Use the verbose flag to see detected CPU features at startup:

aether_runtime_init(0, AETHER_FLAG_AUTO_DETECT | AETHER_FLAG_VERBOSE);

Run Configuration Example

Build and run the C example under runtime/examples/:

gcc -O2 -o runtime_config runtime/examples/runtime_config_example.c \
    runtime/aether_runtime.c runtime/config/aether_optimization_config.c \
    runtime/utils/aether_cpu_detect.c -Iruntime
./runtime_config

How It Works Internally

Where a message goes

Every actor carries one Mailbox (the ring buffer in runtime/actors/actor_state_machine.h). The send path in runtime/actors/aether_send_message.c picks how it gets there:

// aether_send_message(), abridged
const int my_core = current_core_id;
if (my_core >= 0 && my_core == atomic_load(&actor->assigned_core)) {
    scheduler_send_local(actor, msg);     // same core: lock-free SPSC queue
} else {
    scheduler_send_remote(actor, msg, my_core);
}

A single-actor program takes an earlier path still: main-thread mode runs step() inline on the sender's thread rather than queueing at all. The SPSC queue is allocated on first use (ensure_spsc_queue in runtime/scheduler/multicore_scheduler.c), so an actor that never receives a same-core send does not pay for one.

Message Pool Allocation

// runtime/actors/aether_message_pool.h, per-thread pool, abridged
static inline Message* message_pool_alloc(void) {
    if (!g_msg_pool) message_pool_init_thread();
    if (atomic_load_explicit(&g_msg_pool->count, memory_order_relaxed) == 0) {
        return malloc(sizeof(Message));   // pool exhausted: fall back to heap
    }
    // pop an index off the thread's free list
}

Environment Variables

Best Practices

1. Always use AETHER_FLAG_AUTO_DETECT unless you have a specific reason not to
2. Use AETHER_FLAG_VERBOSE during development to see what's enabled
3. Don't recompile for different CPUs - auto-detect handles it
4. Test on target hardware to verify optimizations are available
5. Profile first - measure actual performance gains

Cross-Platform Support

With AETHER_FLAG_AUTO_DETECT, the runtime enables the optimizations each platform supports.

Cooperative Mode

On platforms without pthreads (WASM, embedded), or when threading is explicitly disabled (-DAETHER_NO_THREADING), the cooperative scheduler handles all actor processing on a single thread. Multi-actor programs work correctly, messages are processed cooperatively during wait_for_idle().

# Force cooperative mode on native (for testing):
make stdlib EXTRA_CFLAGS="-DAETHER_NO_THREADING"
ae run examples/actors/counter.ae

# Build for WebAssembly:
make stdlib PLATFORM=wasm

Platform Capability Flags

All platform-dependent code is gated behind AETHER_HAS_* compile-time flags defined in runtime/config/aether_optimization_config.h. These are auto-detected but can be overridden:

# Disable specific features
make stdlib EXTRA_CFLAGS="-DAETHER_NO_FILESYSTEM -DAETHER_NO_NETWORKING"

# Query capabilities at runtime
AETHER_VERBOSE=1 ./program

Apple Silicon Notes:

• P-cores (Performance) detected via hw.perflevel0.physicalcpu
• E-cores (Efficiency) excluded for consistent throughput
• QoS hints encourage P-core scheduling
• Thread affinity is advisory; macOS may migrate threads

Troubleshooting

Issue: "Optimization not enabled"

Solution: Use AETHER_FLAG_VERBOSE to see why:

aether_runtime_init(0, AETHER_FLAG_AUTO_DETECT | AETHER_FLAG_VERBOSE);

Issue: "Performance not as expected"

Check:

1. CPU actually supports features (use AETHER_FLAG_VERBOSE to see detected capabilities)
2. Flags are set correctly
3. Actors created after aether_runtime_init()

Issue: "Works on development machine, not on server"

Reason: Different CPU capabilities Solution: Use AETHER_FLAG_AUTO_DETECT - it adapts automatically