Trans nomenclature tidy-up: upcall vs. native vs. extern.

1 files changed, 54 insertions, 35 deletions

diff --git a/src/comp/middle/trans.rs b/src/comp/middle/trans.rs
index f5fcf587612..fa389c73073 100644
--- a/src/comp/middle/trans.rs
+++ b/src/comp/middle/trans.rs
@@ -53,8 +53,8 @@ state obj namegen(mutable int i) {
 type glue_fns = rec(ValueRef activate_glue,
                     ValueRef yield_glue,
                     ValueRef exit_task_glue,
-                    vec[ValueRef] upcall_glues_rust,
-                    vec[ValueRef] upcall_glues_cdecl,
+                    vec[ValueRef] native_glues_rust,
+                    vec[ValueRef] native_glues_cdecl,
                     ValueRef no_op_type_glue,
                     ValueRef memcpy_glue,
                     ValueRef bzero_glue,
@@ -64,12 +64,31 @@ type tydesc_info = rec(ValueRef tydesc,
                        ValueRef take_glue,
                        ValueRef drop_glue);
 
+/*
+ * A note on nomenclature of linking: "upcall", "extern" and "native".
+ *
+ * An "extern" is an LLVM symbol we wind up emitting an undefined external
+ * reference to. This means "we don't have the thing in this compilation unit,
+ * please make sure you link it in at runtime". This could be a reference to
+ * C code found in a C library, or rust code found in a rust crate.
+ *
+ * A "native" is a combination of an extern that references C code, plus a
+ * glue-code stub that "looks like" a rust function, emitted here, plus a
+ * generic N-ary bit of asm glue (found over in back/x86.rs) that performs a
+ * control transfer into C from rust. Natives may be normal C library code.
+ *
+ * An upcall is a native call generated by the compiler (not corresponding to
+ * any user-written call in the code) into librustrt, to perform some helper
+ * task such as bringing a task to life, allocating memory, etc.
+ *
+ */
+
 state type crate_ctxt = rec(session.session sess,
                             ModuleRef llmod,
                             target_data td,
                             type_names tn,
                             ValueRef crate_ptr,
-                            hashmap[str, ValueRef] upcalls,
+                            hashmap[str, ValueRef] externs,
                             hashmap[str, ValueRef] intrinsics,
                             hashmap[str, ValueRef] item_names,
                             hashmap[ast.def_id, ValueRef] item_ids,
@@ -852,14 +871,14 @@ fn decl_glue(ModuleRef llmod, type_names tn, str s) -> ValueRef {
     ret decl_cdecl_fn(llmod, s, T_fn(vec(T_taskptr(tn)), T_void()));
 }
 
-fn decl_upcall_glue(ModuleRef llmod, type_names tn,
+fn decl_native_glue(ModuleRef llmod, type_names tn,
                     bool pass_task, uint _n) -> ValueRef {
     // It doesn't actually matter what type we come up with here, at the
-    // moment, as we cast the upcall function pointers to int before passing
-    // them to the indirect upcall-invocation glue.  But eventually we'd like
+    // moment, as we cast the native function pointers to int before passing
+    // them to the indirect native-invocation glue.  But eventually we'd like
     // to call them directly, once we have a calling convention worked out.
     let int n = _n as int;
-    let str s = abi.upcall_glue_name(n, pass_task);
+    let str s = abi.native_glue_name(n, pass_task);
     let vec[TypeRef] args = vec(T_int()); // callee
     if (!pass_task) {
         args += vec(T_int()); // taskptr, will not be passed
@@ -869,15 +888,15 @@ fn decl_upcall_glue(ModuleRef llmod, type_names tn,
     ret decl_fastcall_fn(llmod, s, T_fn(args, T_int()));
 }
 
-fn get_upcall(&hashmap[str, ValueRef] upcalls,
+fn get_extern(&hashmap[str, ValueRef] externs,
               ModuleRef llmod, str name, int n_args) -> ValueRef {
-    if (upcalls.contains_key(name)) {
-        ret upcalls.get(name);
+    if (externs.contains_key(name)) {
+        ret externs.get(name);
     }
     auto inputs = _vec.init_elt[TypeRef](T_int(), n_args as uint);
     auto output = T_int();
     auto f = decl_cdecl_fn(llmod, name, T_fn(inputs, output));
-    upcalls.insert(name, f);
+    externs.insert(name, f);
     ret f;
 }
 
@@ -885,26 +904,26 @@ fn trans_upcall(@block_ctxt cx, str name, vec[ValueRef] args) -> result {
     auto cxx = cx.fcx.ccx;
     auto lltaskptr = cx.build.PtrToInt(cx.fcx.lltaskptr, T_int());
     auto args2 = vec(lltaskptr) + args;
-    auto t = trans_upcall2(cx.build, cxx.glues, lltaskptr,
-                           cxx.upcalls, cxx.tn, cxx.llmod, name, true, args2);
+    auto t = trans_native(cx.build, cxx.glues, lltaskptr,
+                          cxx.externs, cxx.tn, cxx.llmod, name, true, args2);
     ret res(cx, t);
 }
 
-fn trans_upcall2(builder b, @glue_fns glues, ValueRef lltaskptr,
-                 &hashmap[str, ValueRef] upcalls,
-                 type_names tn, ModuleRef llmod, str name,
-                 bool pass_task, vec[ValueRef] args) -> ValueRef {
+fn trans_native(builder b, @glue_fns glues, ValueRef lltaskptr,
+                &hashmap[str, ValueRef] externs,
+                type_names tn, ModuleRef llmod, str name,
+                bool pass_task, vec[ValueRef] args) -> ValueRef {
     let int n = (_vec.len[ValueRef](args) as int);
-    let ValueRef llupcall = get_upcall(upcalls, llmod, name, n);
-    llupcall = llvm.LLVMConstPointerCast(llupcall, T_int());
+    let ValueRef llnative = get_extern(externs, llmod, name, n);
+    llnative = llvm.LLVMConstPointerCast(llnative, T_int());
 
     let ValueRef llglue;
     if (pass_task) {
-        llglue = glues.upcall_glues_rust.(n);
+        llglue = glues.native_glues_rust.(n);
     } else {
-        llglue = glues.upcall_glues_cdecl.(n);
+        llglue = glues.native_glues_cdecl.(n);
     }
-    let vec[ValueRef] call_args = vec(llupcall);
+    let vec[ValueRef] call_args = vec(llnative);
 
     if (!pass_task) {
         call_args += vec(lltaskptr);
@@ -5771,8 +5790,8 @@ fn decl_native_fn_and_pair(@crate_ctxt cx,
         arg_n += 1u;
     }
 
-    auto r = trans_upcall2(bcx.build, cx.glues, lltaskptr, cx.upcalls, cx.tn,
-                           cx.llmod, name, pass_task, call_args);
+    auto r = trans_native(bcx.build, cx.glues, lltaskptr, cx.externs, cx.tn,
+                          cx.llmod, name, pass_task, call_args);
     auto rptr = bcx.build.BitCast(fcx.llretptr, T_ptr(T_i32()));
     bcx.build.Store(r, rptr);
     bcx.build.RetVoid();
@@ -5967,7 +5986,7 @@ fn i2p(ValueRef v, TypeRef t) -> ValueRef {
 }
 
 fn trans_exit_task_glue(@glue_fns glues,
-                        &hashmap[str, ValueRef] upcalls,
+                        &hashmap[str, ValueRef] externs,
                         type_names tn, ModuleRef llmod) {
     let vec[TypeRef] T_args = vec();
     let vec[ValueRef] V_args = vec();
@@ -5979,8 +5998,8 @@ fn trans_exit_task_glue(@glue_fns glues,
     auto build = new_builder(entrybb);
     auto tptr = build.PtrToInt(lltaskptr, T_int());
     auto V_args2 = vec(tptr) + V_args;
-    trans_upcall2(build, glues, lltaskptr,
-                  upcalls, tn, llmod, "upcall_exit", true, V_args2);
+    trans_native(build, glues, lltaskptr,
+                 externs, tn, llmod, "upcall_exit", true, V_args2);
     build.RetVoid();
 }
 
@@ -6415,7 +6434,7 @@ fn make_glues(ModuleRef llmod, type_names tn) -> @glue_fns {
              yield_glue = decl_glue(llmod, tn, abi.yield_glue_name()),
              /*
               * Note: the signature passed to decl_cdecl_fn here looks unusual
-              * because it is. It corresponds neither to an upcall signature
+              * because it is. It corresponds neither to a native signature
               * nor a normal rust-ABI signature. In fact it is a fake
               * signature, that exists solely to acquire the task pointer as
               * an argument to the upcall. It so happens that the runtime sets
@@ -6430,14 +6449,14 @@ fn make_glues(ModuleRef llmod, type_names tn) -> @glue_fns {
                                                      T_taskptr(tn)),
                                                  T_void())),
 
-             upcall_glues_rust =
-             _vec.init_fn[ValueRef](bind decl_upcall_glue(llmod, tn, true,
+             native_glues_rust =
+             _vec.init_fn[ValueRef](bind decl_native_glue(llmod, tn, true,
                                                           _),
-                                    abi.n_upcall_glues + 1 as uint),
-             upcall_glues_cdecl =
-             _vec.init_fn[ValueRef](bind decl_upcall_glue(llmod, tn, false,
+                                    abi.n_native_glues + 1 as uint),
+             native_glues_cdecl =
+             _vec.init_fn[ValueRef](bind decl_native_glue(llmod, tn, false,
                                                           _),
-                                    abi.n_upcall_glues + 1 as uint),
+                                    abi.n_native_glues + 1 as uint),
              no_op_type_glue = decl_no_op_type_glue(llmod, tn),
              memcpy_glue = decl_memcpy_glue(llmod),
              bzero_glue = decl_bzero_glue(llmod),
@@ -6503,7 +6522,7 @@ fn trans_crate(session.session sess, @ast.crate crate, str output,
                    td = td,
                    tn = tn,
                    crate_ptr = crate_ptr,
-                   upcalls = new_str_hash[ValueRef](),
+                   externs = new_str_hash[ValueRef](),
                    intrinsics = intrinsics,
                    item_names = new_str_hash[ValueRef](),
                    item_ids = new_def_hash[ValueRef](),