Merge master and add documentation.

lib/runtime-core/src/codegen.rs

@@ -1,3 +1,5 @@
+//! The codegen module provides common functions and data structures used by multiple backends
+//! during the code generation process.
 use crate::{
     backend::RunnableModule,
     backend::{Backend, CacheGen, Compiler, CompilerConfig, Features, Token},
@@ -18,22 +20,35 @@ use std::sync::{Arc, RwLock};
 use wasmparser::{self, WasmDecoder};
 use wasmparser::{Operator, Type as WpType};
 
+/// A type that defines a function pointer, which is called when breakpoints occur.
 pub type BreakpointHandler =
     Box<dyn Fn(BreakpointInfo) -> Result<(), Box<dyn Any>> + Send + Sync + 'static>;
+
+/// Maps instruction pointers to their breakpoint handlers.
 pub type BreakpointMap = Arc<HashMap<usize, BreakpointHandler>>;
 
+/// An event generated during parsing of a wasm binary
 #[derive(Debug)]
 pub enum Event<'a, 'b> {
+    /// An internal event created by the parser used to provide hooks during code generation.
     Internal(InternalEvent),
+    /// An event generated by parsing a wasm operator
     Wasm(&'b Operator<'a>),
+    /// An event generated by parsing a wasm operator that contains an owned `Operator`
     WasmOwned(Operator<'a>),
 }
 
+/// Kinds of `InternalEvent`s created during parsing.
 pub enum InternalEvent {
+    /// A function parse is about to begin.
     FunctionBegin(u32),
+    /// A function parsing has just completed.
     FunctionEnd,
+    /// A breakpoint emitted during parsing.
     Breakpoint(BreakpointHandler),
+    /// Indicates setting an internal field.
     SetInternal(u32),
+    /// Indicates getting an internal field.
     GetInternal(u32),
 }
 
@@ -49,10 +64,13 @@ impl fmt::Debug for InternalEvent {
     }
 }
 
+/// Information for a breakpoint
 pub struct BreakpointInfo<'a> {
+    /// Fault.
     pub fault: Option<&'a FaultInfo>,
 }
 
+/// A trait that represents the functions needed to be implemented to generate code for a module.
 pub trait ModuleCodeGenerator<FCG: FunctionCodeGenerator<E>, RM: RunnableModule, E: Debug> {
     /// Creates a new module code generator.
     fn new() -> Self;
@@ -66,7 +84,7 @@ pub trait ModuleCodeGenerator<FCG: FunctionCodeGenerator<E>, RM: RunnableModule,
     }
     /// Adds an import function.
     fn feed_import_function(&mut self) -> Result<(), E>;
-
+    /// Sets the signatures.
     fn feed_signatures(&mut self, signatures: Map<SigIndex, FuncSig>) -> Result<(), E>;
     /// Sets function signatures.
     fn feed_function_signatures(&mut self, assoc: Map<FuncIndex, SigIndex>) -> Result<(), E>;
@@ -81,6 +99,8 @@ pub trait ModuleCodeGenerator<FCG: FunctionCodeGenerator<E>, RM: RunnableModule,
     unsafe fn from_cache(cache: Artifact, _: Token) -> Result<ModuleInner, CacheError>;
 }
 
+/// A streaming compiler which is designed to generated code for a module based on a stream
+/// of wasm parser events.
 pub struct StreamingCompiler<
     MCG: ModuleCodeGenerator<FCG, RM, E>,
     FCG: FunctionCodeGenerator<E>,
@@ -95,6 +115,7 @@ pub struct StreamingCompiler<
     _phantom_e: PhantomData<E>,
 }
 
+/// A simple generator for a `StreamingCompiler`.
 pub struct SimpleStreamingCompilerGen<
     MCG: ModuleCodeGenerator<FCG, RM, E>,
     FCG: FunctionCodeGenerator<E>,
@@ -114,6 +135,7 @@ impl<
         E: Debug,
     > SimpleStreamingCompilerGen<MCG, FCG, RM, E>
 {
+    /// Create a new `StreamingCompiler`.
     pub fn new() -> StreamingCompiler<MCG, FCG, RM, E, impl Fn() -> MiddlewareChain> {
         StreamingCompiler::new(|| MiddlewareChain::new())
     }
@@ -127,6 +149,7 @@ impl<
         CGEN: Fn() -> MiddlewareChain,
     > StreamingCompiler<MCG, FCG, RM, E, CGEN>
 {
+    /// Create a new `StreamingCompiler` with the given `MiddlewareChain`.
     pub fn new(chain_gen: CGEN) -> Self {
         Self {
             middleware_chain_generator: chain_gen,
@@ -138,6 +161,7 @@ impl<
     }
 }
 
+/// Create a new `ValidatingParserConfig` with the given features.
 pub fn validating_parser_config(features: &Features) -> wasmparser::ValidatingParserConfig {
     wasmparser::ValidatingParserConfig {
         operator_config: wasmparser::OperatorValidatorConfig {
@@ -221,29 +245,35 @@ fn requires_pre_validation(backend: Backend) -> bool {
     }
 }
 
+/// A sink for parse events.
 pub struct EventSink<'a, 'b> {
     buffer: SmallVec<[Event<'a, 'b>; 2]>,
 }
 
 impl<'a, 'b> EventSink<'a, 'b> {
+    /// Push a new `Event` to this sink.
     pub fn push(&mut self, ev: Event<'a, 'b>) {
         self.buffer.push(ev);
     }
 }
 
+/// A container for a chain of middlewares.
 pub struct MiddlewareChain {
     chain: Vec<Box<dyn GenericFunctionMiddleware>>,
 }
 
 impl MiddlewareChain {
+    /// Create a new empty `MiddlewareChain`.
     pub fn new() -> MiddlewareChain {
         MiddlewareChain { chain: vec![] }
     }
 
+    /// Push a new `FunctionMiddleware` to this `MiddlewareChain`.
     pub fn push<M: FunctionMiddleware + 'static>(&mut self, m: M) {
         self.chain.push(Box::new(m));
     }
 
+    /// Run this chain with the provided function code generator, event and module info.
     pub(crate) fn run<E: Debug, FCG: FunctionCodeGenerator<E>>(
         &mut self,
         fcg: Option<&mut FCG>,
@@ -271,8 +301,11 @@ impl MiddlewareChain {
     }
 }
 
+/// A trait that represents the signature required to implement middleware for a function.
 pub trait FunctionMiddleware {
+    /// The error type for this middleware's functions.
     type Error: Debug;
+    /// Processes the given event, module info and sink.
     fn feed_event<'a, 'b: 'a>(
         &mut self,
         op: Event<'a, 'b>,