@@ -51,42 +51,69 @@ fn declare_raw_fn(
5151 llfn
5252}
5353
54- impl DeclareMethods < ' tcx > for CodegenCx < ' ll , ' tcx > {
55- fn declare_global ( & self , name : & str , ty : & ' ll Type ) -> & ' ll Value {
54+ impl CodegenCx < ' ll , ' tcx > {
55+ /// Declare a global value.
56+ ///
57+ /// If there’s a value with the same name already declared, the function will
58+ /// return its Value instead.
59+ pub fn declare_global ( & self , name : & str , ty : & ' ll Type ) -> & ' ll Value {
5660 debug ! ( "declare_global(name={:?})" , name) ;
5761 unsafe { llvm:: LLVMRustGetOrInsertGlobal ( self . llmod , name. as_ptr ( ) . cast ( ) , name. len ( ) , ty) }
5862 }
5963
60- fn declare_cfn ( & self , name : & str , fn_type : & ' ll Type ) -> & ' ll Value {
64+ /// Declare a C ABI function.
65+ ///
66+ /// Only use this for foreign function ABIs and glue. For Rust functions use
67+ /// `declare_fn` instead.
68+ ///
69+ /// If there’s a value with the same name already declared, the function will
70+ /// update the declaration and return existing Value instead.
71+ pub fn declare_cfn ( & self , name : & str , fn_type : & ' ll Type ) -> & ' ll Value {
6172 declare_raw_fn ( self , name, llvm:: CCallConv , fn_type)
6273 }
6374
64- fn declare_fn ( & self , name : & str , fn_abi : & FnAbi < ' tcx , Ty < ' tcx > > ) -> & ' ll Value {
75+ /// Declare a Rust function.
76+ ///
77+ /// If there’s a value with the same name already declared, the function will
78+ /// update the declaration and return existing Value instead.
79+ pub fn declare_fn ( & self , name : & str , fn_abi : & FnAbi < ' tcx , Ty < ' tcx > > ) -> & ' ll Value {
6580 debug ! ( "declare_rust_fn(name={:?}, fn_abi={:?})" , name, fn_abi) ;
6681
6782 let llfn = declare_raw_fn ( self , name, fn_abi. llvm_cconv ( ) , fn_abi. llvm_type ( self ) ) ;
6883 fn_abi. apply_attrs_llfn ( self , llfn) ;
6984 llfn
7085 }
7186
72- fn define_global ( & self , name : & str , ty : & ' ll Type ) -> Option < & ' ll Value > {
87+ /// Declare a global with an intention to define it.
88+ ///
89+ /// Use this function when you intend to define a global. This function will
90+ /// return `None` if the name already has a definition associated with it. In that
91+ /// case an error should be reported to the user, because it usually happens due
92+ /// to user’s fault (e.g., misuse of `#[no_mangle]` or `#[export_name]` attributes).
93+ pub fn define_global ( & self , name : & str , ty : & ' ll Type ) -> Option < & ' ll Value > {
7394 if self . get_defined_value ( name) . is_some ( ) {
7495 None
7596 } else {
7697 Some ( self . declare_global ( name, ty) )
7798 }
7899 }
79100
80- fn define_private_global ( & self , ty : & ' ll Type ) -> & ' ll Value {
101+ /// Declare a private global
102+ ///
103+ /// Use this function when you intend to define a global without a name.
104+ pub fn define_private_global ( & self , ty : & ' ll Type ) -> & ' ll Value {
81105 unsafe { llvm:: LLVMRustInsertPrivateGlobal ( self . llmod , ty) }
82106 }
83107
84- fn get_declared_value ( & self , name : & str ) -> Option < & ' ll Value > {
108+ /// Gets declared value by name.
109+ pub fn get_declared_value ( & self , name : & str ) -> Option < & ' ll Value > {
85110 debug ! ( "get_declared_value(name={:?})" , name) ;
86111 unsafe { llvm:: LLVMRustGetNamedValue ( self . llmod , name. as_ptr ( ) . cast ( ) , name. len ( ) ) }
87112 }
88113
89- fn get_defined_value ( & self , name : & str ) -> Option < & ' ll Value > {
114+ /// Gets defined or externally defined (AvailableExternally linkage) value by
115+ /// name.
116+ pub fn get_defined_value ( & self , name : & str ) -> Option < & ' ll Value > {
90117 self . get_declared_value ( name) . and_then ( |val| {
91118 let declaration = unsafe { llvm:: LLVMIsDeclaration ( val) != 0 } ;
92119 if !declaration { Some ( val) } else { None }
0 commit comments