0
# Core Runtime
1
2
The core runtime provides the foundational components for WebAssembly execution including engine configuration, module compilation, instance management, and execution environment control. These components establish the foundation for all WebAssembly operations.
3
4
## Capabilities
5
6
### Engine Configuration
7
8
Global configuration system controlling WebAssembly compilation strategy, optimization level, debugging features, and runtime behavior. Configuration must be set before engine creation and cannot be modified afterwards.
9
10
```python { .api }
11
class Config:
12
def __init__(self): ...
13
14
# Compilation and optimization settings
15
def debug_info(self, enable: bool) -> None:
16
"""Enable DWARF debug information generation for profiling and debugging"""
17
18
def strategy(self, strategy: str) -> None:
19
"""Set compilation strategy: 'auto', 'cranelift'"""
20
21
def profiler(self, profiler: str) -> None:
22
"""Enable profiler: 'none', 'jitdump', 'vtune'"""
23
24
# WebAssembly proposals
25
def wasm_threads(self, enable: bool) -> None:
26
"""Enable WebAssembly threads proposal"""
27
28
def wasm_reference_types(self, enable: bool) -> None:
29
"""Enable WebAssembly reference types proposal"""
30
31
def wasm_simd(self, enable: bool) -> None:
32
"""Enable WebAssembly SIMD proposal"""
33
34
def wasm_bulk_memory(self, enable: bool) -> None:
35
"""Enable WebAssembly bulk memory operations proposal"""
36
37
def wasm_multi_value(self, enable: bool) -> None:
38
"""Enable WebAssembly multi-value proposal"""
39
40
def wasm_tail_call(self, enable: bool) -> None:
41
"""Enable WebAssembly tail call proposal"""
42
43
def wasm_multi_memory(self, enable: bool) -> None:
44
"""Enable WebAssembly multi-memory proposal"""
45
46
def wasm_memory64(self, enable: bool) -> None:
47
"""Enable WebAssembly memory64 proposal"""
48
49
def wasm_relaxed_simd(self, enable: bool) -> None:
50
"""Enable WebAssembly relaxed SIMD proposal"""
51
52
def wasm_relaxed_simd_deterministic(self, enable: bool) -> None:
53
"""Enable deterministic mode for relaxed SIMD proposal"""
54
55
# Compilation and optimization controls
56
def cranelift_debug_verifier(self, enable: bool) -> None:
57
"""Enable Cranelift debug verifier"""
58
59
def cranelift_opt_level(self, opt_level: str) -> None:
60
"""Set Cranelift optimization level: 'none', 'speed', 'speed_and_size'"""
61
62
# Performance and execution controls
63
def consume_fuel(self, enable: bool) -> None:
64
"""Enable fuel-based execution limiting"""
65
66
def epoch_interruption(self, enable: bool) -> None:
67
"""Enable epoch-based interruption for long-running code"""
68
69
def parallel_compilation(self, enable: bool) -> None:
70
"""Enable parallel compilation of WebAssembly functions"""
71
72
# Caching
73
def cache(self, enabled: Union[bool, str]) -> None:
74
"""Configure compilation caching: True/False or cache directory path"""
75
```
76
77
### Engine Management
78
79
WebAssembly compilation engine responsible for compiling modules, managing compilation caches, and providing runtime services. The engine is the top-level context for all WebAssembly operations.
80
81
```python { .api }
82
class Engine:
83
def __init__(self, config: Config = None):
84
"""
85
Create a new WebAssembly engine.
86
87
Parameters:
88
- config: Optional configuration. If None, uses default settings.
89
"""
90
91
def increment_epoch(self) -> None:
92
"""
93
Increment the epoch counter for epoch-based interruption.
94
Used to interrupt long-running WebAssembly code.
95
"""
96
97
def is_pulley(self) -> bool:
98
"""
99
Check if the engine is using the Pulley backend.
100
101
Returns:
102
True if using Pulley backend, False otherwise.
103
"""
104
```
105
106
### Store Management
107
108
Runtime state container managing execution context, fuel consumption, epoch deadlines, and instance lifecycle. Each store provides isolated execution environment for WebAssembly instances.
109
110
```python { .api }
111
class Store:
112
def __init__(self, engine: Engine = None, data: Any = None):
113
"""
114
Create a new store for WebAssembly execution.
115
116
Parameters:
117
- engine: WebAssembly engine. If None, creates default engine.
118
- data: Optional user data associated with the store.
119
"""
120
121
def data(self) -> Any:
122
"""Get the user data associated with this store"""
123
124
def gc(self) -> None:
125
"""Run garbage collection on externref values in the store"""
126
127
# Fuel-based execution control
128
def set_fuel(self, fuel: int) -> None:
129
"""
130
Set the fuel available for execution in this store.
131
132
Parameters:
133
- fuel: Amount of fuel to set (must be non-negative)
134
135
Raises:
136
WasmtimeError: If fuel consumption is not enabled in configuration
137
"""
138
139
def get_fuel(self) -> int:
140
"""
141
Get the amount of fuel remaining in this store.
142
143
Returns:
144
Amount of fuel remaining
145
146
Raises:
147
WasmtimeError: If fuel consumption is not enabled in configuration
148
"""
149
150
# WASI integration
151
def set_wasi(self, wasi: WasiConfig) -> None:
152
"""
153
Configure WASI for this store.
154
155
Parameters:
156
- wasi: WASI configuration object
157
158
Raises:
159
WasmtimeError: If WASI configuration fails
160
"""
161
162
# Epoch-based interruption
163
def set_epoch_deadline(self, ticks_after_current: int) -> None:
164
"""
165
Set relative epoch deadline for interrupting long-running code.
166
167
Parameters:
168
- ticks_after_current: Number of epoch ticks after current epoch before interruption
169
"""
170
171
# Resource limits
172
def set_limits(self, memory_size: int = -1, table_elements: int = -1,
173
instances: int = -1, tables: int = -1, memories: int = -1) -> None:
174
"""
175
Configure resource limits for this store.
176
177
Parameters:
178
- memory_size: Maximum linear memory size in bytes (-1 for unlimited)
179
- table_elements: Maximum table elements (-1 for unlimited)
180
- instances: Maximum WebAssembly instances (-1 for unlimited)
181
- tables: Maximum tables (-1 for unlimited)
182
- memories: Maximum linear memories (-1 for unlimited)
183
"""
184
```
185
186
### Module Compilation
187
188
WebAssembly module compilation and validation providing binary parsing, validation, serialization, and metadata extraction. Compiled modules can be instantiated multiple times and shared between stores.
189
190
```python { .api }
191
class Module:
192
def __init__(self, engine: Engine, wasm: bytes, validate: bool = True):
193
"""
194
Compile a WebAssembly module from binary.
195
196
Parameters:
197
- engine: WebAssembly engine for compilation
198
- wasm: WebAssembly binary data
199
- validate: Whether to validate the module (default: True)
200
201
Raises:
202
WasmtimeError: If compilation or validation fails
203
"""
204
205
@classmethod
206
def from_file(cls, engine: Engine, path: str, validate: bool = True) -> 'Module':
207
"""
208
Compile a WebAssembly module from file.
209
210
Parameters:
211
- engine: WebAssembly engine for compilation
212
- path: Path to WebAssembly binary file
213
- validate: Whether to validate the module (default: True)
214
215
Returns:
216
Compiled WebAssembly module
217
218
Raises:
219
WasmtimeError: If compilation, validation, or file reading fails
220
"""
221
222
@staticmethod
223
def validate(engine: Engine, wasm: bytes) -> None:
224
"""
225
Validate WebAssembly binary without compilation.
226
227
Parameters:
228
- engine: WebAssembly engine for validation context
229
- wasm: WebAssembly binary data to validate
230
231
Raises:
232
WasmtimeError: If validation fails
233
"""
234
235
def serialize(self) -> bytes:
236
"""
237
Serialize compiled module for caching.
238
239
Returns:
240
Serialized module data
241
"""
242
243
@classmethod
244
def deserialize(cls, engine: Engine, encoded: bytes) -> 'Module':
245
"""
246
Deserialize a previously compiled module.
247
248
Parameters:
249
- engine: WebAssembly engine (must be compatible)
250
- encoded: Serialized module data
251
252
Returns:
253
Deserialized WebAssembly module
254
255
Raises:
256
WasmtimeError: If deserialization fails or engine incompatible
257
"""
258
259
@property
260
def imports(self) -> List[ImportType]:
261
"""
262
Get the import requirements of this module.
263
264
Returns:
265
List of import type declarations
266
"""
267
268
@property
269
def exports(self) -> List[ExportType]:
270
"""
271
Get the exports provided by this module.
272
273
Returns:
274
List of export type declarations
275
"""
276
277
def custom_sections(self, name: str) -> List[bytes]:
278
"""
279
Get custom sections with the specified name.
280
281
Parameters:
282
- name: Name of custom section to retrieve
283
284
Returns:
285
List of custom section data
286
"""
287
```
288
289
## Usage Examples
290
291
### Basic Engine and Store Setup
292
293
```python
294
import wasmtime
295
296
# Create configuration with debugging enabled
297
config = wasmtime.Config()
298
config.debug_info(True)
299
config.wasm_simd(True)
300
config.consume_fuel(True)
301
302
# Create engine with configuration
303
engine = wasmtime.Engine(config)
304
305
# Create store with custom data
306
user_data = {"request_id": "123", "user": "alice"}
307
store = wasmtime.Store(engine, user_data)
308
309
# Set fuel for execution limiting
310
store.set_fuel(1000000)
311
```
312
313
### Module Compilation and Caching
314
315
```python
316
import wasmtime
317
318
engine = wasmtime.Engine()
319
320
# Compile from binary data
321
wasm_bytes = load_wasm_file("module.wasm")
322
module = wasmtime.Module(engine, wasm_bytes)
323
324
# Serialize for caching
325
cached_data = module.serialize()
326
save_to_cache(cached_data)
327
328
# Later: deserialize from cache
329
cached_data = load_from_cache()
330
module = wasmtime.Module.deserialize(engine, cached_data)
331
332
# Inspect module metadata
333
print(f"Module imports: {len(module.imports)}")
334
print(f"Module exports: {len(module.exports)}")
335
for export in module.exports:
336
print(f" Export: {export.name} ({export.type})")
337
```
338
339
### Fuel-based Execution Control
340
341
```python
342
import wasmtime
343
344
config = wasmtime.Config()
345
config.consume_fuel(True)
346
engine = wasmtime.Engine(config)
347
store = wasmtime.Store(engine)
348
349
# Set fuel before execution
350
store.set_fuel(100000)
351
352
# Execute WebAssembly code...
353
# func(store, args...)
354
355
# Check remaining fuel
356
remaining = store.get_fuel()
357
print(f"Fuel remaining: {remaining}")
358
359
# Set more fuel if needed
360
if remaining < 10000:
361
store.set_fuel(100000)
362
```
363
364
### Epoch-based Interruption
365
366
```python
367
import wasmtime
368
import threading
369
import time
370
371
engine = wasmtime.Engine()
372
store = wasmtime.Store(engine)
373
374
# Set epoch deadline
375
store.set_epoch_deadline(100)
376
377
# Function to increment epoch from another thread
378
def epoch_incrementer():
379
time.sleep(1) # Let execution start
380
for _ in range(200):
381
engine.increment_epoch()
382
time.sleep(0.01)
383
384
# Start epoch incrementer
385
thread = threading.Thread(target=epoch_incrementer)
386
thread.start()
387
388
# Long-running WebAssembly execution will be interrupted
389
# when epoch counter exceeds deadline
390
```