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_component_model_implements(self, enable: bool) -> None:

183 """

184 Configures whether the WebAssembly component model implements proposal

185 is enabled.

186 """

187 if not isinstance(enable, bool):

188 raise TypeError("expected a bool")

189 ffi.wasmtime_config_wasm_component_model_implements_set(self.ptr(), enable)

190

191 @setter_property

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

193 """

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

195

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

197 """

198

199 if not isinstance(enable, bool):

200 raise TypeError('expected a bool')

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

202

203 @setter_property

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

205 """

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

207 enabled.

208

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

210 """

211 if not isinstance(enable, bool):

212 raise TypeError('expected a bool')

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

214

215 @setter_property

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

217 """

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

219

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

221 """

222 if not isinstance(enable, bool):

223 raise TypeError('expected a bool')

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

225

226 @setter_property

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

228 """

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

230

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

232 """

233 if not isinstance(enable, bool):

234 raise TypeError('expected a bool')

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

236

237 @setter_property

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

239 """

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

241

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

243 """

244 if not isinstance(enable, bool):

245 raise TypeError('expected a bool')

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

247

248 @setter_property

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

250 """

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

252

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

254 """

255 if not isinstance(enable, bool):

256 raise TypeError('expected a bool')

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

258

259 @setter_property

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

261 """

262 Configures the compilation strategy used for wasm code.

263

264 Acceptable values for `strategy` are:

265

266 * `"auto"`

267 * `"cranelift"`

268 """

269

270 if strategy == "auto":

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

272 elif strategy == "cranelift":

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

274 else:

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

276

277 @setter_property

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

279 if not isinstance(enable, bool):

280 raise TypeError('expected a bool')

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

282

283 @setter_property

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

285 if opt_level == "none":

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

287 elif opt_level == "speed":

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

289 elif opt_level == "speed_and_size":

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

291 else:

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

293

294 @setter_property

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

296 """

297 Configures the profiling strategy used for JIT code.

298

299 Acceptable values for `profiler` are:

300

301 * `"none"`

302 * `"jitdump"`

303 * `"vtune"`

304 * `"perfmap"`

305 """

306 if profiler == "none":

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

308 elif profiler == "jitdump":

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

310 elif profiler == "vtune":

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

312 elif profiler == "perfmap":

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

314 else:

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

316

317 @setter_property

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

319 """

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

321

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

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

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

325

326 More information about cache configuration can be found at

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

328 """

329

330 if isinstance(enabled, bool):

331 if not enabled:

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

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

334 elif isinstance(enabled, str):

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

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

337 )

338 else:

339 raise TypeError("expected string or bool")

340 if error:

341 raise WasmtimeError._from_ptr(error)

342

343 @setter_property

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

345 """

346 Configures whether wasm execution can be interrupted via epoch

347 increments.

348 """

349

350 if enabled:

351 val = 1

352 else:

353 val = 0

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

355

356 @setter_property

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

358 """

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

360 execution.

361

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

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

364 """

365 if not isinstance(instances, bool):

366 raise TypeError('expected an bool')

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

368

369 @setter_property

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

371 """

372 Configures whether parallel compilation is enabled for functions

373 within a module.

374

375 This is enabled by default.

376 """

377 if not isinstance(enable, bool):

378 raise TypeError('expected a bool')

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

380

381 @setter_property

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

383 """

384 Configures whether shared memories can be created.

385

386 This is disabled by default.

387 """

388 if not isinstance(enable, bool):

389 raise TypeError('expected a bool')

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

391

392 @setter_property

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

394 """

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

396

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

398 overflow or want to limit wasm stack usage.

399

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

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

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

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

404 of embedders to uphold this invariant.

405 """

406 if not isinstance(size, int):

407 raise TypeError('expected an int')

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

409

410 @setter_property

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

412 """

413 Enables or disables GC support in Wasmtime entirely.

414

415 This defaults to `True`.

416 """

417 if not isinstance(enable, bool):

418 raise TypeError('expected a bool')

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

420

421 @setter_property

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

423 """

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

425

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

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

428 """

429 if not isinstance(enable, bool):

430 raise TypeError('expected a bool')

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

432

433 @setter_property

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

435 """

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

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

438 a new location when they need to grow.

439 """

440 if not isinstance(enable, bool):

441 raise TypeError('expected a bool')

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

443

444 @setter_property

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

446 """

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

448 memories.

449

450 For more information see the Rust documentation at

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

452 """

453 if not isinstance(size, int):

454 raise TypeError('expected an int')

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

456

457 @setter_property

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

459 """

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

461

462 For more information see the Rust documentation at

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

464 """

465 if not isinstance(size, int):

466 raise TypeError('expected an int')

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

468

469 @setter_property

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

471 """

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

473 memories to grow into after being relocated.

474

475 For more information see the Rust documentation at

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

477 """

478 if not isinstance(size, int):

479 raise TypeError('expected an int')

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

481

482 @setter_property

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

484 """

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

486 `.eh_frame` on Linux).

487

488 This defaults to `True`.

489 """

490 if not isinstance(enable, bool):

491 raise TypeError('expected a bool')

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

493

494 @setter_property

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

496 """

497 Configures the target triple that this configuration will produce

498 machine code for.

499

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

501 inference of native CPU features.

502

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

504

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

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

507 be used to compile code.

508 """

509 if not isinstance(triple, str):

510 raise TypeError('expected a str')

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

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

513 if error:

514 raise WasmtimeError._from_ptr(error)

515

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

517 """

518 Enables a target-specific flag in Cranelift.

519

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

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

522 """

523 if not isinstance(flag, str):

524 raise TypeError('expected a str')

525 ffi.wasmtime_config_cranelift_flag_enable(self.ptr(),

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

527

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

529 """

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

531

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

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

534 """

535 if not isinstance(key, str):

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

537 if not isinstance(value, str):

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

539 ffi.wasmtime_config_cranelift_flag_set(self.ptr(),

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

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

542

543 @setter_property

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

545 """

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

547 instead of traditional Unix signal handling.

548

549 This defaults to `True` on macOS.

550 """

551 if not isinstance(enable, bool):

552 raise TypeError('expected a bool')

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

554

555 @setter_property

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

557 """

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

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

560

561 This defaults to `True`.

562 """

563 if not isinstance(enable, bool):

564 raise TypeError('expected a bool')

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

566

567 @setter_property

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

569 """

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

571 initialize linear memory.

572

573 This can significantly improve instantiation performance. Defaults

574 to `True`.

575 """

576 if not isinstance(enable, bool):

577 raise TypeError('expected a bool')

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