Memory Pressure API
Relevant source files
The following files were used as context for generating this wiki page:
The Memory Pressure API provides visibility into WebAssembly (WASM) heap usage within EdgeVec, enabling applications to implement graceful degradation when memory is constrained. It allows monitoring of allocated bytes against the total WASM heap size and provides automated mechanisms to block operations or suggest maintenance tasks like compaction when specific thresholds are reached.
Sources: src/wasm/memory.rs:1-12, README.md:129-142
Core Architecture and Monitoring
The system relies on real-time introspection of the WASM memory buffer combined with internal allocation tracking. It categorizes memory state into three distinct levels based on usage percentages: Normal, Warning, and Critical.
Memory Pressure Levels
| Level | Threshold | Behavioral Guidance |
|---|---|---|
| Normal | < 80% | All operations allowed; system healthy. |
| Warning | 80% - 95% | High usage; consider reducing data or running compaction. |
| Critical | > 95% | Risk of Out-of-Memory (OOM); stop inserts. |
Sources: src/wasm/memory.rs:24-34, src/wasm/mod.rs:1145-1153
Allocation Tracking Logic
EdgeVec tracks memory usage through a thread-local estimate. When vectors are inserted (individually or in batches), the system calculates the byte size (typically dimensions * 4 for F32 vectors) and updates a global counter. This counter is then compared against the actual byteLength of the WASM ArrayBuffer to determine the usage percentage.
API Interfaces
The API is exposed to JavaScript through the main EdgeVec handle, providing both status retrieval and configuration methods.
Monitoring Methods
| Method | Return Type | Description |
|---|---|---|
getMemoryPressure() | MemoryPressure | Returns current level, used bytes, total bytes, and percentage. |
canInsert() | boolean | Checks if memory is critical and if insert blocking is enabled. |
getMemoryRecommendation() | MemoryRecommendation | Provides actionable guidance (e.g., "compact" or "reduce"). |
memoryUsage() | number | Returns total approximate bytes used by the index. |
Sources: pkg/edgevec.js:1003-1123, src/wasm/mod.rs:1159-1262
Configuration Parameters
Applications can customize how the API reacts to memory limits using setMemoryConfig.
| Option | Type | Default | Description |
|---|---|---|---|
warningThreshold | number | 80.0 | Usage % to trigger "warning" level. |
criticalThreshold | number | 95.0 | Usage % to trigger "critical" level. |
autoCompactOnWarning | boolean | false | Whether to trigger compaction automatically. |
blockInsertsOnCritical | boolean | true | Prevent insertions when memory is critical. |
Sources: src/wasm/memory.rs:88-100, pkg/edgevec.js:1037-1055
Graceful Degradation Workflow
The API is designed to trigger specific lifecycle events in the host application to prevent crashes. A typical sequence involves monitoring the pressure level and executing a compact() operation to reclaim space from soft-deleted vectors.
Data Models
The API utilizes structured objects to communicate state between the Rust core and the JavaScript environment.
MemoryPressure Object
Used to provide a snapshot of current resource utilization.
level: One of"normal","warning", or"critical".usedBytes: Estimated bytes currently allocated for vector storage and metadata.totalBytes: The total size of the current WebAssembly heap.usagePercent: The ratio of used to total bytes.
MemoryRecommendation Object
Used to provide actionable logic to application developers.
action: Specific suggested action (e.g.,"compact").message: Human-readable explanation of the state.canInsert: Boolean indicating if the engine will accept more data.suggestCompact: Boolean indicating if space reclamation via compaction is viable.
Sources: src/wasm/memory.rs:39-50, src/wasm/memory.rs:113-122, pkg/edgevec.js:1072-1085
Conclusion
The Memory Pressure API is a critical component for browser-based deployments of EdgeVec, where memory resources are strictly limited by the host environment. By combining proactive allocation tracking with configurable thresholds, it enables developers to build resilient vector search applications that can maintain stability under heavy data loads through automated compaction and operation blocking.
Sources: README.md:129-142, src/wasm/memory.rs:1-12