Document export tables a bunch more and rename get_lib_prefix -> get_group_prefix

Author: msullivan

mypyc/emit.py

@@ -145,8 +145,8 @@ def new_label(self) -> str:
         self.context.temp_counter += 1
         return '__LL%d' % self.context.temp_counter
 
-    def get_module_lib_prefix(self, module_name: str) -> str:
-        """Get the library prefix for a module.
+    def get_module_group_prefix(self, module_name: str) -> str:
+        """Get the group prefix for a module (relative to the current group).
 
         The prefix should be prepended to the object name whenever
         accessing an object from this module.
@@ -155,6 +155,13 @@ def get_module_lib_prefix(self, module_name: str) -> str:
         no prefix.  But if it lives in a different group (and hence a separate
         extension module), we need to access objects from it indirectly via an
         export table.
+
+        For example, for code in group `a` to call a function `bar` in group `b`,
+        it would need to do `exports_b.CPyDef_bar(...)`, while code that is
+        also in group `b` can simply do `CPyDef_bar(...)`.
+
+        Thus the prefix for a module in group `b` is 'exports_b.' if the current
+        group is *not* b and just '' if it is.
         """
         groups = self.context.group_map
         target_group_name = groups.get(module_name)
@@ -164,10 +171,10 @@ def get_module_lib_prefix(self, module_name: str) -> str:
         else:
             return ''
 
-    def get_lib_prefix(self, obj: Union[ClassIR, FuncDecl]) -> str:
-        """Get the library prefix for an object."""
+    def get_group_prefix(self, obj: Union[ClassIR, FuncDecl]) -> str:
+        """Get the group prefix for an object."""
         # See docs above
-        return self.get_module_lib_prefix(obj.module_name)
+        return self.get_module_group_prefix(obj.module_name)
 
     def static_name(self, id: str, module: Optional[str], prefix: str = STATIC_PREFIX) -> str:
         """Create name of a C static variable.
