Coverage for wasmtime/_config.py: 83%

1from . import _ffi as ffi

2import ctypes

3from wasmtime import WasmtimeError, Managed

4import typing

7def setter_property(fset: typing.Callable) -> property:

8 prop = property(fset=fset)

9 if fset.__doc__:

10 prop.__doc__ = fset.__doc__

11 prop.__doc__ += "\n\n Note that this field can only be set, it cannot be read"

12 return prop

15class Config(Managed["ctypes._Pointer[ffi.wasm_config_t]"]):

16 """

17 Global configuration, used to create an `Engine`.

19 A `Config` houses a number of configuration options which tweaks how wasm

20 code is compiled or generated.

21 """

23 def __init__(self) -> None:

24 self._set_ptr(ffi.wasm_config_new())

26 def _delete(self, ptr: "ctypes._Pointer[ffi.wasm_config_t]") -> None:

27 ffi.wasm_config_delete(ptr)

29 @setter_property

30 def debug_info(self, enable: bool) -> None:

31 """

32 Configures whether DWARF debug information is emitted for the generated

33 code. This can improve profiling and the debugging experience.

34 """

36 if not isinstance(enable, bool):

37 raise TypeError('expected a bool')

38 ffi.wasmtime_config_debug_info_set(self.ptr(), enable)

40 @setter_property

41 def wasm_threads(self, enable: bool) -> None:

42 """

43 Configures whether the wasm [threads proposal] is enabled.

45 [threads proposal]: https://github.com/webassembly/threads

46 """

48 if not isinstance(enable, bool):

49 raise TypeError('expected a bool')

50 ffi.wasmtime_config_wasm_threads_set(self.ptr(), enable)

52 @setter_property

53 def wasm_tail_call(self, enable: bool) -> None:

54 """

55 Configures whether the wasm [tail call proposal] is enabled.

57 [tail call proposal]: https://github.com/WebAssembly/tail-call

58 """

60 if not isinstance(enable, bool):

61 raise TypeError('expected a bool')

62 ffi.wasmtime_config_wasm_tail_call_set(self.ptr(), enable)

64 @setter_property

65 def wasm_reference_types(self, enable: bool) -> None:

66 """

67 Configures whether the wasm [reference types proposal] is enabled.

69 [reference types proposal]: https://github.com/webassembly/reference-types

70 """

72 if not isinstance(enable, bool):

73 raise TypeError('expected a bool')

74 ffi.wasmtime_config_wasm_reference_types_set(self.ptr(), enable)

76 @setter_property

77 def wasm_simd(self, enable: bool) -> None:

78 """

79 Configures whether the wasm [SIMD proposal] is enabled.

81 [SIMD proposal]: https://github.com/webassembly/simd

82 """

84 if not isinstance(enable, bool):

85 raise TypeError('expected a bool')

86 ffi.wasmtime_config_wasm_simd_set(self.ptr(), enable)

88 @setter_property

89 def wasm_bulk_memory(self, enable: bool) -> None:

90 """

91 Configures whether the wasm [bulk memory proposal] is enabled.

93 [bulk memory proposal]: https://github.com/webassembly/bulk-memory

94 """

96 if not isinstance(enable, bool):

97 raise TypeError('expected a bool')

98 ffi.wasmtime_config_wasm_bulk_memory_set(self.ptr(), enable)

100 @setter_property

101 def wasm_multi_value(self, enable: bool) -> None:

102 """

103 Configures whether the wasm [multi value proposal] is enabled.

104

105 [multi value proposal]: https://github.com/webassembly/multi-value

106 """

107

108 if not isinstance(enable, bool):

109 raise TypeError('expected a bool')

110 ffi.wasmtime_config_wasm_multi_value_set(self.ptr(), enable)

111

112 @setter_property

113 def wasm_multi_memory(self, enable: bool) -> None:

114 """

115 Configures whether the wasm [multi memory proposal] is enabled.

116

117 [multi memory proposal]: https://github.com/webassembly/multi-memory

118 """

119

120 if not isinstance(enable, bool):

121 raise TypeError('expected a bool')

