# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
`some_global_executor` is a cross-platform global executor implementation for the `some_executor` framework. It provides thread pool-based task execution that works on both standard platforms and WebAssembly (WASM) targets.
## Key Architecture
### Platform Abstraction (`src/sys/`)
- **`src/sys/stdlib.rs`**: Standard platform implementation using OS threads and `crossbeam-channel`
- **`src/sys/wasm/`**: WebAssembly implementation using web workers for parallelism
- **`src/sys/wasm/channel.rs`**: WASM-specific channel implementation for worker communication
- **`src/sys/wasm/static_executor.rs`**: Static executor for WASM environments
- Platform-specific code is abstracted through the `sys` module, which conditionally compiles based on target architecture
### Core Components
- **`Executor`**: Main executor type that manages thread pools and task scheduling
- **`SpawnedTask`**: Internal representation of spawned tasks with waker support (`src/waker.rs`)
- **`DrainNotify`**: Mechanism for tracking running tasks and notifying when all complete
- **`ExecutorDrain`**: Future that completes when all tasks finish
- **Global executor support**: Can be set as global or thread-local default executor
## Build and Development Commands
### Standard Testing
```bash
# Run all tests
cargo test
# Run a specific test
cargo test test_name
# Run tests with output
cargo test -- --nocapture
```
### WebAssembly Testing
```bash
# Run WASM tests with special flags for atomics support
CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER="wasm-bindgen-test-runner" \
RUSTFLAGS='-C target-feature=+atomics,+bulk-memory,+mutable-globals' \
cargo +nightly test --target wasm32-unknown-unknown -Z build-std=std,panic_abort
# Run specific WASM test file
CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER="wasm-bindgen-test-runner" \
RUSTFLAGS='-C target-feature=+atomics,+bulk-memory,+mutable-globals' \
cargo +nightly test --target wasm32-unknown-unknown -Z build-std=std,panic_abort --test test_static_inline
```
### Documentation
```bash
# Generate documentation with warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
# Open documentation in browser
cargo doc --open
```
### Linting and Formatting
```bash
# Run clippy for lint checks
cargo clippy
# Run clippy with all targets (including tests)
cargo clippy --all-targets
# Format code
cargo fmt
# Check formatting without making changes
cargo fmt -- --check
```
## Logging with logwise
This codebase uses the `logwise` logging framework. When using logwise:
### Basic logging
```rust
logwise::info_sync!("Here is foo: {foo}", foo=3);
```
### Complex types require privacy wrapper
```rust
logwise::warn_sync!("Here is foo: {foo}", foo=logwise::privacy::LogIt(example));
```
## Dependencies
The project uses several dependencies from crates.io:
- `logwise`: Logging framework (v0.3.0)
- `some_executor`: Core executor traits (v0.6.1)
- `atomic-waker`: Atomic waker implementation (v1.1.2)
- `test_executors`: Testing utilities (dev dependency)
- `continue`: Async coordination utilities
Platform-specific dependencies:
- **Standard platforms**: `crossbeam-channel`, `num_cpus`
- **WASM**: `wasm-bindgen`, `web-sys`, `js-sys`, `wasm_thread`, `wasm_safe_mutex`
Note: When developing locally, these dependencies may be patched to local paths in the `[patch.crates-io]` section.
## Testing Considerations
- Tests use `test_executors::async_test` macro for async test support
- WASM tests require browser environment (configured with `wasm_bindgen_test_configure!(run_in_browser)`)
- Each test should reset the logging context with `logwise::context::Context::reset("test_name".to_string())`
- Use `r#continue::continuation()` for async coordination in tests
## Thread Pool Sizing
- Standard platforms: Default thread count is `num_cpus::get()`
- WASM: Platform-specific implementation determines appropriate worker count
- Thread pools can be dynamically resized using `executor.resize(thread_count)`