Introduce Builder and Product types to the Module workflow.

This eliminates API confusion and surface area with respect to what state
the `Backend` needs to be in at different points.

Now, API users will construct a `Builder`, and pass it into the `Module`
which uses it to constrct a `Backend`. The `Backend` instance only lives
inside the `Module`. And when finished, the `Module` can return a
`Product` back to the user providing any outputs it has.

lib/faerie/src/backend.rs

@@ -11,19 +11,18 @@ use failure::Error;
 use std::fs::File;
 use target;
 
-pub struct FaerieCompiledFunction {}
+/// A builder for `FaerieBackend`.
-
+pub struct FaerieBuilder {
-pub struct FaerieCompiledData {}
-
-/// A `FaerieBackend` implements `Backend` and emits ".o" files using the `faerie` library.
-pub struct FaerieBackend {
     isa: Box<TargetIsa>,
-    artifact: faerie::Artifact,
+    name: String,
     format: container::Format,
+    faerie_target: faerie::Target,
 }
 
-impl FaerieBackend {
+impl FaerieBuilder {
-    /// Create a new `FaerieBackend` using the given Cretonne target.
+    /// Create a new `FaerieBuilder` using the given Cretonne target, that
+    /// can be passed to
+    /// [`Module::new`](cretonne_module/struct.Module.html#method.new].
     pub fn new(
         isa: Box<TargetIsa>,
         name: String,
@@ -33,34 +32,27 @@ impl FaerieBackend {
         let faerie_target = target::translate(&*isa)?;
         Ok(Self {
             isa,
-            artifact: faerie::Artifact::new(faerie_target, name),
+            name,
             format,
+            faerie_target,
         })
     }
-
-    /// Return the name of the output file. This is the name passed into `new`.
-    pub fn name(&self) -> &str {
-        &self.artifact.name
-    }
-
-    /// Call `emit` on the faerie `Artifact`, producing bytes in memory.
-    pub fn emit(&self) -> Result<Vec<u8>, Error> {
-        match self.format {
-            container::Format::ELF => self.artifact.emit::<faerie::Elf>(),
-            container::Format::MachO => self.artifact.emit::<faerie::Mach>(),
-        }
-    }
-
-    /// Call `write` on the faerie `Artifact`, writing to a file.
-    pub fn write(&self, sink: File) -> Result<(), Error> {
-        match self.format {
-            container::Format::ELF => self.artifact.write::<faerie::Elf>(sink),
-            container::Format::MachO => self.artifact.write::<faerie::Mach>(sink),
-        }
-    }
 }
 
+/// A `FaerieBackend` implements `Backend` and emits ".o" files using the `faerie` library.
+pub struct FaerieBackend {
+    isa: Box<TargetIsa>,
+    artifact: faerie::Artifact,
+    format: container::Format,
+}
+
+pub struct FaerieCompiledFunction {}
+
+pub struct FaerieCompiledData {}
+
 impl Backend for FaerieBackend {
+    type Builder = FaerieBuilder;
+
     type CompiledFunction = FaerieCompiledFunction;
     type CompiledData = FaerieCompiledData;
 
@@ -69,6 +61,19 @@ impl Backend for FaerieBackend {
     type FinalizedFunction = ();
     type FinalizedData = ();
 
+    /// The returned value here provides functions for emitting object files
+    /// to memory and files.
+    type Product = FaerieProduct;
+
+    /// Create a new `FaerieBackend` using the given Cretonne target.
+    fn new(builder: FaerieBuilder) -> Self {
+        Self {
+            isa: builder.isa,
+            artifact: faerie::Artifact::new(builder.faerie_target, builder.name),
+            format: builder.format,
+        }
+    }
+
     fn isa(&self) -> &TargetIsa {
         &*self.isa
     }
@@ -216,6 +221,44 @@ impl Backend for FaerieBackend {
     fn finalize_data(&mut self, _data: &FaerieCompiledData, _namespace: &ModuleNamespace<Self>) {
         // Nothing to do.
     }
+
+    fn finish(self) -> FaerieProduct {
+        FaerieProduct {
+            artifact: self.artifact,
+            format: self.format,
+        }
+    }
+}
+
+/// This is the output of `Module`'s
+/// [`finish`](../cretonne_module/struct.Module.html#method.finish) function.
+/// It provides functions for writing out the object file to memory or a file.
+pub struct FaerieProduct {
+    artifact: faerie::Artifact,
+    format: container::Format,
+}
+
+impl FaerieProduct {
+    /// Return the name of the output file. This is the name passed into `new`.
+    pub fn name(&self) -> &str {
+        &self.artifact.name
+    }
+
+    /// Call `emit` on the faerie `Artifact`, producing bytes in memory.
+    pub fn emit(&self) -> Result<Vec<u8>, Error> {
+        match self.format {
+            container::Format::ELF => self.artifact.emit::<faerie::Elf>(),
+            container::Format::MachO => self.artifact.emit::<faerie::Mach>(),
+        }
+    }
+
+    /// Call `write` on the faerie `Artifact`, writing to a file.
+    pub fn write(&self, sink: File) -> Result<(), Error> {
+        match self.format {
+            container::Format::ELF => self.artifact.write::<faerie::Elf>(sink),
+            container::Format::MachO => self.artifact.write::<faerie::Mach>(sink),
+        }
+    }
 }
 
 fn translate_function_linkage(linkage: Linkage) -> faerie::Decl {

lib/faerie/src/lib.rs

@@ -29,5 +29,5 @@ mod backend;
 mod container;
 mod target;
 
-pub use backend::FaerieBackend;
+pub use backend::{FaerieBuilder, FaerieBackend};
 pub use container::Format;

lib/module/src/backend.rs

@@ -14,6 +14,9 @@ pub trait Backend
 where
     Self: marker::Sized,
 {
+    /// A builder for constructing `Backend` instances.
+    type Builder;
+
     /// The results of compiling a function.
     type CompiledFunction;
 
@@ -21,13 +24,21 @@ where
     type CompiledData;
 
     /// The completed output artifact for a function, if this is meaningful for
-    /// the Backend.
+    /// the `Backend`.
     type FinalizedFunction;
 
     /// The completed output artifact for a data object, if this is meaningful for
-    /// the Backend.
+    /// the `Backend`.
     type FinalizedData;
 
+    /// This is an object returned by `Module`'s
+    /// [`finish`](struct.Module.html#method.finish) function,
+    /// if the `Backend` has a purpose for this.
+    type Product;
+
+    /// Create a new `Backend` instance.
+    fn new(Self::Builder) -> Self;
+
     /// Return the `TargetIsa` to compile for.
     fn isa(&self) -> &TargetIsa;
 
@@ -94,4 +105,8 @@ where
         data: &Self::CompiledData,
         namespace: &ModuleNamespace<Self>,
     ) -> Self::FinalizedData;
+
+    /// Consume this `Backend` and return a result. Some implementations may
+    /// provide additional functionality through this result.
+    fn finish(self) -> Self::Product;
 }

lib/module/src/module.rs

@@ -236,14 +236,14 @@ where
     B: Backend,
 {
     /// Create a new `Module`.
-    pub fn new(backend: B) -> Self {
+    pub fn new(backend_builder: B::Builder) -> Self {
         Self {
             names: HashMap::new(),
             contents: ModuleContents {
                 functions: PrimaryMap::new(),
                 data_objects: PrimaryMap::new(),
             },
-            backend,
+            backend: B::new(backend_builder),
         }
     }
 
@@ -532,10 +532,10 @@ where
         }
     }
 
-    /// Consume the module and return its contained `Backend`. Some `Backend`
+    /// Consume the module and return the resulting `Product`. Some `Backend`
-    /// implementations have additional features not available through the
+    /// implementations may provide additional functionality available after
-    /// `Module` interface.
+    /// a `Module` is complete.
-    pub fn consume(self) -> B {
+    pub fn finish(self) -> B::Product {
-        self.backend
+        self.backend.finish()
     }
 }

lib/simplejit/src/backend.rs

@@ -12,6 +12,43 @@ use std::ptr;
 use libc;
 use memory::Memory;
 
+/// A builder for `SimpleJITBackend`.
+pub struct SimpleJITBuilder {
+    isa: Box<TargetIsa>,
+}
+
+impl SimpleJITBuilder {
+    /// Create a new `SimpleJITBuilder`.
+    pub fn new() -> Self {
+        let (flag_builder, isa_builder) = cretonne_native::builders().unwrap_or_else(|_| {
+            panic!("host machine is not a supported target");
+        });
+        let isa = isa_builder.finish(settings::Flags::new(&flag_builder));
+        Self::with_isa(isa)
+    }
+
+    /// Create a new `SimpleJITBuilder` with an arbitrary target. This is mainly
+    /// useful for testing.
+    ///
+    /// SimpleJIT requires a `TargetIsa` configured for non-PIC.
+    ///
+    /// To create a `SimpleJITBuilder` for native use, use the `new` constructor
+    /// instead.
+    pub fn with_isa(isa: Box<TargetIsa>) -> Self {
+        debug_assert!(!isa.flags().is_pic(), "SimpleJIT requires non-PIC code");
+        Self { isa }
+    }
+}
+
+/// A `SimpleJITBackend` implements `Backend` and emits code and data into memory where it can be
+/// directly called and accessed.
+pub struct SimpleJITBackend {
+    isa: Box<TargetIsa>,
+    code_memory: Memory,
+    readonly_memory: Memory,
+    writable_memory: Memory,
+}
+
 /// A record of a relocation to perform.
 struct RelocRecord {
     offset: CodeOffset,
@@ -32,49 +69,34 @@ pub struct SimpleJITCompiledData {
     relocs: Vec<RelocRecord>,
 }
 
-/// A `SimpleJITBackend` implements `Backend` and emits code and data into memory where it can be
+impl<'simple_jit_backend> Backend for SimpleJITBackend {
-/// directly called and accessed.
+    type Builder = SimpleJITBuilder;
-pub struct SimpleJITBackend {
+
-    isa: Box<TargetIsa>,
+    /// SimpleJIT compiled function and data objects may have outstanding
-    code_memory: Memory,
+    /// relocations that need to be performed before the memory can be used.
-    readonly_memory: Memory,
+    /// These relocations are performed within `finalize_function` and
-    writable_memory: Memory,
+    /// `finalize_data`.
-}
+    type CompiledFunction = SimpleJITCompiledFunction;
+    type CompiledData = SimpleJITCompiledData;
+
+    /// SimpleJIT emits code and data into memory, and provides raw pointers
+    /// to them.
+    type FinalizedFunction = *const u8;
+    type FinalizedData = (*mut u8, usize);
+
+    /// SimpleJIT emits code and data into memory as it processes them, so it
+    /// doesn't need to provide anything after the `Module` is complete.
+    type Product = ();
 
-impl SimpleJITBackend {
     /// Create a new `SimpleJITBackend`.
-    pub fn new() -> Self {
+    fn new(builder: SimpleJITBuilder) -> Self {
-        let (flag_builder, isa_builder) = cretonne_native::builders().unwrap_or_else(|_| {
-            panic!("host machine is not a supported target");
-        });
-        let isa = isa_builder.finish(settings::Flags::new(&flag_builder));
-        Self::with_isa(isa)
-    }
-
-    /// Create a new `SimpleJITBackend` with an arbitrary target. This is mainly
-    /// useful for testing.
-    ///
-    /// SimpleJIT requires a `TargetIsa` configured for non-PIC.
-    ///
-    /// To create a `SimpleJITBackend` for native use, use the `new` constructor
-    /// instead.
-    pub fn with_isa(isa: Box<TargetIsa>) -> Self {
-        debug_assert!(!isa.flags().is_pic(), "SimpleJIT requires non-PIC code");
         Self {
-            isa,
+            isa: builder.isa,
             code_memory: Memory::new(),
             readonly_memory: Memory::new(),
             writable_memory: Memory::new(),
         }
     }
-}
-
-impl<'simple_jit_backend> Backend for SimpleJITBackend {
-    type CompiledFunction = SimpleJITCompiledFunction;
-    type CompiledData = SimpleJITCompiledData;
-
-    type FinalizedFunction = *const u8;
-    type FinalizedData = (*mut u8, usize);
 
     fn isa(&self) -> &TargetIsa {
         &*self.isa
@@ -317,6 +339,10 @@ impl<'simple_jit_backend> Backend for SimpleJITBackend {
         self.readonly_memory.set_readonly();
         (data.storage, data.size)
     }
+
+    /// SimpleJIT emits code and data into memory as it processes them, so it
+    /// doesn't need to provide anything after the `Module` is complete.
+    fn finish(self) -> () {}
 }
 
 fn lookup_with_dlsym(name: &str) -> *const u8 {

lib/simplejit/src/lib.rs

@@ -26,4 +26,4 @@ extern crate libc;
 mod backend;
 mod memory;
 
-pub use backend::SimpleJITBackend;
+pub use backend::{SimpleJITBuilder, SimpleJITBackend};