122 ffi.wasmtime_config_wasm_multi_memory_set(self.ptr(), enable)

123

124 @setter_property

125 def wasm_memory64(self, enable: bool) -> None:

126 """

127 Configures whether the wasm [memory64 proposal] is enabled.

128

129 [memory64 proposal]: https://github.com/webassembly/memory64

130 """

131

132 if not isinstance(enable, bool):

133 raise TypeError('expected a bool')

134 ffi.wasmtime_config_wasm_memory64_set(self.ptr(), enable)

135

136 @setter_property

137 def wasm_relaxed_simd(self, enable: bool) -> None:

138 """

139 Configures whether the wasm [relaxed simd proposal] is enabled.

140

141 [relaxed simd proposal]: https://github.com/webassembly/relaxed-simd

142 """

143

144 if not isinstance(enable, bool):

145 raise TypeError('expected a bool')

146 ffi.wasmtime_config_wasm_relaxed_simd_set(self.ptr(), enable)

147

148 @setter_property

149 def wasm_relaxed_simd_deterministic(self, enable: bool) -> None:

150 """

151 Configures whether the wasm [relaxed simd proposal] is deterministic

152 in is execution as opposed to having the most optimal implementation for

153 the current platform.

154

155 [relaxed simd proposal]: https://github.com/webassembly/relaxed-simd

156 """

157

158 if not isinstance(enable, bool):

159 raise TypeError('expected a bool')

160 ffi.wasmtime_config_wasm_relaxed_simd_deterministic_set(self.ptr(), enable)

161

162 @setter_property

163 def wasm_component_model(self, enable: bool) -> None:

164 """

165 Configures whether the WebAssembly component model proposal is enabled.

166 """

167 if not isinstance(enable, bool):

168 raise TypeError("expected a bool")

169 ffi.wasmtime_config_wasm_component_model_set(self.ptr(), enable)

170

171 @setter_property

172 def wasm_component_model_map(self, enable: bool) -> None:

173 """

174 Configures whether the WebAssembly component model map types proposal

175 is enabled.

176 """

177 if not isinstance(enable, bool):

178 raise TypeError("expected a bool")

179 ffi.wasmtime_config_wasm_component_model_map_set(self.ptr(), enable)

180

181 @setter_property

182 def wasm_exceptions(self, enable: bool) -> None:

183 """

184 Configures whether the wasm [exceptions proposal] is enabled.

185

186 [exceptions proposal]: https://github.com/WebAssembly/exception-handling

187 """

188

189 if not isinstance(enable, bool):

190 raise TypeError('expected a bool')

191 ffi.wasmtime_config_wasm_exceptions_set(self.ptr(), enable)

192

193 @setter_property

194 def wasm_function_references(self, enable: bool) -> None:

195 """

196 Configures whether the wasm [typed function references proposal] is

197 enabled.

198

199 [typed function references proposal]: https://github.com/WebAssembly/function-references

200 """

201 if not isinstance(enable, bool):

202 raise TypeError('expected a bool')

203 ffi.wasmtime_config_wasm_function_references_set(self.ptr(), enable)

204

205 @setter_property

206 def wasm_gc(self, enable: bool) -> None:

207 """

208 Configures whether the wasm [GC proposal] is enabled.

209

210 [GC proposal]: https://github.com/WebAssembly/gc

211 """

212 if not isinstance(enable, bool):

213 raise TypeError('expected a bool')

214 ffi.wasmtime_config_wasm_gc_set(self.ptr(), enable)

215

216 @setter_property

217 def wasm_wide_arithmetic(self, enable: bool) -> None:

218 """

219 Configures whether the wasm [wide arithmetic proposal] is enabled.

220

221 [wide arithmetic proposal]: https://github.com/WebAssembly/wide-arithmetic

222 """

223 if not isinstance(enable, bool):

224 raise TypeError('expected a bool')

225 ffi.wasmtime_config_wasm_wide_arithmetic_set(self.ptr(), enable)

226

227 @setter_property

228 def wasm_custom_page_sizes(self, enable: bool) -> None:

229 """

230 Configures whether the wasm [custom-page-sizes proposal] is enabled.

231

232 [custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes

233 """

