Update documentation and comments to use relative timing values

Co-authored-by: max-lt <9805205+max-lt@users.noreply.github.com>

Author: Copilot

README.md

@@ -5,7 +5,7 @@ V8-based JavaScript runtime for serverless workers, built on [rusty_v8](https://
 ## Quick Start
 
 ```rust
-use openworkers_runtime_v8::{init_pool, execute_pooled, RuntimeLimits, Script, Task};
+use openworkers_runtime_v8::{init_pool, execute_pooled, RuntimeLimits, Script, Event};
 
 // Initialize pool once at startup
 init_pool(1000, RuntimeLimits::default());
@@ -17,12 +17,12 @@ let script = Script::new(r#"
     });
 "#);
 
-execute_pooled("worker-id", script, ops, task).await?;
+execute_pooled("worker-id", script, ops, event).await?;
 ```
 
 ## Features
 
-- **Isolate pooling** — <10µs warm start, ~100µs cold start
+- **Isolate pooling** — Fast warm start (~µs), cold start with snapshot (~µs)
 - **Streaming** — ReadableStream with backpressure
 - **Web APIs** — fetch, setTimeout, Response, Request, URL, console
 - **Async/await** — Full Promise support
@@ -31,8 +31,8 @@ execute_pooled("worker-id", script, ops, task).await?;
 
 | Mode        | Cold Start | Warm Start |
 | ----------- | ---------- | ---------- |
-| IsolatePool | ~100µs     | <10µs      |
-| Worker      | ~2-3ms     | ~2-3ms     |
+| IsolatePool | ~µs        | Fastest    |
+| Worker      | ~ms        | ~ms        |
 
 ## Documentation
 

docs/architecture.md

@@ -24,17 +24,17 @@ platform.rs                 ← V8 Platform (singleton, once per process)
 | **Runtime**              | `runtime/mod.rs`            | V8 isolate + context + channels | New isolate       |
 | **Worker**               | `worker.rs`                 | High-level API around Runtime   | New isolate/req   |
 | **SharedIsolate**        | `shared_isolate.rs`         | Thread-local reusable isolate   | Once/thread       |
-| **ExecutionContext**     | `execution_context.rs`      | Disposable context              | ~100µs            |
+| **ExecutionContext**     | `execution_context.rs`      | Disposable context              | Fast (~µs)        |
 | **LockerManagedIsolate** | `locker_managed_isolate.rs` | Pool-compatible isolate         | Once/worker       |
 | **IsolatePool**          | `isolate_pool.rs`           | Global LRU cache                | Manages lifecycle |
 
 ## Execution Modes
 
-| Mode              | API                | Performance | Use Case             |
-| ----------------- | ------------------ | ----------- | -------------------- |
-| **Legacy**        | `Worker::new()`    | ~700µs/req  | Max isolation, tests |
-| **Shared Pool**   | `execute_pooled()` | ~200µs/req  | Single-thread        |
-| **Thread-Pinned** | `execute_pinned()` | ~170µs/req  | **Production**       |
+| Mode              | API                | Performance    | Use Case             |
+| ----------------- | ------------------ | -------------- | -------------------- |
+| **Legacy**        | `Worker::new()`    | Slow (~ms/req) | Max isolation, tests |
+| **Shared Pool**   | `execute_pooled()` | Fast (~µs/req) | Single-thread        |
+| **Thread-Pinned** | `execute_pinned()` | Fastest        | **Production**       |
 
 See [execution_modes.md](./execution_modes.md) for details.
 
@@ -75,6 +75,7 @@ pub trait EventLoopRuntime {
     fn pump_and_checkpoint(&mut self);
 }
 
+// Implemented by Runtime and ExecutionContext
 // Used by Worker, ExecutionContext, WorkerFuture
 drain_and_process(cx, runtime, buffer) -> Result<()>
 ```
@@ -132,15 +133,15 @@ Used by: Runtime          Used by: IsolatePool
 
 ## Key Files
 
-| File                   | Lines | Purpose                       |
-| ---------------------- | ----- | ----------------------------- |
-| `runtime/mod.rs`       | ~800  | V8 setup, callback processing |
-| `runtime/bindings.rs`  | ~600  | JS native functions           |
-| `worker.rs`            | ~700  | Worker API, event loop        |
-| `execution_context.rs` | ~500  | Pooled execution context      |
-| `isolate_pool.rs`      | ~300  | LRU cache, v8::Locker         |
-| `event_loop.rs`        | ~80   | Shared polling logic          |
-| `platform.rs`          | ~20   | V8 platform singleton         |
+| File                    | Lines  | Purpose                       |
+| ----------------------- | ------ | ----------------------------- |
+| `runtime/mod.rs`        | ~700   | V8 setup, callback processing |
+| `runtime/bindings/`     | ~2500  | JS native functions (folder)  |
+| `worker.rs`             | ~1700  | Worker API, event loop        |
+| `execution_context.rs`  | ~1300  | Pooled execution context      |
+| `isolate_pool.rs`       | ~450   | LRU cache, v8::Locker         |
+| `event_loop.rs`         | ~80    | Shared polling logic          |
+| `platform.rs`           | ~80    | V8 platform singleton         |
 
 ## See Also
 

docs/execution_modes.md

@@ -4,11 +4,11 @@ Three ways to run JavaScript in the V8 runtime.
 
 ## Comparison
 
-| Mode              | Cold Start | Warm Start | Thread Model             | Use Case       |
-| ----------------- | ---------- | ---------- | ------------------------ | -------------- |
-| **IsolatePool**   | ~100µs     | <10µs      | Multi-thread, v8::Locker | **Production** |
-| **Worker**        | ~2-3ms     | ~2-3ms     | Single, per-request      | Max isolation  |
-| **SharedIsolate** | ~100µs     | ~100µs     | Thread-local             | Legacy         |
+| Mode              | Cold Start    | Warm Start | Thread Model             | Use Case       |
+| ----------------- | ------------- | ---------- | ------------------------ | -------------- |
+| **IsolatePool**   | ~µs           | Fastest    | Multi-thread, v8::Locker | **Production** |
+| **Worker**        | ~ms           | ~ms        | Single, per-request      | Max isolation  |
+| **SharedIsolate** | ~µs           | ~µs        | Thread-local             | Legacy         |
 
 ## IsolatePool (Recommended)
 
@@ -21,7 +21,7 @@ use openworkers_runtime_v8::{init_pool, execute_pooled};
 init_pool(1000, RuntimeLimits::default());
 
 // Per request
-execute_pooled("worker-id", script, ops, task).await?;
+execute_pooled("worker-id", script, ops, event).await?;
 ```
 
 **How it works:**
@@ -33,8 +33,8 @@ execute_pooled("worker-id", script, ops, task).await?;
 
 **Cache behavior:**
 
-- Hit → reuse existing isolate (<10µs)
-- Miss → create new (~100µs with snapshot)
+- Hit → reuse existing isolate (fastest)
+- Miss → create new (~µs with snapshot, ~ms without)
 - Full → evict LRU, create new
 
 See [isolate_pool.md](./isolate_pool.md) for implementation details.
@@ -102,11 +102,11 @@ execute_pinned("owner-id", script, ops, task).await?;
 
 ### Benchmark Comparison
 
-| Scenario       | Shared Pool | Thread-Pinned     |
-| -------------- | ----------- | ----------------- |
-| Warm cache     | 0.64ms      | **0.48ms** (+34%) |
-| CPU-bound      | 1.73ms      | 1.80ms            |
-| With I/O (5ms) | 7.95ms      | 7.92ms            |
+| Scenario       | Shared Pool | Thread-Pinned |
+| -------------- | ----------- | ------------- |
+| Warm cache     | Fast        | **Faster**    |
+| CPU-bound      | Similar     | Similar       |
+| With I/O       | Similar     | Similar       |
 
 Under high contention (many threads, few isolates), shared pool can degrade to **worse than no pooling**. Thread-pinned avoids this.
 

docs/isolate_pool.md

@@ -59,6 +59,9 @@ pub struct LockerManagedIsolate {
     pub platform: &'static v8::SharedRef<v8::Platform>,
     pub limits: RuntimeLimits,
     pub memory_limit_hit: Arc<AtomicBool>,
+    pub use_snapshot: bool,
+    pub deferred_destruction_queue: Arc<DeferredDestructionQueue>,
+    // ... heap limit state
 }
 ```
 
@@ -130,11 +133,11 @@ pub async fn with_lock_async<F, Fut, R>(&self, f: F) -> R {
 
 ## Performance
 
-| Operation                  | Time   |
-| -------------------------- | ------ |
-| Cache hit + lock           | <10µs  |
-| Cache miss (with snapshot) | ~100µs |
-| Cache miss (no snapshot)   | ~2-3ms |
+| Operation                  | Time           |
+| -------------------------- | -------------- |
+| Cache hit + lock           | Fastest (~µs)  |
+| Cache miss (with snapshot) | Fast (~µs)     |
+| Cache miss (no snapshot)   | Slower (~ms)   |
 
 ### Contention Scenarios
 

docs/streams.md

@@ -33,9 +33,11 @@ Rust ↔ JavaScript streaming bridge for efficient data transfer without full bu
 
 ```rust
 pub struct StreamManager {
-    senders: Arc<Mutex<HashMap<StreamId, UnboundedSender<StreamChunk>>>>,
-    receivers: Arc<Mutex<HashMap<StreamId, UnboundedReceiver<StreamChunk>>>>,
+    senders: Arc<Mutex<HashMap<StreamId, Sender<StreamChunk>>>>,
+    receivers: Arc<Mutex<HashMap<StreamId, Receiver<StreamChunk>>>>,
+    metadata: Arc<Mutex<HashMap<StreamId, String>>>,
     next_id: Arc<Mutex<StreamId>>,
+    high_water_mark: usize,  // Channel capacity for backpressure
 }
 
 pub enum StreamChunk {
@@ -139,7 +141,7 @@ while (true) {
 ## Thread Safety
 
 - `StreamManager` is `Clone` + `Send` via `Arc<Mutex<...>>`
-- Channels are thread-safe (`mpsc::unbounded`)
+- Channels are thread-safe (`mpsc::channel` with bounded capacity)
 - One reader per stream (WHATWG spec)
 
 ## Memory

src/execution_context.rs

@@ -4,7 +4,7 @@
 //! a fresh V8 Context within an existing SharedIsolate, providing complete
 //! isolation from other executions.
 //!
-//! The context is cheap to create (~100µs) compared to an isolate (~3-5ms).
+//! The context is cheap to create (~µs) compared to an isolate (~ms without snapshot).
 
 use std::cell::RefCell;
 use std::collections::HashMap;
@@ -228,7 +228,7 @@ impl ExecutionContext {
 
     /// Create a new execution context within a shared isolate
     ///
-    /// This is relatively cheap (~100µs) compared to creating an isolate.
+    /// This is relatively cheap (~µs) compared to creating an isolate.
     ///
     /// # Safety
     /// The SharedIsolate must remain valid for the lifetime of this ExecutionContext.

src/lib.rs

@@ -15,10 +15,10 @@
 //! init_pool(1000, limits);
 //!
 //! // Execute worker (handles everything internally)
-//! execute_pooled("worker-id", script, ops, task).await?;
+//! execute_pooled("worker-id", script, ops, event).await?;
 //! ```
 //!
-//! Performance: <10µs warm start, ~100µs cold start (with snapshot)
+//! Performance: Fast warm start (~µs), cold start with snapshot (~µs)
 //!
 //! ### Worker (Maximum Isolation)
 //!
@@ -28,10 +28,10 @@
 //! use openworkers_runtime_v8::Worker;
 //!
 //! let mut worker = Worker::new_with_ops(script, limits, ops).await?;
-//! worker.exec(task).await?;
+//! worker.exec(event).await?;
 //! ```
 //!
-//! Performance: ~2-3ms per request (creates new isolate)
+//! Performance: Slower (~ms per request, creates new isolate)
 
 pub mod event_loop;
 pub mod execution_context;

src/locker_managed_isolate.rs

@@ -41,7 +41,7 @@ pub struct LockerManagedIsolate {
 impl LockerManagedIsolate {
     /// Create a new locker-managed isolate
     ///
-    /// This is expensive (~3-5ms without snapshot, ~100µs with snapshot)
+    /// This is expensive (~ms without snapshot, ~µs with snapshot)
     /// and should be done lazily by the pool, not per-request.
     pub fn new(limits: RuntimeLimits) -> Self {
         // Get global V8 platform (initialized once, shared across all modules)

src/pooled_execution.rs

@@ -23,8 +23,8 @@ use openworkers_core::{Event, OperationsHandle, Script, TerminationReason};
 /// * `task` - Task to execute (HTTP request, scheduled event, etc.)
 ///
 /// # Performance
-/// - Cache hit: <10µs (isolate reused from pool)
-/// - Cache miss: ~100µs (with snapshot) or ~3-5ms (without)
+/// - Cache hit: Fastest (~µs, isolate reused from pool)
+/// - Cache miss: Fast with snapshot (~µs), slower without (~ms)
 /// - Same worker_id always reuses the same isolate (warm cache)
 ///
 /// # Example

src/shared_isolate.rs

@@ -25,8 +25,8 @@ pub struct SharedIsolate {
 impl SharedIsolate {
     /// Create a new shared isolate
     ///
-    /// This is expensive (~3-5ms) and should be done once at startup,
-    /// not per-request.
+    /// This is expensive (~ms without snapshot, ~µs with snapshot)
+    /// and should be done once at startup, not per-request.
     pub fn new(limits: RuntimeLimits) -> Self {
         // Get global V8 platform (initialized once, shared across all modules)
         let platform = crate::platform::get_platform();