Added some docs + start to &mut self builder methods

Author: denismerigoux

src/librustc_codegen_llvm/builder.rs

@@ -64,7 +64,7 @@ impl BuilderMethods<'a, 'll, 'tcx>
         llfn: &'ll Value,
         name: &'b str
     ) -> Self {
-        let bx = Builder::with_cx(cx);
+        let mut bx = Builder::with_cx(cx);
         let llbb = unsafe {
             let name = SmallCStr::new(name);
             llvm::LLVMAppendBasicBlockInContext(
@@ -121,48 +121,48 @@ impl BuilderMethods<'a, 'll, 'tcx>
         }
     }
 
-    fn set_value_name(&self, value: &'ll Value, name: &str) {
+    fn set_value_name(&mut self, value: &'ll Value, name: &str) {
         let cname = SmallCStr::new(name);
         unsafe {
             llvm::LLVMSetValueName(value, cname.as_ptr());
         }
     }
 
-    fn position_at_end(&self, llbb: &'ll BasicBlock) {
+    fn position_at_end(&mut self, llbb: &'ll BasicBlock) {
         unsafe {
             llvm::LLVMPositionBuilderAtEnd(self.llbuilder, llbb);
         }
     }
 
-    fn position_at_start(&self, llbb: &'ll BasicBlock) {
+    fn position_at_start(&mut self, llbb: &'ll BasicBlock) {
         unsafe {
             llvm::LLVMRustPositionBuilderAtStart(self.llbuilder, llbb);
         }
     }
 
-    fn ret_void(&self) {
+    fn ret_void(&mut self) {
         self.count_insn("retvoid");
         unsafe {
             llvm::LLVMBuildRetVoid(self.llbuilder);
         }
     }
 
-    fn ret(&self, v: &'ll Value) {
+    fn ret(&mut self, v: &'ll Value) {
         self.count_insn("ret");
         unsafe {
             llvm::LLVMBuildRet(self.llbuilder, v);
         }
     }
 
-    fn br(&self, dest: &'ll BasicBlock) {
+    fn br(&mut self, dest: &'ll BasicBlock) {
         self.count_insn("br");
         unsafe {
             llvm::LLVMBuildBr(self.llbuilder, dest);
         }
     }
 
     fn cond_br(
-        &self,
+        &mut self,
         cond: &'ll Value,
         then_llbb: &'ll BasicBlock,
         else_llbb: &'ll BasicBlock,
@@ -446,7 +446,7 @@ impl BuilderMethods<'a, 'll, 'tcx>
     }
 
     fn alloca(&self, ty: &'ll Type, name: &str, align: Align) -> &'ll Value {
-        let bx = Builder::with_cx(self.cx);
+        let mut bx = Builder::with_cx(self.cx);
         bx.position_at_start(unsafe {
             llvm::LLVMGetFirstBasicBlock(self.llfn())
         });

src/librustc_codegen_llvm/intrinsic.rs

@@ -790,10 +790,10 @@ fn codegen_msvc_try(
 
         bx.set_personality_fn(bx.cx().eh_personality());
 
-        let normal = bx.build_sibling_block("normal");
+        let mut normal = bx.build_sibling_block("normal");
         let catchswitch = bx.build_sibling_block("catchswitch");
         let catchpad = bx.build_sibling_block("catchpad");
-        let caught = bx.build_sibling_block("caught");
+        let mut caught = bx.build_sibling_block("caught");
 
         let func = llvm::get_param(bx.llfn(), 0);
         let data = llvm::get_param(bx.llfn(), 1);
@@ -914,8 +914,8 @@ fn codegen_gnu_try(
         // expected to be `*mut *mut u8` for this to actually work, but that's
         // managed by the standard library.
 
-        let then = bx.build_sibling_block("then");
-        let catch = bx.build_sibling_block("catch");
+        let mut then = bx.build_sibling_block("then");
+        let mut catch = bx.build_sibling_block("catch");
 
         let func = llvm::get_param(bx.llfn(), 0);
         let data = llvm::get_param(bx.llfn(), 1);

src/librustc_codegen_llvm/lib.rs

@@ -129,7 +129,7 @@ mod value;
 
 pub struct LlvmCodegenBackend(());
 
-impl BackendMethods for LlvmCodegenBackend {
+impl ExtraBackendMethods for LlvmCodegenBackend {
     type Metadata = ModuleLlvm;
     type OngoingCodegen = OngoingCodegen;
 

src/librustc_codegen_ssa/base.rs

@@ -535,7 +535,7 @@ pub fn maybe_create_entry_wrapper<'a, 'll: 'a, 'tcx: 'll, Bx: BuilderMethods<'a,
         cx.set_frame_pointer_elimination(llfn);
         cx.apply_target_cpu_attr(llfn);
 
-        let bx = Bx::new_block(&cx, llfn, "top");
+        let mut bx = Bx::new_block(&cx, llfn, "top");
 
         bx.insert_reference_to_gdb_debug_scripts_section_global();
 
@@ -571,7 +571,7 @@ pub const CODEGEN_WORK_PACKAGE_KIND: time_graph::WorkPackageKind =
     time_graph::WorkPackageKind(&["#DE9597", "#FED1D3", "#FDC5C7", "#B46668", "#88494B"]);
 
 
-pub fn codegen_crate<B : BackendMethods>(
+pub fn codegen_crate<B : ExtraBackendMethods>(
     backend: B,
     tcx: TyCtxt<'ll, 'tcx, 'tcx>,
     rx: mpsc::Receiver<Box<dyn Any + Send>>

src/librustc_codegen_ssa/interfaces/backend.rs

@@ -11,6 +11,7 @@
 use super::CodegenObject;
 use {ModuleCodegen, CachedModuleCodegen};
 use rustc::session::Session;
+use rustc_codegen_utils::codegen_backend::CodegenBackend;
 use rustc::middle::cstore::EncodedMetadata;
 use rustc::middle::allocator::AllocatorKind;
 use rustc::ty::TyCtxt;
@@ -27,7 +28,7 @@ pub trait Backend<'ll> {
     type Context;
 }
 
-pub trait BackendMethods {
+pub trait ExtraBackendMethods : CodegenBackend {
     type Metadata;
     type OngoingCodegen;
 

src/librustc_codegen_ssa/interfaces/builder.rs

@@ -50,14 +50,14 @@ pub trait BuilderMethods<'a, 'll :'a, 'tcx: 'll> : HasCodegen<'a, 'll, 'tcx> +
     fn llbb(&self) -> <Self::CodegenCx as Backend<'ll>>::BasicBlock;
     fn count_insn(&self, category: &str);
 
-    fn set_value_name(&self, value: <Self::CodegenCx as Backend<'ll>>::Value, name: &str);
-    fn position_at_end(&self, llbb: <Self::CodegenCx as Backend<'ll>>::BasicBlock);
-    fn position_at_start(&self, llbb: <Self::CodegenCx as Backend<'ll>>::BasicBlock);
-    fn ret_void(&self);
-    fn ret(&self, v: <Self::CodegenCx as Backend<'ll>>::Value);
-    fn br(&self, dest: <Self::CodegenCx as Backend<'ll>>::BasicBlock);
+    fn set_value_name(&mut self, value: <Self::CodegenCx as Backend<'ll>>::Value, name: &str);
+    fn position_at_end(&mut self, llbb: <Self::CodegenCx as Backend<'ll>>::BasicBlock);
+    fn position_at_start(&mut self, llbb: <Self::CodegenCx as Backend<'ll>>::BasicBlock);
+    fn ret_void(&mut self);
+    fn ret(&mut self, v: <Self::CodegenCx as Backend<'ll>>::Value);
+    fn br(&mut self, dest: <Self::CodegenCx as Backend<'ll>>::BasicBlock);
     fn cond_br(
-        &self,
+        &mut self,
         cond: <Self::CodegenCx as Backend<'ll>>::Value,
         then_llbb: <Self::CodegenCx as Backend<'ll>>::BasicBlock,
         else_llbb: <Self::CodegenCx as Backend<'ll>>::BasicBlock,

src/librustc_codegen_ssa/interfaces/mod.rs

@@ -8,6 +8,22 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Interface of a Rust codegen backend
+//!
+//! This crate defines all the traits that have to be implemented by a codegen backend in order to
+//! use the backend-agnostic codegen code in `rustc_codegen_ssa`.
+//!
+//! The interface is designed around two backend-specific data structures, the codegen context and
+//! the builder. The codegen context is supposed to be read-only after its creation and during the
+//! actual codegen, while the builder stores the information about the function during codegen and
+//! is used to produce the instructions of the backend IR.
+//!
+//! Finaly, a third `Backend` structure has to implement methods related to how codegen information
+//! is passed to the backend, especially for asynchronous compilation.
+//!
+//! The traits contain associated types that are backend-specific, such as the backend's value or
+//! basic blocks.
+
 use std::fmt;
 mod backend;
 mod misc;
@@ -21,7 +37,7 @@ mod debuginfo;
 mod abi;
 mod asm;
 
-pub use self::backend::{Backend, BackendMethods};
+pub use self::backend::{Backend, ExtraBackendMethods};
 pub use self::misc::MiscMethods;
 pub use self::statics::StaticMethods;
 pub use self::declare::{DeclareMethods, PreDefineMethods};

src/librustc_codegen_ssa/lib.rs

@@ -8,10 +8,6 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! # Note
-//!
-//! This API is completely unstable and subject to change.
-
 #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
       html_favicon_url = "https://doc.rust-lang.org/favicon.ico",
       html_root_url = "https://doc.rust-lang.org/nightly/")]
@@ -28,6 +24,10 @@
 #![allow(dead_code)]
 #![feature(quote)]
 
+//! This crate contains codegen code that is used by all codegen backends (LLVM and others).
+//! The backend-agnostic functions of this crate use functions defined in various traits that
+//! have to be implemented by each backends.
+
 #[macro_use] extern crate bitflags;
 #[macro_use] extern crate log;
 extern crate rustc_apfloat;

src/librustc_codegen_ssa/mir/block.rs

@@ -102,7 +102,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
         };
 
         let funclet_br =
-            |this: &mut Self, bx: &Bx, target: mir::BasicBlock| {
+            |this: &mut Self, bx: &mut Bx, target: mir::BasicBlock| {
                 let (lltarget, is_cleanupret) = lltarget(this, target);
                 if is_cleanupret {
                     // micro-optimization: generate a `ret` rather than a jump
@@ -115,7 +115,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
 
         let do_call = |
             this: &mut Self,
-            bx: &Bx,
+            bx: &mut Bx,
             fn_ty: FnType<'tcx, Ty<'tcx>>,
             fn_ptr: Cx::Value,
             llargs: &[Cx::Value],
@@ -191,7 +191,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
             }
 
             mir::TerminatorKind::Goto { target } => {
-                funclet_br(self, &bx, target);
+                funclet_br(self, &mut bx, target);
             }
 
             mir::TerminatorKind::SwitchInt { ref discr, switch_ty, ref values, ref targets } => {
@@ -293,7 +293,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
 
                 if let ty::InstanceDef::DropGlue(_, None) = drop_fn.def {
                     // we don't actually need to drop anything.
-                    funclet_br(self, &bx, target);
+                    funclet_br(self, &mut bx, target);
                     return
                 }
 
@@ -323,7 +323,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
                          bx.cx().fn_type_of_instance(&drop_fn))
                     }
                 };
-                do_call(self, &bx, fn_ty, drop_fn, args,
+                do_call(self, &mut bx, fn_ty, drop_fn, args,
                         Some((ReturnDest::Nothing, target)),
                         unwind);
             }
@@ -347,7 +347,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
 
                 // Don't codegen the panic block if success if known.
                 if const_cond == Some(expected) {
-                    funclet_br(self, &bx, target);
+                    funclet_br(self, &mut bx, target);
                     return;
                 }
 
@@ -418,7 +418,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
                 let llfn = bx.cx().get_fn(instance);
 
                 // Codegen the actual panic invoke/call.
-                do_call(self, &bx, fn_ty, llfn, &args, None, cleanup);
+                do_call(self, &mut bx, fn_ty, llfn, &args, None, cleanup);
             }
 
             mir::TerminatorKind::DropAndReplace { .. } => {
@@ -468,7 +468,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
                     if let Some(destination_ref) = destination.as_ref() {
                         let &(ref dest, target) = destination_ref;
                         self.codegen_transmute(&bx, &args[0], dest);
-                        funclet_br(self, &bx, target);
+                        funclet_br(self, &mut bx, target);
                     } else {
                         // If we are trying to transmute to an uninhabited type,
                         // it is likely there is no allotted destination. In fact,
@@ -495,7 +495,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
                     Some(ty::InstanceDef::DropGlue(_, None)) => {
                         // empty drop glue - a nop.
                         let &(_, target) = destination.as_ref().unwrap();
-                        funclet_br(self, &bx, target);
+                        funclet_br(self, &mut bx, target);
                         return;
                     }
                     _ => bx.cx().new_fn_type(sig, &extra_args)
@@ -541,7 +541,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
                     // Codegen the actual panic invoke/call.
                     do_call(
                         self,
-                        &bx,
+                        &mut bx,
                         fn_ty,
                         llfn,
                         &[msg_file_line_col],
@@ -639,7 +639,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
                     }
 
                     if let Some((_, target)) = *destination {
-                        funclet_br(self, &bx, target);
+                        funclet_br(self, &mut bx, target);
                     } else {
                         bx.unreachable();
                     }
@@ -731,7 +731,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
                     _ => span_bug!(span, "no llfn for call"),
                 };
 
-                do_call(self, &bx, fn_ty, fn_ptr, &llargs,
+                do_call(self, &mut bx, fn_ty, fn_ptr, &llargs,
                         destination.as_ref().map(|&(_, target)| (ret_dest, target)),
                         cleanup);
             }
@@ -903,7 +903,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
             span_bug!(self.mir.span, "landing pad was not inserted?")
         }
 
-        let bx : Bx = self.new_block("cleanup");
+        let mut bx : Bx = self.new_block("cleanup");
 
         let llpersonality = self.cx.eh_personality();
         let llretty = self.landing_pad_type();
@@ -942,7 +942,7 @@ impl<'a, 'f, 'll: 'a + 'f, 'tcx: 'll, Cx: CodegenMethods<'ll, 'tcx>>
         &self,
         bb: mir::BasicBlock
     ) -> Bx {
-        let bx = Bx::with_cx(self.cx);
+        let mut bx = Bx::with_cx(self.cx);
         bx.position_at_end(self.blocks[bb]);
         bx
     }