234 if not isinstance(enable, bool):

235 raise TypeError('expected a bool')

236 ffi.wasmtime_config_wasm_custom_page_sizes_set(self.ptr(), enable)

237

238 @setter_property

239 def wasm_stack_switching(self, enable: bool) -> None:

240 """

241 Configures whether the wasm [stack switching proposal] is enabled.

242

243 [stack switching proposal]: https://github.com/WebAssembly/stack-switching

244 """

245 if not isinstance(enable, bool):

246 raise TypeError('expected a bool')

247 ffi.wasmtime_config_wasm_stack_switching_set(self.ptr(), enable)

248

249 @setter_property

250 def strategy(self, strategy: str) -> None:

251 """

252 Configures the compilation strategy used for wasm code.

253

254 Acceptable values for `strategy` are:

255

256 * `"auto"`

257 * `"cranelift"`

258 """

259

260 if strategy == "auto":

261 ffi.wasmtime_config_strategy_set(self.ptr(), 0)

262 elif strategy == "cranelift":

263 ffi.wasmtime_config_strategy_set(self.ptr(), 1)

264 else:

265 raise WasmtimeError("unknown strategy: " + str(strategy))

266

267 @setter_property

268 def cranelift_debug_verifier(self, enable: bool) -> None:

269 if not isinstance(enable, bool):

270 raise TypeError('expected a bool')

271 ffi.wasmtime_config_cranelift_debug_verifier_set(self.ptr(), enable)

272

273 @setter_property

274 def cranelift_opt_level(self, opt_level: str) -> None:

275 if opt_level == "none":

276 ffi.wasmtime_config_cranelift_opt_level_set(self.ptr(), 0)

277 elif opt_level == "speed":

278 ffi.wasmtime_config_cranelift_opt_level_set(self.ptr(), 1)

279 elif opt_level == "speed_and_size":

280 ffi.wasmtime_config_cranelift_opt_level_set(self.ptr(), 2)

281 else:

282 raise WasmtimeError("unknown opt level: " + str(opt_level))

283

284 @setter_property

285 def profiler(self, profiler: str) -> None:

286 """

287 Configures the profiling strategy used for JIT code.

288

289 Acceptable values for `profiler` are:

290

291 * `"none"`

292 * `"jitdump"`

293 * `"vtune"`

294 * `"perfmap"`

295 """

296 if profiler == "none":

297 ffi.wasmtime_config_profiler_set(self.ptr(), 0)

298 elif profiler == "jitdump":

299 ffi.wasmtime_config_profiler_set(self.ptr(), 1)

300 elif profiler == "vtune":

301 ffi.wasmtime_config_profiler_set(self.ptr(), 2)

302 elif profiler == "perfmap":

303 ffi.wasmtime_config_profiler_set(self.ptr(), 3)

304 else:

305 raise WasmtimeError("unknown profiler: " + str(profiler))

306

307 @setter_property

308 def cache(self, enabled: typing.Union[bool, str]) -> None:

309 """

310 Configures whether code caching is enabled for this `Config`.

311

312 The value `True` can be passed in here to enable the default caching

313 configuration and location, or a path to a file can be passed in which

314 is a path to a TOML configuration file for the cache.

315

316 More information about cache configuration can be found at

317 https://bytecodealliance.github.io/wasmtime/cli-cache.html

318 """

319

320 if isinstance(enabled, bool):

321 if not enabled:

322 raise WasmtimeError("caching cannot be explicitly disabled")

323 error = ffi.wasmtime_config_cache_config_load(self.ptr(), None)

324 elif isinstance(enabled, str):

325 error = ffi.wasmtime_config_cache_config_load(self.ptr(),

326 ctypes.c_char_p(enabled.encode('utf-8')),

327 )

328 else:

329 raise TypeError("expected string or bool")

330 if error:

331 raise WasmtimeError._from_ptr(error)

332

333 @setter_property

334 def epoch_interruption(self, enabled: bool) -> None:

335 """

336 Configures whether wasm execution can be interrupted via epoch

337 increments.

338 """

339

340 if enabled:

341 val = 1

