webkit_memory_api.go RawHistoryFolder
1// Package contracts defines the WebKit memory optimization API contracts
2// This file contains the expected function signatures and behavior contracts
3package contracts
4
5import (
6 "time"
7 "unsafe"
8)
9
10// WebKitMemoryAPI defines the contract for WebKit memory management functions
11type WebKitMemoryAPI interface {
12 // Memory Pressure Settings
13 CreateMemoryPressureSettings(memoryLimitMB int, conservativeThreshold, strictThreshold, killThreshold, pollInterval float64) (unsafe.Pointer, error)
14 ApplyMemoryPressureSettings(context unsafe.Pointer, settings unsafe.Pointer) error
15
16 // Cache Model Management
17 SetCacheModel(context unsafe.Pointer, model CacheModel) error
18 GetCurrentCacheModel(context unsafe.Pointer) (CacheModel, error)
19
20 // JavaScript Garbage Collection
21 TriggerJavaScriptGC(context unsafe.Pointer) error
22
23 // WebView Settings
24 SetPageCacheEnabled(settings unsafe.Pointer, enabled bool) error
25 SetOfflineAppCacheEnabled(settings unsafe.Pointer, enabled bool) error
26
27 // Memory Monitoring
28 GetProcessMemoryInfo(pid int) (ProcessMemoryInfo, error)
29 ListWebKitProcesses() ([]ProcessMemoryInfo, error)
30}
31
32// CacheModel represents WebKit cache model options
33type CacheModel int
34
35const (
36 CacheModelDocumentViewer CacheModel = iota
37 CacheModelWebBrowser
38 CacheModelPrimaryWebBrowser
39)
40
41// ProcessMemoryInfo represents process memory statistics
42type ProcessMemoryInfo struct {
43 PID int `json:"pid"`
44 VmRSS int64 `json:"vm_rss"` // KB
45 VmSize int64 `json:"vm_size"` // KB
46 VmPeak int64 `json:"vm_peak"` // KB
47 ProcessName string `json:"process_name"`
48}
49
50// MemoryConfigAPI defines the contract for memory configuration management
51type MemoryConfigAPI interface {
52 // Configuration Validation
53 ValidateMemoryConfig(config MemoryConfig) error
54
55 // Preset Management
56 GetMemoryOptimizedPreset() MemoryConfig
57 GetBalancedPreset() MemoryConfig
58 GetHighPerformancePreset() MemoryConfig
59
60 // Configuration Application
61 ApplyMemoryConfig(webview unsafe.Pointer, config MemoryConfig) error
62}
63
64// MemoryConfig represents memory optimization configuration
65type MemoryConfig struct {
66 MemoryLimitMB int `json:"memory_limit_mb"`
67 ConservativeThreshold float64 `json:"conservative_threshold"`
68 StrictThreshold float64 `json:"strict_threshold"`
69 KillThreshold float64 `json:"kill_threshold"`
70 PollIntervalSeconds float64 `json:"poll_interval_seconds"`
71 CacheModel string `json:"cache_model"`
72 EnablePageCache bool `json:"enable_page_cache"`
73 EnableOfflineAppCache bool `json:"enable_offline_app_cache"`
74 ProcessRecycleThreshold int `json:"process_recycle_threshold"`
75 EnableGCInterval int `json:"enable_gc_interval"`
76 EnableMemoryMonitoring bool `json:"enable_memory_monitoring"`
77}
78
79// MemoryStatsAPI defines the contract for memory statistics tracking
80type MemoryStatsAPI interface {
81 // Statistics Retrieval
82 GetMemoryStats(webviewID uintptr) (MemoryStats, error)
83 GetAllMemoryStats() (map[uintptr]MemoryStats, error)
84
85 // Memory Management Operations
86 TriggerMemoryCleanup(webviewID uintptr) error
87 ShouldRecycleWebView(webviewID uintptr) (bool, error)
88
89 // Monitoring Operations
90 StartMemoryMonitoring(interval time.Duration) error
91 StopMemoryMonitoring() error
92 GetTotalMemoryUsage() (float64, error) // MB
93}
94
95// MemoryStats represents WebView memory statistics
96type MemoryStats struct {
97 PageLoadCount int `json:"page_load_count"`
98 LastGCTime time.Time `json:"last_gc_time"`
99 HasMemoryPressureSettings bool `json:"has_memory_pressure_settings"`
100 WebViewID uintptr `json:"webview_id"`
101}
102
103// WebViewLifecycleAPI defines the contract for WebView lifecycle management
104type WebViewLifecycleAPI interface {
105 // WebView Registration
106 RegisterWebView(webviewID uintptr, config MemoryConfig) error
107 UnregisterWebView(webviewID uintptr) error
108
109 // Lifecycle Events
110 OnPageLoad(webviewID uintptr, url string) error
111 OnMemoryPressure(webviewID uintptr, pressureLevel int) error
112 OnGarbageCollection(webviewID uintptr) error
113
114 // Recycling Operations
115 ShouldRecycleWebView(webviewID uintptr) bool
116 RequestWebViewRecycling(webviewID uintptr) error
117}
118
119// Error Types - define expected error behaviors
120
121// ErrMemoryLimitExceeded indicates memory usage exceeded configured limits
122type ErrMemoryLimitExceeded struct {
123 Limit int64 // bytes
124 Actual int64 // bytes
125}
126
127func (e ErrMemoryLimitExceeded) Error() string {
128 return "memory limit exceeded"
129}
130
131// ErrInvalidMemoryConfig indicates invalid memory configuration parameters
132type ErrInvalidMemoryConfig struct {
133 Field string
134 Message string
135}
136
137func (e ErrInvalidMemoryConfig) Error() string {
138 return "invalid memory configuration"
139}
140
141// ErrWebKitAPIUnavailable indicates WebKit memory APIs are not available
142type ErrWebKitAPIUnavailable struct {
143 Function string
144 Reason string
145}
146
147func (e ErrWebKitAPIUnavailable) Error() string {
148 return "WebKit API unavailable"
149}
150
151// Behavioral Contracts - define expected behaviors as comments
152
153/*
154MEMORY_PRESSURE_CONTRACT:
155- Conservative threshold (0.2) should trigger background cleanup
156- Strict threshold (0.35) should trigger aggressive cleanup
157- Kill threshold (0.8) should trigger process termination warning
158- Poll interval determines monitoring frequency (2.0s recommended)
159- Memory limit applies per-WebView instance, not global
160
161CACHE_MODEL_CONTRACT:
162- DocumentViewer: Minimal caching, ~40% less memory than WebBrowser
163- WebBrowser: Default caching, balanced performance/memory
164- PrimaryWebBrowser: Maximum caching, highest memory usage
165- Changes take effect on next navigation
166
167GC_CONTRACT:
168- JavaScript GC triggers should complete within 2 seconds
169- GC should not block UI thread or navigation
170- Periodic GC intervals should be 30-120 seconds for effectiveness
171- Manual GC triggers should be idempotent (safe to call repeatedly)
172
173PROCESS_RECYCLING_CONTRACT:
174- Page load counting should be accurate and monotonic
175- Recycling recommendations should not force immediate action
176- New WebView creation should reset all memory counters
177- Recycling should preserve user session state until destruction
178
179MONITORING_CONTRACT:
180- Memory statistics should be updated within poll interval
181- /proc parsing should handle process disappearance gracefully
182- Memory reporting should be accurate within 5% of system tools
183- Monitoring overhead should be <1% of total browser memory usage
184*/