1# Data Model: WebKit Memory Optimization
2
3**Feature**: 005-webkit-memory-optimization
4**Phase**: 1 - Design & Data Model
5**Date**: 2025-01-10
6
7## Core Entities
8
9### MemoryConfig
10**Purpose**: Configuration settings that control WebKit memory optimization behavior
11
12**Fields**:
13- `MemoryLimitMB` (int): Maximum memory limit per WebView in MB (0 = unlimited)
14- `ConservativeThreshold` (float64): Early memory cleanup threshold (0.0-1.0, default 0.33)
15- `StrictThreshold` (float64): Aggressive memory cleanup threshold (0.0-1.0, default 0.5)
16- `KillThreshold` (float64): Process termination threshold (0.0-1.0, 0 = disabled)
17- `PollIntervalSeconds` (float64): Memory usage polling interval (default 2.0)
18- `CacheModel` (CacheModel): WebKit caching strategy (document_viewer/web_browser/primary_web_browser)
19- `EnablePageCache` (bool): Enable/disable page cache for back/forward navigation
20- `EnableOfflineAppCache` (bool): Enable/disable offline application caching
21- `ProcessRecycleThreshold` (int): Recycle WebView after N page loads (0 = disabled)
22- `EnableGCInterval` (int): JavaScript garbage collection interval in seconds (0 = disabled)
23- `EnableMemoryMonitoring` (bool): Enable detailed memory logging and monitoring
24
25**Validation Rules**:
26- ConservativeThreshold must be between 0.0 and 1.0
27- StrictThreshold must be between 0.0 and 1.0
28- StrictThreshold must be greater than ConservativeThreshold
29- KillThreshold must be between 0.0 and 1.0
30- PollIntervalSeconds must be non-negative
31- MemoryLimitMB must be non-negative
32
33**State Transitions**: Immutable configuration object (changes require new instance)
34
35### MemoryStats
36**Purpose**: Real-time and historical memory usage statistics for WebView instances
37
38**Fields**:
39- `pageLoadCount` (int): Number of pages loaded in this WebView instance
40- `lastGCTime` (time.Time): Timestamp of last JavaScript garbage collection
41- `memoryPressureSettings` (*C.WebKitMemoryPressureSettings): Native WebKit memory settings
42
43**Relationships**: 
44- Owned by WebView instance (1:1 relationship)
45- References native WebKit memory pressure settings
46- Tracked by WebViewMemoryManager (many:1 relationship)
47
48**Validation Rules**: Read-only statistics, no validation required
49
50**State Transitions**:
51- `pageLoadCount` increments on each page load
52- `lastGCTime` updates when garbage collection is triggered
53- `memoryPressureSettings` set once during WebView creation
54
55### ProcessMemoryInfo
56**Purpose**: System-level memory information for WebKit processes
57
58**Fields**:
59- `PID` (int): Process identifier
60- `VmRSS` (int64): Resident Set Size in KB (actual RAM usage)
61- `VmSize` (int64): Virtual Memory Size in KB (total virtual memory)
62- `VmPeak` (int64): Peak Virtual Memory in KB (maximum ever used)
63- `ProcessName` (string): Name of the process (extracted from cmdline)
64
65**Relationships**: 
66- Collected by WebViewMemoryManager for all WebKit processes
67- Associated with specific WebView instances (many:1 for multi-process WebKit)
68
69**Validation Rules**:
70- All memory values must be non-negative
71- PID must be positive integer
72
73**State Transitions**: Immutable snapshot of process memory state
74
75### OptimizationPreset
76**Purpose**: Pre-configured memory optimization settings for common use cases
77
78**Fields**: Embeds MemoryConfig with preset values
79
80**Preset Types**:
811. **MemoryOptimized**: Maximum memory reduction (256MB limit, aggressive thresholds)
822. **Balanced**: Moderate optimization (512MB limit, balanced thresholds)  
833. **HighPerformance**: Maximum performance (no limits, minimal optimization)
84
85**Validation Rules**: Inherits MemoryConfig validation rules
86
87**State Transitions**: Immutable preset definitions
88
89### WebViewMemoryManager
90**Purpose**: Global memory monitoring and lifecycle management for multiple WebViews
91
92**Fields**:
93- `views` (map[uintptr]*WebView): Registry of active WebViews by ID
94- `enableMonitoring` (bool): Enable background memory monitoring
95- `recycleThreshold` (int): Global recycling threshold
96- `monitoringInterval` (time.Duration): Monitoring check frequency
97- `stopMonitoring` (chan struct{}): Channel for stopping monitoring goroutine
98
99**Relationships**:
100- Manages multiple WebView instances (1:many)
101- Monitors ProcessMemoryInfo for all WebKit processes
102- Singleton pattern for global memory management
103
104**Validation Rules**:
105- monitoringInterval must be positive
106- recycleThreshold must be non-negative
107
108**State Transitions**:
109- WebViews registered on creation, unregistered on destruction
110- Monitoring starts when first WebView registered
111- Monitoring stops when last WebView unregistered
112
113## Entity Relationships
114
115```
116WebView (1) ----owns----> (1) MemoryStats
117   |                           |
118   |                           |
119   v                           v
120WebViewMemoryManager <-tracks- ProcessMemoryInfo
121   |
122   |
123   v (configures)
124MemoryConfig <-preset- OptimizationPreset
125```
126
127## Data Flow
128
129### Memory Configuration Flow
1301. User selects optimization preset or custom settings
1312. MemoryConfig validated and applied to WebView creation
1323. WebKit memory pressure settings configured via C API
1334. Settings persisted for process lifecycle
134
135### Memory Monitoring Flow
1361. WebViewMemoryManager polls /proc filesystem for process memory
1372. WebKit memory pressure callbacks trigger on internal events
1383. MemoryStats updated with current usage and GC events
1394. Memory events logged if monitoring enabled
140
141### Process Recycling Flow
1421. MemoryStats.pageLoadCount incremented on navigation
1432. WebViewMemoryManager checks recycling threshold
1443. Recycling recommendation logged (user/application decision)
1454. New WebView creation triggers fresh memory allocation
146
147## Memory Layout Considerations
148
149### Go Memory Management
150- WebView structs include finalizers for cleanup
151- CGO memory requires explicit free() calls
152- Channel-based coordination for goroutine cleanup
153- Careful pointer management for C callbacks
154
155### WebKit Native Memory
156- WebKitMemoryPressureSettings allocated via C API
157- GObject reference counting for WebKit objects
158- Memory pressure thresholds enforced by WebKit internally
159- Process memory isolated per WebView instance
160
161### Monitoring Memory Overhead
162- /proc parsing: ~1KB per process check
163- Memory statistics storage: ~100 bytes per WebView
164- Monitoring goroutine: ~8KB stack space
165- Logging overhead: configurable via EnableMemoryMonitoring flag
166
167## Testing Considerations
168
169### Unit Tests
170- MemoryConfig validation rules
171- OptimizationPreset value correctness
172- ProcessMemoryInfo parsing accuracy
173- WebViewMemoryManager lifecycle management
174
175### Integration Tests
176- WebKit memory pressure settings application
177- Real memory usage reduction measurement
178- Process recycling effectiveness
179- Memory monitoring accuracy vs /proc ground truth
180
181### Contract Tests
182- WebKit C API memory functions available
183- Memory pressure callbacks functional
184- GObject reference counting correct
185- CGO memory safety verified