342 else:

343 val = 0

344 ffi.wasmtime_config_epoch_interruption_set(self.ptr(), val)

345

346 @setter_property

347 def consume_fuel(self, instances: bool) -> None:

348 """

349 Configures whether wasm code will consume *fuel* as part of its

350 execution.

351

352 Fuel consumption allows WebAssembly to trap when fuel runs out.

353 Currently stores start with 0 fuel if this is enabled.

354 """

355 if not isinstance(instances, bool):

356 raise TypeError('expected an bool')

357 ffi.wasmtime_config_consume_fuel_set(self.ptr(), instances)

358

359 @setter_property

360 def parallel_compilation(self, enable: bool) -> None:

361 """

362 Configures whether parallel compilation is enabled for functions

363 within a module.

364

365 This is enabled by default.

366 """

367 if not isinstance(enable, bool):

368 raise TypeError('expected a bool')

369 ffi.wasmtime_config_parallel_compilation_set(self.ptr(), enable)

370

371 @setter_property

372 def shared_memory(self, enable: bool) -> None:

373 """

374 Configures whether shared memories can be created.

375

376 This is disabled by default.

377 """

378 if not isinstance(enable, bool):

379 raise TypeError('expected a bool')

380 ffi.wasmtime_config_shared_memory_set(self.ptr(), enable)

381

382 @setter_property

383 def max_wasm_stack(self, size: int) -> None:

384 """

385 Configures the maximum stack size, in bytes, that JIT code can use.

386

387 This defaults to 2MB. Configuring this can help if you hit stack

388 overflow or want to limit wasm stack usage.

389

390 Note that if this limit is set too high then the OS's stack guards may

391 be hit which will result in an uncaught segfault. This limit can only

392 be set to a size that's smaller than the actual OS stack, and that's not

393 something able to be dynamically determined, so it's the responsibility

394 of embedders to uphold this invariant.

395 """

396 if not isinstance(size, int):

397 raise TypeError('expected an int')

398 ffi.wasmtime_config_max_wasm_stack_set(self.ptr(), size)

399

400 @setter_property

401 def gc_support(self, enable: bool) -> None:

402 """

403 Enables or disables GC support in Wasmtime entirely.

404

405 This defaults to `True`.

406 """

407 if not isinstance(enable, bool):

408 raise TypeError('expected a bool')

409 ffi.wasmtime_config_gc_support_set(self.ptr(), enable)

410

411 @setter_property

412 def cranelift_nan_canonicalization(self, enable: bool) -> None:

413 """

414 Configures whether Cranelift should perform a NaN-canonicalization pass.

415

416 This replaces NaNs with a single canonical value for fully deterministic

417 WebAssembly execution. Not required by the spec; disabled by default.

418 """

419 if not isinstance(enable, bool):

420 raise TypeError('expected a bool')

421 ffi.wasmtime_config_cranelift_nan_canonicalization_set(self.ptr(), enable)

422

423 @setter_property

424 def memory_may_move(self, enable: bool) -> None:

425 """

426 Configures whether `memory_reservation` is the maximal size of linear

427 memory (disabling movement) or whether linear memories may be moved to

428 a new location when they need to grow.

429 """

430 if not isinstance(enable, bool):

431 raise TypeError('expected a bool')

432 ffi.wasmtime_config_memory_may_move_set(self.ptr(), enable)

433

434 @setter_property

435 def memory_reservation(self, size: int) -> None:

436 """

437 Configures the initial memory reservation size, in bytes, for linear

438 memories.

439

440 For more information see the Rust documentation at

441 https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.memory_reservation

442 """

443 if not isinstance(size, int):

444 raise TypeError('expected an int')

445 ffi.wasmtime_config_memory_reservation_set(self.ptr(), size)

446

447 @setter_property

448 def memory_guard_size(self, size: int) -> None:

449 """

450 Configures the guard region size, in bytes, for linear memory.

451

452 For more information see the Rust documentation at

453 https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.memory_guard_size

454 """

455 if not isinstance(size, int):

456 raise TypeError('expected an int')

457 ffi.wasmtime_config_memory_guard_size_set(self.ptr(), size)

