T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rewrote doc with @sunfishcode's comments in mind

Browse Source
This commit is contained in:
Denis Merigoux
2018-08-06 11:06:42 +02:00
committed by Dan Gohman
parent 73511435d0
commit b7d2df9307
1 changed files with 18 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
lib/frontend/src/lib.rs
View File

@@ -6,35 +6,38 @@
//! To get started, create an [`FunctionBuilderContext`](struct.FunctionBuilderContext.html) and
//! pass it as an argument to a [`FunctionBuilder`](struct.FunctionBuilder.html).
//!
//! # Source Language Variables and Cranelift IR values
//! # Mutable variables and Cranelift IR values
//!
//! The most interesting feature of this API is that it provides a single way to deal with all your
//! variable problems. Indeed, the [`FunctionBuilder`](struct.FunctionBuilder.html) struct has a
//! type parameter `Variable` that should be instantiated with the type of your Source Language
//! Variables (SLV). Then, through calling the functions
//! type parameter `Variable` that should be instantiated with the type of your source language
//! variables. Then, through calling the functions
//! [`declare_var`](struct.FunctionBuilder.html#method.declare_var),
//! [`def_var`](struct.FunctionBuilder.html#method.def_var) and
//! [`use_var`](struct.FunctionBuilder.html#method.use_var), the
//! [`FunctionBuilder`](struct.FunctionBuilder.html) will create for you all the Cranelift IR
//! values corresponding to your SLVs.
//! values corresponding to your variables.
//!
//! If a SLV is immutable (defined only once), then it will get mapped to one and only Cranelift IR
//! value. If a SLV is mutable ([`def_var`](struct.FunctionBuilder.html#method.def_var) multiple
//! times), then internally a [`SSA`](https://en.wikipedia.org/wiki/Static_single_assignment_form)
//! construction algorithm will automatically create multiple Cranelift IR values that will be
//! returned to you by [`use_var`](struct.FunctionBuilder.html#method.use_var) depending on where
//! you want to use your SLV.
//! This API has been designed to help you translate your mutable variables into
//! [`SSA`](https://en.wikipedia.org/wiki/Static_single_assignment_form) form.
//! [`use_var`](struct.FunctionBuilder.html#method.use_var) will returns the Cranelift IR value
//! that corresponds to your mutable variable at a precise point in the program. However, you know
//! beforehand that one of your variables is defined only once, for instance if it is the result
//! of an intermediate expression in an expression-based language, then you can translate it
//! directly by the Cranelift IR value returned by the instruction builder. Using the
//! [`use_var`](struct.FunctionBuilder.html#method.use_var) API for such an immutable variable
//! would also work but with a slight additional overhead (the SSA algorithm does not know
//! beforehand if a variable is immutable or not).
//!
//! The morality is that you should use these three functions to handle all your SLVs, even those
//! that are not present in the source code but artefacts of the translation. For instance, if your
//! source language is expression-based, then you will need to introduce artifical SLVs to store
//! intermediate results of the computation of your expressions. Hence The `Variable` type that you
//!
//! The moral is that you should use these three functions to handle all your mutable variables, even those
//! that are not present in the source code but artefacts of the translation. Hence The `Variable` type that you
//! would pass to [`FunctionBuilder`](struct.FunctionBuilder.html) could look like this
//!
//! ```
//! enum Variable {
//! OriginalSourceVariable(String),
//! IntermediateExpressionVariable(u32)
//! TranslationArtefact(u32)
//! }
//! ```
//!