Struct CodeBuilder
pub struct CodeBuilder<'a> { /* private fields */ }
Expand description
Builder-style structure used to create a Module
or
pre-compile a module to a serialized list of bytes.
This structure can be used for more advanced configuration when compiling a WebAssembly module. Most configuration can use simpler constructors such as:
Note that a CodeBuilder
always involves compiling WebAssembly bytes
to machine code. To deserialize a list of bytes use
Module::deserialize
instead.
A CodeBuilder
requires a source of WebAssembly bytes to be configured
before calling compile_module_serialized
or compile_module
. This can
be provided with either the wasm_binary
or wasm_binary_file
method.
Note that only a single source of bytes can be provided.
§WebAssembly Text Format
This builder supports the WebAssembly Text Format (*.wat
files) through
the CodeBuilder::wasm_binary_or_text
and
CodeBuilder::wasm_binary_or_text_file
methods. These methods
automatically convert WebAssembly text files to binary. Note though that
this behavior is disabled if the wat
crate feature is not enabled.
Implementations§
§impl<'a> CodeBuilder<'a>
impl<'a> CodeBuilder<'a>
pub fn new(engine: &'a Engine) -> CodeBuilder<'a>
pub fn new(engine: &'a Engine) -> CodeBuilder<'a>
Creates a new builder which will insert modules into the specified
Engine
.
pub fn wasm_binary(
&mut self,
wasm_bytes: impl Into<Cow<'a, [u8]>>,
wasm_path: Option<&'a Path>,
) -> Result<&mut CodeBuilder<'a>, Error>
pub fn wasm_binary( &mut self, wasm_bytes: impl Into<Cow<'a, [u8]>>, wasm_path: Option<&'a Path>, ) -> Result<&mut CodeBuilder<'a>, Error>
Configures the WebAssembly binary that is being compiled.
The wasm_bytes
parameter must be a binary WebAssembly file.
This will be stored within the CodeBuilder
for processing later when
compilation is finalized.
The optional wasm_path
parameter is the path to the wasm_bytes
on
disk, if any. This may be used for diagnostics and other
debugging-related purposes, but this method will not read the path
specified.
§Errors
This method will return an error if WebAssembly bytes have already been configured.
pub fn wasm_binary_or_text(
&mut self,
wasm_bytes: &'a [u8],
wasm_path: Option<&'a Path>,
) -> Result<&mut CodeBuilder<'a>, Error>
pub fn wasm_binary_or_text( &mut self, wasm_bytes: &'a [u8], wasm_path: Option<&'a Path>, ) -> Result<&mut CodeBuilder<'a>, Error>
Equivalent of CodeBuilder::wasm_binary
that also accepts the
WebAssembly text format.
This method will configure the WebAssembly binary to be compiled. The
input wasm_bytes
may either be the wasm text format or the binary
format. If the wat
crate feature is enabled, which is enabled by
default, then the text format will automatically be converted to the
binary format.
§Errors
This method will return an error if WebAssembly bytes have already been
configured. This method will also return an error if wasm_bytes
is the
wasm text format and the text syntax is not valid.
pub fn wasm_binary_file(
&mut self,
file: &'a Path,
) -> Result<&mut CodeBuilder<'a>, Error>
pub fn wasm_binary_file( &mut self, file: &'a Path, ) -> Result<&mut CodeBuilder<'a>, Error>
Reads the file
specified for the WebAssembly bytes that are going to
be compiled.
This method will read file
from the filesystem and interpret it
as a WebAssembly binary.
A DWARF package file will be probed using the root of file
and with a
.dwp
extension. If found, it will be loaded and DWARF fusion
performed.
§Errors
This method will return an error if WebAssembly bytes have already been configured.
If file
can’t be read or an error happens reading it then that will
also be returned.
If DWARF fusion is performed and the DWARF packaged file cannot be read then an error will be returned.
pub fn wasm_binary_or_text_file(
&mut self,
file: &'a Path,
) -> Result<&mut CodeBuilder<'a>, Error>
pub fn wasm_binary_or_text_file( &mut self, file: &'a Path, ) -> Result<&mut CodeBuilder<'a>, Error>
Equivalent of CodeBuilder::wasm_binary_file
that also accepts the
WebAssembly text format.
This method is will read the file at path
and interpret the contents
to determine if it’s the wasm text format or binary format. The file
extension of file
is not consulted. The text format is automatically
converted to the binary format if the crate feature wat
is active.
§Errors
In addition to the errors returned by CodeBuilder::wasm_binary_file
this may also fail if the text format is read and the syntax is invalid.
pub fn dwarf_package_file(
&mut self,
file: &Path,
) -> Result<&mut CodeBuilder<'a>, Error>
pub fn dwarf_package_file( &mut self, file: &Path, ) -> Result<&mut CodeBuilder<'a>, Error>
Explicitly specify DWARF .dwp
path.
§Errors
This method will return an error if the .dwp
file has already been set
through CodeBuilder::dwarf_package
or auto-detection in
CodeBuilder::wasm_binary_file
.
This method will also return an error if file
cannot be read.
pub fn dwarf_package(
&mut self,
dwp_bytes: &'a [u8],
) -> Result<&mut CodeBuilder<'a>, Error>
pub fn dwarf_package( &mut self, dwp_bytes: &'a [u8], ) -> Result<&mut CodeBuilder<'a>, Error>
Set the DWARF package binary.
Initializes dwarf_package
from dwp_bytes
in preparation for
DWARF fusion. Allows the DWARF package to be supplied as a byte array
when the file probing performed in wasm_file
is not appropriate.
§Errors
Returns an error if the *.dwp
file is already set via auto-probing in
CodeBuilder::wasm_binary_file
or explicitly via
CodeBuilder::dwarf_package_file
.
pub fn hint(&self) -> Option<CodeHint>
pub fn hint(&self) -> Option<CodeHint>
Returns a hint, if possible, of what the provided bytes are.
This method can be use to detect what the previously supplied bytes to
methods such as CodeBuilder::wasm_binary_or_text
are. This will
return whether a module or a component was found in the provided bytes.
This method will return None
if wasm bytes have not been configured
or if the provided bytes don’t look like either a component or a
module.
pub fn compile_module_serialized(&self) -> Result<Vec<u8>, Error>
pub fn compile_module_serialized(&self) -> Result<Vec<u8>, Error>
Finishes this compilation and produces a serialized list of bytes.
This method requires that either CodeBuilder::wasm_binary
or
related methods were invoked prior to indicate what is being compiled.
This method will block the current thread until compilation has finished, and when done the serialized artifact will be returned.
Note that this method will never cache compilations, even if the
cache
feature is enabled.
§Errors
This can fail if the input wasm module was not valid or if another compilation-related error is encountered.
pub fn compile_component_serialized(&self) -> Result<Vec<u8>, Error>
pub fn compile_component_serialized(&self) -> Result<Vec<u8>, Error>
Same as CodeBuilder::compile_module_serialized
except that it
compiles a serialized Component
instead of a module.
§impl<'a> CodeBuilder<'a>
impl<'a> CodeBuilder<'a>
pub fn compile_module(&self) -> Result<Module, Error>
pub fn compile_module(&self) -> Result<Module, Error>
Same as CodeBuilder::compile_module_serialized
except that a
Module
is produced instead.
Note that this method will cache compilations if the cache
feature is
enabled and turned on in Config
.
pub fn compile_component(&self) -> Result<Component, Error>
pub fn compile_component(&self) -> Result<Component, Error>
Same as CodeBuilder::compile_module
except that it compiles a
Component
instead of a module.
Auto Trait Implementations§
impl<'a> Freeze for CodeBuilder<'a>
impl<'a> !RefUnwindSafe for CodeBuilder<'a>
impl<'a> Send for CodeBuilder<'a>
impl<'a> Sync for CodeBuilder<'a>
impl<'a> Unpin for CodeBuilder<'a>
impl<'a> !UnwindSafe for CodeBuilder<'a>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more