458

459 @setter_property

460 def memory_reservation_for_growth(self, size: int) -> None:

461 """

462 Configures the size, in bytes, of extra virtual memory reserved for

463 memories to grow into after being relocated.

464

465 For more information see the Rust documentation at

466 https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.memory_reservation_for_growth

467 """

468 if not isinstance(size, int):

469 raise TypeError('expected an int')

470 ffi.wasmtime_config_memory_reservation_for_growth_set(self.ptr(), size)

471

472 @setter_property

473 def native_unwind_info(self, enable: bool) -> None:

474 """

475 Configures whether to generate native unwind information (e.g.

476 `.eh_frame` on Linux).

477

478 This defaults to `True`.

479 """

480 if not isinstance(enable, bool):

481 raise TypeError('expected a bool')

482 ffi.wasmtime_config_native_unwind_info_set(self.ptr(), enable)

483

484 @setter_property

485 def target(self, triple: str) -> None:

486 """

487 Configures the target triple that this configuration will produce

488 machine code for.

489

490 Defaults to the native host. Setting this also disables automatic

491 inference of native CPU features.

492

493 Raises a `WasmtimeError` if the target triple is not recognized.

494

495 Note that if this is set to something other than the host then an

496 `Engine` created won't be able to run generated code, but it can still

497 be used to compile code.

498 """

499 if not isinstance(triple, str):

500 raise TypeError('expected a str')

501 error = ffi.wasmtime_config_target_set(self.ptr(),

502 ctypes.c_char_p(triple.encode('utf-8')))

503 if error:

504 raise WasmtimeError._from_ptr(error)

505

506 def cranelift_flag_enable(self, flag: str) -> None:

507 """

508 Enables a target-specific flag in Cranelift.

509

510 This can be used to enable CPU features such as SSE4.2 on x86_64

511 hosts. Available flags can be explored with `wasmtime settings`.

512 """

513 if not isinstance(flag, str):

514 raise TypeError('expected a str')

515 ffi.wasmtime_config_cranelift_flag_enable(self.ptr(),

516 ctypes.c_char_p(flag.encode('utf-8')))

517

518 def cranelift_flag_set(self, key: str, value: str) -> None:

519 """

520 Sets a target-specific flag in Cranelift to the specified value.

521

522 This can be used to configure CPU features such as SSE4.2 on x86_64

523 hosts. Available flags can be explored with `wasmtime settings`.

524 """

525 if not isinstance(key, str):

526 raise TypeError('expected a str for key')

527 if not isinstance(value, str):

528 raise TypeError('expected a str for value')

529 ffi.wasmtime_config_cranelift_flag_set(self.ptr(),

530 ctypes.c_char_p(key.encode('utf-8')),

531 ctypes.c_char_p(value.encode('utf-8')))

532

533 @setter_property

534 def macos_use_mach_ports(self, enable: bool) -> None:

535 """

536 Configures whether Mach ports are used for exception handling on macOS

537 instead of traditional Unix signal handling.

538

539 This defaults to `True` on macOS.

540 """

541 if not isinstance(enable, bool):

542 raise TypeError('expected a bool')

543 ffi.wasmtime_config_macos_use_mach_ports_set(self.ptr(), enable)

544

545 @setter_property

546 def signals_based_traps(self, enable: bool) -> None:

547 """

548 Configures whether signals-based trap handlers are enabled (e.g.

549 `SIGILL` and `SIGSEGV` on Unix platforms).

550

551 This defaults to `True`.

552 """

553 if not isinstance(enable, bool):

554 raise TypeError('expected a bool')

555 ffi.wasmtime_config_signals_based_traps_set(self.ptr(), enable)

556

557 @setter_property

558 def memory_init_cow(self, enable: bool) -> None:

559 """

560 Configures whether copy-on-write memory-mapped data is used to

561 initialize linear memory.

562

563 This can significantly improve instantiation performance. Defaults

564 to `True`.

565 """

566 if not isinstance(enable, bool):

567 raise TypeError('expected a bool')

568 ffi.wasmtime_config_memory_init_cow_set(self.ptr(), enable)