@@ -179,7 +186,7 @@ def static_name(self, id: str, module: Optional[str], prefix: str = STATIC_PREFI
         overlap with other calls to this method within a compilation
         group.
         """
-        lib_prefix = '' if not module else self.get_module_lib_prefix(module)
+        lib_prefix = '' if not module else self.get_module_group_prefix(module)
         # If we are accessing static via the export table, we need to dereference
         # the pointer also.
         star_maybe = '*' if lib_prefix else ''

mypyc/emitclass.py

@@ -397,14 +397,14 @@ def generate_vtable(entries: VTableEntries,
     for entry in entries:
         if isinstance(entry, VTableMethod):
             emitter.emit_line('(CPyVTableItem){}{}{},'.format(
-                emitter.get_lib_prefix(entry.method.decl),
+                emitter.get_group_prefix(entry.method.decl),
                 NATIVE_PREFIX,
                 entry.method.cname(emitter.names)))
         else:
             cl, attr, is_setter = entry
             namer = native_setter_name if is_setter else native_getter_name
             emitter.emit_line('(CPyVTableItem){}{},'.format(
-                emitter.get_lib_prefix(cl),
+                emitter.get_group_prefix(cl),
                 namer(cl, attr, emitter.names)))
     # msvc doesn't allow empty arrays; maybe allowing them at all is an extension?
     if not entries:
@@ -462,7 +462,7 @@ def generate_constructor_for_class(cl: ClassIR,
     args = ', '.join(['self'] + [REG_PREFIX + arg.name for arg in fn.sig.args])
     if init_fn is not None:
         emitter.emit_line('char res = {}{}{}({});'.format(
-            emitter.get_lib_prefix(init_fn.decl),
+            emitter.get_group_prefix(init_fn.decl),
             NATIVE_PREFIX, init_fn.cname(emitter.names), args))
         emitter.emit_line('if (res == 2) {')
         emitter.emit_line('Py_DECREF(self);')

mypyc/emitfunc.py

@@ -224,7 +224,7 @@ def visit_get_attr(self, op: GetAttr) -> None:
             # duplicating getter/setter code.
             self.emit_line('%s = %s%s((%s *)%s); /* %s */' % (
                 dest,
-                self.emitter.get_lib_prefix(decl_cl),
+                self.emitter.get_group_prefix(decl_cl),
                 native_getter_name(decl_cl, op.attr, self.emitter.names),
                 decl_cl.struct_name(self.names),
                 obj,
@@ -252,7 +252,7 @@ def visit_set_attr(self, op: SetAttr) -> None:
             typ, decl_cl = cl.attr_details(op.attr)
             self.emit_line('%s = %s%s((%s *)%s, %s); /* %s */' % (
                 dest,
-                self.emitter.get_lib_prefix(decl_cl),
+                self.emitter.get_group_prefix(decl_cl),
                 native_setter_name(decl_cl, op.attr, self.emitter.names),
                 decl_cl.struct_name(self.names),
                 obj,
@@ -303,7 +303,7 @@ def visit_call(self, op: Call) -> None:
         """Call native function."""
         dest = self.get_dest_assign(op)
         args = ', '.join(self.reg(arg) for arg in op.args)
-        lib = self.emitter.get_lib_prefix(op.fn)
+        lib = self.emitter.get_group_prefix(op.fn)
         cname = op.fn.cname(self.names)
         self.emit_line('%s%s%s%s(%s);' % (dest, lib, NATIVE_PREFIX, cname, args))
 
@@ -333,7 +333,7 @@ def visit_method_call(self, op: MethodCall) -> None:
         version = '_TRAIT' if rtype.class_ir.is_trait else ''
         if is_direct:
             # Directly call method, without going through the vtable.
-            lib = self.emitter.get_lib_prefix(method.decl)
+            lib = self.emitter.get_group_prefix(method.decl)
             self.emit_line('{}{}{}{}({});'.format(
                 dest, lib, NATIVE_PREFIX, method.cname(self.names), args))
         else:

mypyc/emitmodule.py

@@ -363,6 +363,26 @@ def generate_export_table(self, decl_emitter: Emitter, code_emitter: Emitter) ->
 
         Then, all calls to functions in another group and accesses to statics
         from another group are done indirectly via the export table.
+
+        For example, a group containing a module b, where b contains a class B
+        and a function bar, would declare an export table like:
+            struct export_table_b {
+                PyTypeObject **CPyType_B;
+                PyObject *(*CPyDef_B)(CPyTagged cpy_r_x);
+                CPyTagged (*CPyDef_B___foo)(PyObject *cpy_r_self, CPyTagged cpy_r_y);
+                tuple_T2OI (*CPyDef_bar)(PyObject *cpy_r_x);
+                char (*CPyDef___top_level__)(void);
+            };
+        that would be initialized with:
+            static struct export_table_b exports = {
+                &CPyType_B,
+                &CPyDef_B,
+                &CPyDef_B___foo,
+                &CPyDef_bar,
+                &CPyDef___top_level__,
+            };
+        To call `b.foo`, then, a function in another group would do
+        `exports_b.CPyDef_bar(...)`.
         """
 
         decls = decl_emitter.context.declarations

mypyc/emitwrapper.py

@@ -176,7 +176,7 @@ def generate_hash_wrapper(cl: ClassIR, fn: FuncIR, emitter: Emitter) -> str:
         name=name
     ))
     emitter.emit_line('{}retval = {}{}{}(self);'.format(emitter.ctype_spaced(fn.ret_type),
-                                                        emitter.get_lib_prefix(fn.decl),
+                                                        emitter.get_group_prefix(fn.decl),
                                                         NATIVE_PREFIX,
                                                         fn.cname(emitter.names)))
     emitter.emit_error_check('retval', fn.ret_type, 'return -1;')