引言​

Python，以其简洁的语法和庞大的生态系统，已成为当今最受欢迎的编程语言之一。然而，围绕其性能瓶颈和动态类型系统在大型项目中的维护性问题的讨论也从未停止。为了解决这些挑战，开发者社区探索了多种优化路径。

MoonBit 官方推出的 python.mbt 工具为此提供了一个新的视角。它允许开发者在 MoonBit 环境中直接调用 Python 代码。这种结合旨在融合 MoonBit 的静态类型安全、高性能潜力与 Python 成熟的生态系统。通过 python.mbt，开发者可以在享受 Python 丰富库函数的同时，利用 MoonBit 的静态分析能力、现代化的构建与测试工具，为构建大规模、高性能的系统级软件提供可能。

本文旨在深入探讨 python.mbt 的工作原理，并提供一份实践指南。本文将解答一些常见问题，例如：python.mbt 如何工作？它是否会因为增加了一个中间层而比原生 Python 更慢？相较于 C++ 的 pybind11 或 Rust 的 PyO3 等现有工具，python.mbt 的优势何在？要回答这些问题，我们首先需要理解 Python 解释器的基本工作流程。

Python 解释器的工作原理​

Python 解释器执行代码主要经历三个阶段：

1. 解析阶段 (Parsing) ：此阶段包含词法分析和语法分析。解释器将人类可读的 Python 源代码分解成一个个标记（Token），然后根据语法规则将这些标记组织成一个树形结构，即抽象语法树（AST）。

   例如，对于以下 Python 代码：

   def add(x, y):
     return x + y
   
   a = add(1, 2)
   print(a)
   

   我们可以使用 Python 的 ast 模块来查看其生成的 AST 结构：

   Module(
       body=[
           FunctionDef(
               name='add',
               args=arguments(
                   args=[
                       arg(arg='x'),
                       arg(arg='y')]),
               body=[
                   Return(
                       value=BinOp(
                           left=Name(id='x', ctx=Load()),
                           op=Add(),
                           right=Name(id='y', ctx=Load())))]),
           Assign(
               targets=[
                   Name(id='a', ctx=Store())],
               value=Call(
                   func=Name(id='add', ctx=Load()),
                   args=[
                       Constant(value=1),
                       Constant(value=2)])),
           Expr(
               value=Call(
                   func=Name(id='print', ctx=Load()),
                   args=[
                       Name(id='a', ctx=Load())]))])
   

2. 编译阶段 (Compilation) ：接下来，Python 解释器会将 AST 编译成更低级、更线性的中间表示，即字节码（Bytecode）。这是一种平台无关的指令集，专为 Python 虚拟机（PVM）设计。

   利用 Python 的 dis 模块，我们可以查看上述代码对应的字节码：

     2           LOAD_CONST               0 (<code object add>)
                 MAKE_FUNCTION
                 STORE_NAME               0 (add)
   
     5           LOAD_NAME                0 (add)
                 PUSH_NULL
                 LOAD_CONST               1 (1)
                 LOAD_CONST               2 (2)
                 CALL                     2
                 STORE_NAME               1 (a)
   
     6           LOAD_NAME                2 (print)
                 PUSH_NULL
                 LOAD_NAME                1 (a)
                 CALL                     1
                 POP_TOP
                 RETURN_CONST             3 (None)
   

3. 执行阶段 (Execution) ：最后，Python 虚拟机（PVM）会逐条执行字节码指令。每条指令都对应 CPython 解释器底层的一个 C 函数调用。例如，LOAD_NAME 会查找变量，BINARY_OP 会执行二元运算。正是这个逐条解释执行的过程，构成了 Python 性能开销的主要来源。一次简单的 1 + 2 运算，背后需要经历整个解析、编译和虚拟机执行的复杂流程。

了解这个流程，有助于我们理解 Python 性能优化的基本思路，以及 python.mbt 的设计哲学。

优化 Python 性能的路径​

目前，提升 Python 程序性能主要有两种主流方法：

1. 即时编译（JIT） 。像 PyPy 这样的项目，通过分析正在运行的程序，将频繁执行的"热点"字节码编译成高度优化的本地机器码，从而绕过 PVM 的解释执行，大幅提升计算密集型任务的速度。然而，JIT 并非万能药，它无法解决 Python 动态类型语言的固有问题，例如在大型项目中难以进行有效的静态分析，这给软件维护带来了挑战。
2. 原生扩展。开发者可以使用 C++（借助 pybind11）或 Rust（借助 PyO3）等语言直接调用Python功能，或者用这些语言来编写性能关键模块，然后从 Python 中调用。这种方法可以获得接近原生的性能，但它要求开发者同时精通 Python 和一门复杂的系统级语言，学习曲线陡峭，对大多数 Python 程序员来说门槛较高。

python.mbt 也是一种原生扩展。但相比较于C++和Rust等语言，它试图在性能、易用性和工程化能力之间找到一个新的平衡点，更强调在MoonBit语言中直接使用Python功能。

1. 高性能核心：MoonBit 是一门静态类型的编译型语言，其代码可以被高效地编译成原生机器码。开发者可以将计算密集型逻辑用 MoonBit 实现，从根本上获得高性能。
2. 无缝的 Python 调用：python.mbt 直接与 CPython 的 C-API 交互，调用 Python 模块和函数。这意味着调用开销被最小化，绕过了 Python 的解析和编译阶段，直达虚拟机执行层。
3. 更平缓的学习曲线：相较于 C++ 和 Rust，MoonBit 的语法设计更加现代化和简洁，并拥有完善的函数式编程支持、文档系统、单元测试和静态分析工具，对习惯于 Python 的开发者更加友好。
4. 改善的工程化与 AI 协作：MoonBit 的强类型系统和清晰的接口定义，使得代码意图更加明确，更易于被静态分析工具和 AI 辅助编程工具理解。这有助于在大型项目中维护代码质量，并提升与 AI 协作编码的效率和准确性。

在 MoonBit 中使用已封装的 Python 库​

为了方便开发者使用，MoonBit 官方会在构建系统和IDE成熟后对主流 Python 库进行封装。封装完成后，用户可以像导入普通 MoonBit 包一样，在项目中使用这些 Python 库。下面以 matplotlib 绘图库为例。

首先，在你的项目根目录的 moon.pkg.json 或终端中添加 matplotlib 依赖：

moon update
moon add Kaida-Amethyst/matplotlib

然后，在要使用该库的子包的 moon.pkg.json 中声明导入。这里，我们遵循 Python 的惯例，为其设置一个别名 plt：

{
  "import": [
    {
      "path": "Kaida-Amethyst/matplotlib",
      "alias": "plt"
    }
  ]
}

完成配置后，便可以在 MoonBit 代码中调用 matplotlib 进行绘图：

let 
(Double) -> Double
sin : (
Double
Double) -> 
Double
Double = 
fn @moonbitlang/core/math.sin(x : Double) -> Double
Calculates the sine of a number in radians. Handles special cases and edge
conditions according to IEEE 754 standards.
Parameters:

x : The angle in radians for which to calculate the sine.
Returns the sine of the angle x.
Example:
test {
  inspect(@math.sin(0.0), content="0")
  inspect(@math.sin(1.570796326794897), content="1") // pi / 2
  inspect(@math.sin(2.0), content="0.9092974268256817")
  inspect(@math.sin(-5.0), content="0.9589242746631385")
  inspect(@math.sin(31415926535897.9323846), content="0.0012091232715481885")
  inspect(@math.sin(@double.not_a_number), content="NaN")
  inspect(@math.sin(@double.infinity), content="NaN")
  inspect(@math.sin(@double.neg_infinity), content="NaN")
}
@math.sin

fn main {
  let 
Array[Double]
x = 
type Array[T]
An Array is a collection of values that supports random access and can
grow in size.
Array::
fn[T] Array::makei(length : Int, f : (Int) -> T raise?) -> Array[T] raise?
Creates a new array of the specified length, where each element is
initialized using an index-based initialization function.
Parameters:

length : The length of the new array. If length is less than or equal
to 0, returns an empty array.
initializer : A function that takes an index (starting from 0) and
returns a value of type T. This function is called for each index to
initialize the corresponding element.
Returns a new array of type Array[T] with the specified length, where each
element is initialized using the provided function.
Example:
test {
  let arr = Array::makei(3, i => i * 2)
  inspect(arr, content="[0, 2, 4]")
}
makei(100, fn(
Int
i) { 
Int
i.
fn Int::to_double(self : Int) -> Double
Converts a 32-bit integer to a double-precision floating-point number. The
conversion preserves the exact value since all integers in the range of Int
can be represented exactly as Double values.
Parameters:

self : The 32-bit integer to be converted.
Returns a double-precision floating-point number that represents the same
numerical value as the input integer.
Example:
test {
  let n = 42
  inspect(n.to_double(), content="42")
  let neg = -42
  inspect(neg.to_double(), content="-42")
}
to_double() 
fn Mul::mul(self : Double, other : Double) -> Double
Multiplies two double-precision floating-point numbers. This is the
implementation of the * operator for Double type.
Parameters:

self : The first double-precision floating-point operand.
other : The second double-precision floating-point operand.
Returns a new double-precision floating-point number representing the product
of the two operands. Special cases follow IEEE 754 standard:

If either operand is NaN, returns NaN
If one operand is infinity and the other is zero, returns NaN
If one operand is infinity and the other is a non-zero finite number,
returns infinity with the appropriate sign
If both operands are infinity, returns infinity with the appropriate sign
Example:
test {
  inspect(2.5 * 2.0, content="5")
  inspect(-2.0 * 3.0, content="-6")
  let nan = 0.0 / 0.0 // NaN
  inspect(nan * 1.0, content="NaN")
}
* 0.1 })
  let 
Array[Double]
y = 
Array[Double]
x.
fn[T, U] Array::map(self : Array[T], f : (T) -> U raise?) -> Array[U] raise?
Maps a function over the elements of the array.
Example
test {
  let v = [3, 4, 5]
  let v2 = v.map(x => x + 1)
  assert_eq(v2, [4, 5, 6])
}
map(
let sin : (Double) -> Double
sin)

  // 为保证类型安全，封装后的 subplots 接口总是返回一个固定类型的元组。
  // 这避免了 Python 中根据参数返回不同类型对象的动态行为。
  let (_, 
Unit
axes) = 
(Int, Int) -> (Unit, Unit)
plt::
(Int, Int) -> (Unit, Unit)
subplots(1, 1)

  // 使用 .. 级联调用语法
  
Unit
axes[0
(Int) -> Unit
][0]
  ..
(Array[Double], Array[Double], Unit, Unit, Int) -> Unit
plot(
Array[Double]
x, 
Array[Double]
y, 
Unit
color = 
Unit
Green, 
Unit
linestyle = 
Unit
Dashed, 
Int
linewidth = 2)
  ..
(String) -> Unit
set_title("Sine of x")
  ..
(String) -> Unit
set_xlabel("x")
  ..
(String) -> Unit
set_ylabel("sin(x)")

  
() -> Unit
@plt.show()
}

目前，在 macOS 和 Linux 环境下，MoonBit 的构建系统可以自动处理依赖。在 Windows 上，用户可能需要手动安装 C 编译器并配置 Python 环境。未来的 MoonBit IDE 将致力于简化这一过程。

在 MoonBit 中使用未封装的 Python 模块​

Python 生态浩如烟海，即使现在有了AI技术，完全依赖官方封装也并不现实。幸运的是，我们可以利用 python.mbt 的核心功能直接与任何 Python 模块交互。下面，我们以 Python 标准库中，一个简单的的 time 模块为例，演示这一过程。

引入 python.mbt​

首先，确保你的 MoonBit 工具链是最新版本，然后添加 python.mbt 依赖：

moon update
moon add Kaida-Amethyst/python

接着，在你的包的 moon.pkg.json 中导入它：

{
  "import": ["Kaida-Amethyst/python"]
}

python.mbt 会自动处理 Python 解释器的初始化（Py_Initialize）和关闭，开发者无需手动管理。

导入 Python 模块​

使用 @python.pyimport 函数来导入模块。为了避免重复导入造成的性能损耗，建议使用闭包技巧来缓存导入的模块对象：

// 定义一个结构体来持有 Python 模块对象，增强类型安全
pub struct TimeModule {
  
?
time_mod: PyModule
}

// 定义一个函数，它返回一个闭包，该闭包用于获取 TimeModule 实例
fn 
fn import_time_mod() -> () -> TimeModule
import_time_mod() -> () -> 
struct TimeModule {
  time_mod: ?
}
TimeModule {
  // 仅在首次调用时执行导入操作
  guard 
(String) -> Unit
@python.pyimport("time") is 
(?) -> Unit
Some(
?
time_mod) else {
    
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
test {
  if false {
    println(42)
    println("Hello, World!")
    println([1, 2, 3])
  }
}
println("Failed to load Python module: time")
    
fn[T] panic() -> T
panic("ModuleLoadError")
  }
  let 
TimeModule
time_mod = 
struct TimeModule {
  time_mod: ?
}
TimeModule::{ 
?
time_mod }
  // 返回的闭包会捕获 time_mod 变量
  fn () { 
TimeModule
time_mod }
}

// 创建一个全局的 time_mod "getter" 函数
let 
() -> TimeModule
time_mod: () -> 
struct TimeModule {
  time_mod: ?
}
TimeModule = 
fn import_time_mod() -> () -> TimeModule
import_time_mod()

在后续代码中，我们应始终通过调用 time_mod() 来获取模块，而不是 import_time_mod。

MoonBit 与 Python 对象的相互转换​

要调用 Python 函数，我们需要在 MoonBit 对象和 Python 对象（PyObject）之间进行转换。

1. 整数: 使用 PyInteger::from 从 Int64 创建 PyInteger，使用 to_int64() 反向转换。

   test "py_integer_conversion" {
     let 
   Int64
   n: 
   Int64
   Int64 = 42
     let 
   &Show
   py_int = 
   (Int64) -> &Show
   PyInteger::
   (Int64) -> &Show
   from(
   Int64
   n)
     
   fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
   Tests if the string representation of an object matches the expected content.
   Used primarily in test cases to verify the correctness of Show
   implementations and program outputs.
   Parameters:
   
   object : The object to be inspected. Must implement the Show trait.
   content : The expected string representation of the object. Defaults to
   an empty string.
   location : Source code location information for error reporting.
   Automatically provided by the compiler.
   arguments_location : Location information for function arguments in
   source code. Automatically provided by the compiler.
   Throws an InspectError if the actual string representation of the object
   does not match the expected content. The error message includes detailed
   information about the mismatch, including source location and both expected
   and actual values.
   Example:
   test {
     inspect(42, content="42")
     inspect("hello", content="hello")
     inspect([1, 2, 3], content="[1, 2, 3]")
   }
   inspect(
   &Show
   py_int, 
   String
   content="42")
     
   fn[T : Eq + Show] assert_eq(a : T, b : T, msg? : String, loc~ : SourceLoc = _) -> Unit raise
   Asserts that two values are equal. If they are not equal, raises a failure
   with a message containing the source location and the values being compared.
   Parameters:
   
   a : First value to compare.
   b : Second value to compare.
   loc : Source location information to include in failure messages. This is
   usually automatically provided by the compiler.
   Throws a Failure error if the values are not equal, with a message showing
   the location of the failing assertion and the actual values that were
   compared.
   Example:
   test {
     assert_eq(1, 1)
     assert_eq("hello", "hello")
   }
   assert_eq(
   &Show
   py_int.
   () -> Int64
   to_int64(), 42L)
   }
   

2. 浮点数: 使用 PyFloat::from 和 to_double。

   test "py_float_conversion" {
     let 
   Double
   n: 
   Double
   Double = 3.5
     let 
   &Show
   py_float = 
   (Double) -> &Show
   PyFloat::
   (Double) -> &Show
   from(
   Double
   n)
     
   fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
   Tests if the string representation of an object matches the expected content.
   Used primarily in test cases to verify the correctness of Show
   implementations and program outputs.
   Parameters:
   
   object : The object to be inspected. Must implement the Show trait.
   content : The expected string representation of the object. Defaults to
   an empty string.
   location : Source code location information for error reporting.
   Automatically provided by the compiler.
   arguments_location : Location information for function arguments in
   source code. Automatically provided by the compiler.
   Throws an InspectError if the actual string representation of the object
   does not match the expected content. The error message includes detailed
   information about the mismatch, including source location and both expected
   and actual values.
   Example:
   test {
     inspect(42, content="42")
     inspect("hello", content="hello")
     inspect([1, 2, 3], content="[1, 2, 3]")
   }
   inspect(
   &Show
   py_float, 
   String
   content="3.5")
     
   fn[T : Eq + Show] assert_eq(a : T, b : T, msg? : String, loc~ : SourceLoc = _) -> Unit raise
   Asserts that two values are equal. If they are not equal, raises a failure
   with a message containing the source location and the values being compared.
   Parameters:
   
   a : First value to compare.
   b : Second value to compare.
   loc : Source location information to include in failure messages. This is
   usually automatically provided by the compiler.
   Throws a Failure error if the values are not equal, with a message showing
   the location of the failing assertion and the actual values that were
   compared.
   Example:
   test {
     assert_eq(1, 1)
     assert_eq("hello", "hello")
   }
   assert_eq(
   &Show
   py_float.
   () -> Double
   to_double(), 3.5)
   }
   

3. 字符串: 使用 PyString::from 和 to_string。

   test "py_string_conversion" {
     let 
   &Show
   py_str = 
   (String) -> &Show
   PyString::
   (String) -> &Show
   from("hello")
     
   fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
   Tests if the string representation of an object matches the expected content.
   Used primarily in test cases to verify the correctness of Show
   implementations and program outputs.
   Parameters:
   
   object : The object to be inspected. Must implement the Show trait.
   content : The expected string representation of the object. Defaults to
   an empty string.
   location : Source code location information for error reporting.
   Automatically provided by the compiler.
   arguments_location : Location information for function arguments in
   source code. Automatically provided by the compiler.
   Throws an InspectError if the actual string representation of the object
   does not match the expected content. The error message includes detailed
   information about the mismatch, including source location and both expected
   and actual values.
   Example:
   test {
     inspect(42, content="42")
     inspect("hello", content="hello")
     inspect([1, 2, 3], content="[1, 2, 3]")
   }
   inspect(
   &Show
   py_str, 
   String
   content="'hello'")
     
   fn[T : Eq + Show] assert_eq(a : T, b : T, msg? : String, loc~ : SourceLoc = _) -> Unit raise
   Asserts that two values are equal. If they are not equal, raises a failure
   with a message containing the source location and the values being compared.
   Parameters:
   
   a : First value to compare.
   b : Second value to compare.
   loc : Source location information to include in failure messages. This is
   usually automatically provided by the compiler.
   Throws a Failure error if the values are not equal, with a message showing
   the location of the failing assertion and the actual values that were
   compared.
   Example:
   test {
     assert_eq(1, 1)
     assert_eq("hello", "hello")
   }
   assert_eq(
   &Show
   py_str.
   fn Show::to_string(&Show) -> String
   to_string(), "hello")
   }
   

4. 列表 (List) : 你可以创建一个空 PyList 然后 append 元素，或者直接从一个 Array[&IsPyObject] 创建。

   test "py_list_from_array" {
     let 
   Unit
   one = 
   (Int) -> Unit
   PyInteger::
   (Int) -> Unit
   from(1)
     let 
   Unit
   two = 
   (Double) -> Unit
   PyFloat::
   (Double) -> Unit
   from(2.0)
     let 
   Unit
   three = 
   (String) -> Unit
   PyString::
   (String) -> Unit
   from("three")
     let 
   Array[Unit]
   arr
   Array[Unit]
   : 
   type Array[T]
   An Array is a collection of values that supports random access and can
   grow in size.
   Array
   Array[Unit]
   [&IsPyObject] = [
   Unit
   one, 
   Unit
   two, 
   Unit
   three]
   
     let 
   &Show
   list = 
   (Array[Unit]) -> &Show
   PyList::
   (Array[Unit]) -> &Show
   from(
   Array[Unit]
   arr)
     
   fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
   Tests if the string representation of an object matches the expected content.
   Used primarily in test cases to verify the correctness of Show
   implementations and program outputs.
   Parameters:
   
   object : The object to be inspected. Must implement the Show trait.
   content : The expected string representation of the object. Defaults to
   an empty string.
   location : Source code location information for error reporting.
   Automatically provided by the compiler.
   arguments_location : Location information for function arguments in
   source code. Automatically provided by the compiler.
   Throws an InspectError if the actual string representation of the object
   does not match the expected content. The error message includes detailed
   information about the mismatch, including source location and both expected
   and actual values.
   Example:
   test {
     inspect(42, content="42")
     inspect("hello", content="hello")
     inspect([1, 2, 3], content="[1, 2, 3]")
   }
   inspect(
   &Show
   list, 
   String
   content="[1, 2.0, 'three']")
   }
   

5. 元组 (Tuple) : PyTuple 需要先指定大小，然后通过 set 方法逐一填充元素。

   test "py_tuple_creation" {
     let 
   &Show
   tuple = 
   (Int) -> &Show
   PyTuple::
   (Int) -> &Show
   new(3)
     
   &Show
   tuple
     ..
   (Int, Unit) -> Unit
   set(0, 
   (Int) -> Unit
   PyInteger::
   (Int) -> Unit
   from(1))
     ..
   (Int, Unit) -> Unit
   set(1, 
   (Double) -> Unit
   PyFloat::
   (Double) -> Unit
   from(2.0))
     ..
   (Int, Unit) -> Unit
   set(2, 
   (String) -> Unit
   PyString::
   (String) -> Unit
   from("three"))
   
     
   fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
   Tests if the string representation of an object matches the expected content.
   Used primarily in test cases to verify the correctness of Show
   implementations and program outputs.
   Parameters:
   
   object : The object to be inspected. Must implement the Show trait.
   content : The expected string representation of the object. Defaults to
   an empty string.
   location : Source code location information for error reporting.
   Automatically provided by the compiler.
   arguments_location : Location information for function arguments in
   source code. Automatically provided by the compiler.
   Throws an InspectError if the actual string representation of the object
   does not match the expected content. The error message includes detailed
   information about the mismatch, including source location and both expected
   and actual values.
   Example:
   test {
     inspect(42, content="42")
     inspect("hello", content="hello")
     inspect([1, 2, 3], content="[1, 2, 3]")
   }
   inspect(
   &Show
   tuple, 
   String
   content="(1, 2.0, 'three')")
   }
   

6. 字典 (Dict) : PyDict 主要支持字符串作为键。使用 new 创建字典，set 添加键值对。对于非字符串键，需要使用 set_by_obj。

   test "py_dict_creation" {
     let 
   &Show
   dict = 
   () -> &Show
   PyDict::
   () -> &Show
   new()
     
   &Show
   dict
     ..
   (String, Unit) -> Unit
   set("one", 
   (Int) -> Unit
   PyInteger::
   (Int) -> Unit
   from(1))
     ..
   (String, Unit) -> Unit
   set("two", 
   (Double) -> Unit
   PyFloat::
   (Double) -> Unit
   from(2.0))
   
     
   fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
   Tests if the string representation of an object matches the expected content.
   Used primarily in test cases to verify the correctness of Show
   implementations and program outputs.
   Parameters:
   
   object : The object to be inspected. Must implement the Show trait.
   content : The expected string representation of the object. Defaults to
   an empty string.
   location : Source code location information for error reporting.
   Automatically provided by the compiler.
   arguments_location : Location information for function arguments in
   source code. Automatically provided by the compiler.
   Throws an InspectError if the actual string representation of the object
   does not match the expected content. The error message includes detailed
   information about the mismatch, including source location and both expected
   and actual values.
   Example:
   test {
     inspect(42, content="42")
     inspect("hello", content="hello")
     inspect([1, 2, 3], content="[1, 2, 3]")
   }
   inspect(
   &Show
   dict, 
   String
   content="{'one': 1, 'two': 2.0}")
   }
   

从 Python 复合类型中获取元素时，python.mbt 会进行运行时类型检查，并返回一个 Optional[PyObjectEnum]，以确保类型安全。

test "py_list_get" {
  let 
Unit
list = 
() -> Unit
PyList::
() -> Unit
new()
  
Unit
list.
(Unit) -> Unit
append(
(Int) -> Unit
PyInteger::
(Int) -> Unit
from(1))
  
Unit
list.
(Unit) -> Unit
append(
(String) -> Unit
PyString::
(String) -> Unit
from("hello"))

  
fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
Parameters:

object : The object to be inspected. Must implement the Show trait.
content : The expected string representation of the object. Defaults to
an empty string.
location : Source code location information for error reporting.
Automatically provided by the compiler.
arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
Example:
test {
  inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
}
inspect(
Unit
list.
(Int) -> Unit
get(0).
() -> &Show
unwrap(), 
String
content="PyInteger(1)")
  
fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
Parameters:

object : The object to be inspected. Must implement the Show trait.
content : The expected string representation of the object. Defaults to
an empty string.
location : Source code location information for error reporting.
Automatically provided by the compiler.
arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
Example:
test {
  inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
}
inspect(
Unit
list.
(Int) -> Unit
get(1).
() -> &Show
unwrap(), 
String
content="PyString('hello')")
  
fn inspect(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
Parameters:

object : The object to be inspected. Must implement the Show trait.
content : The expected string representation of the object. Defaults to
an empty string.
location : Source code location information for error reporting.
Automatically provided by the compiler.
arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
Example:
test {
  inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
}
inspect(
Unit
list.
(Int) -> &Show
get(2), 
String
content="None") // 索引越界返回 None
}

调用模块中的函数​

调用函数分为两步：首先用 get_attr 获取函数对象，然后用 invoke 执行调用。invoke 的返回值是一个需要进行模式匹配和类型转换的 PyObject。

下面是 time.sleep 和 time.time 的 MoonBit 封装：

// 封装 time.sleep
pub fn 
fn sleep(seconds : Double) -> Unit
sleep(
Double
seconds: 
Double
Double) -> 
Unit
Unit {
  let 
TimeModule
lib = 
let time_mod : () -> TimeModule
time_mod()
  guard 
TimeModule
lib.
?
time_mod.
(String) -> Unit
get_attr("sleep") is 
(_/0) -> Unit
Some(
(Unit) -> _/0
PyCallable(
Unit
f)) else {
    
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
test {
  if false {
    println(42)
    println("Hello, World!")
    println([1, 2, 3])
  }
}
println("get function `sleep` failed!")
    
fn[T] panic() -> T
panic()
  }
  let 
Unit
args = 
(Int) -> Unit
PyTuple::
(Int) -> Unit
new(1)
  
Unit
args.
(Int, Unit) -> Unit
set(0, 
(Double) -> Unit
PyFloat::
(Double) -> Unit
from(
Double
seconds))
  match (try? 
Unit
f.
(Unit) -> Unit
invoke(
Unit
args)) {
    
(Unit) -> Result[Unit, Error]
Ok(_) => 
Unit
Ok(())
    
(Error) -> Result[Unit, Error]
Err(
Error
e) => {
      
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
test {
  if false {
    println(42)
    println("Hello, World!")
    println([1, 2, 3])
  }
}
println("invoke `sleep` failed!")
      
fn[T] panic() -> T
panic()
    }
  }
}

// 封装 time.time
pub fn 
fn time() -> Double
time() -> 
Double
Double {
  let 
TimeModule
lib = 
let time_mod : () -> TimeModule
time_mod()
  guard 
TimeModule
lib.
?
time_mod.
(String) -> Unit
get_attr("time") is 
(_/0) -> Unit
Some(
(Unit) -> _/0
PyCallable(
Unit
f)) else {
    
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
test {
  if false {
    println(42)
    println("Hello, World!")
    println([1, 2, 3])
  }
}
println("get function `time` failed!")
    
fn[T] panic() -> T
panic()
  }
  match (try? 
Unit
f.
() -> Unit
invoke()) {
    
(Unit) -> Result[Unit, Error]
Ok(
(_/0) -> Unit
Some(
(Unit) -> _/0
PyFloat(
Unit
t))) => 
Unit
t.
() -> Double
to_double()
    _ => {
      
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
test {
  if false {
    println(42)
    println("Hello, World!")
    println([1, 2, 3])
  }
}
println("invoke `time` failed!")
      
fn[T] panic() -> T
panic()
    }
  }
}

完成封装后，我们就可以在 MoonBit 中以类型安全的方式使用它们了：

test "sleep" {
  let 
Unit
start = 
fn time() -> Double
time().
() -> Unit
unwrap()
  
fn sleep(seconds : Double) -> Unit
sleep(1)
  let 
Unit
end = 
fn time() -> Double
time().
() -> Unit
unwrap()

  
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
test {
  if false {
    println(42)
    println("Hello, World!")
    println([1, 2, 3])
  }
}
println("start = \{
Unit
start}")
  
fn[T : Show] println(input : T) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:

value : The value to be printed. Must implement the Show trait.
Example:
test {
  if false {
    println(42)
    println("Hello, World!")
    println([1, 2, 3])
  }
}
println("end = \{
Unit
end}")
}

实践建议​

1. 明确边界：将 python.mbt 视为连接 MoonBit 和 Python 生态的"胶水层"。将核心计算和业务逻辑保留在 MoonBit 中以利用其性能和类型系统优势，仅在必要情况下，需要调用 Python 独有库时才使用 python.mbt。

2. 用 ADT 替代字符串魔法：许多 Python 函数接受特定的字符串作为参数来控制行为。在 MoonBit 封装中，应将这些"魔法字符串"转换为代数数据类型（ADT） ，即枚举。这利用了 MoonBit 的类型系统，将运行时的值检查提前到编译时，极大地增强了代码的健壮性。

3. 完善的错误处理：本文中的示例为了简洁使用了 panic 或返回简单字符串。在生产代码中，应定义专门的错误类型，并通过 Result 类型进行传递和处理，提供清晰的错误上下文。

4. 映射关键字参数：Python 函数广泛使用关键字参数（kwargs），如 plot(color='blue', linewidth=2)。这可以优雅地映射到 MoonBit 的标签参数（Labeled Arguments） 。在封装时，应优先使用标签参数以提供相似的开发体验。

   例如，一个接受 kwargs 的 Python 函数：

   # graphics.py
   def draw_line(points, color="black", width=1):
       # ... drawing logic ...
       print(f"Drawing line with color {color} and width {width}")
   

   其 MoonBit 封装可以设计成：

   fn draw_line(points: Array[Point], color~: Color = Black, width: Int = 1) -> Unit {
     let points : PyList = ... // convert Array[Point] to PyList
   
     // 构造args
     let args = PyTuple::new(1)
     args .. set(0, points)
   
     // 构造kwargs
     let kwargs = PyDict::new()
     kwargs
     ..set("color", PyString::from(color))
     ...set("width", PyInteger::from(width))
     match (try? f.invoke(args~, kwargs~)) {
       Ok(_) => ()
       _ => {
         // 进行错误处理
       }
     }
   }
   

5. 警惕动态性：始终牢记 Python 是动态类型的。从 Python 获取的任何数据都应被视为"不可信"的，必须进行严格的类型检查和校验，尽量避免使用 unwrap，而是通过模式匹配来安全地处理所有可能的情况。

结语​

本文梳理了 python.mbt 的工作原理，并展示了如何利用它在 MoonBit 中调用 Python 代码，无论是通过预封装的库还是直接与 Python 模块交互。python.mbt 不仅仅是一个工具，它代表了一种融合思想：将 MoonBit 的静态分析、高性能和工程化优势与 Python 庞大而成熟的生态系统相结合。我们希望这篇文章能为 MoonBit 和 Python 社区的开发者们在构建未来软件时，提供一个新的、更强大的选择。

---

引言​

MoonBit 是一门现代化函数式编程语言，它有着严谨的类型系统，高可读性的语法，以及专为AI设计的工具链等。然而，重复造轮子并不可取。无数经过时间检验、性能卓越的库是用C语言（或兼容C ABI的语言，如C++、Rust）编写的。从底层硬件操作到复杂的科学计算，再到图形渲染，C的生态系统是一座蕴藏着无尽宝藏的富矿。

那么，我们能否让现代的MoonBit与这些经典的C库协同工作，让新世界的开拓者也能使用旧时代的强大工具呢？答案是肯定的。通过C语言外部函数接口（C Foreign Function Interface, C-FFI），MoonBit拥有调用C函数的能力，将新旧两个世界连接起来。

这篇文章将作为你的向导，带你一步步探索MoonBit C-FFI的奥秘。我们将通过一个具体的例子——为一个C语言编写的数学库 mymath​ 创建MoonBit绑定——来学习如何处理不同类型的数据、指针、结构体乃至函数指针。

预先准备​

要连接到任何一个C库，我们需要知道这个C库的头文件的函数，如何找到头文件，如何找到库文件。对于我们这篇文章的任务来说。C语言数学库的头文件就是 mymath.h​。它定义了我们希望在MoonBit中调用的各种函数和类型。我们这里假设我们的mymath​是安装到系统上的，编译时使用-I/usr/inluclude​来找到头文件，使用-L/usr/lib -lmymath​来链接库，下面是我们的mymath.h​的部分内容。

// mymath.h

// --- 基础函数 ---
void print_version();
int version_major();
int is_normal(double input);

// --- 浮点数计算 ---
float sinf(float input);
float cosf(float input);
float tanf(float input);
double sin(double input);
double cos(double input);
double tan(double input);

// --- 字符串与指针 ---
int parse_int(char* str);
char* version();
int tan_with_errcode(double input, double* output);

// --- 数组操作 ---
int sin_array(int input_len, double* inputs, double* outputs);
int cos_array(int input_len, double* inputs, double* outputs);
int tan_array(int input_len, double* inputs, double* outputs);

// --- 结构体与复杂类型 ---
typedef struct {
  double real;
  double img;
} Complex;

Complex* new_complex(double r, double i);
void multiply(Complex* a, Complex* b, Complex** result);
void init_n_complexes(int n, Complex** complex_array);

// --- 函数指针 ---
void for_each_complex(int n, Complex** arr, void (*call_back)(Complex*));

基础准备 (The Groundwork)​

在编写任何 FFI 代码之前，我们需要先搭建好 MoonBit 与 C 代码之间的桥梁。

编译到 Native​

首先，MoonBit 代码需要被编译成原生机器码。这可以通过以下命令完成：

moon build --target native

这个命令会将你的 MoonBit 项目编译成 C 代码，并使用系统上的 C 编译器（如 GCC 或 Clang）将其编译为最终的可执行文件。编译后的 C 文件位于 target/native/release/build/​ 目录下，按包名存放在相应的子目录中。例如，main/main.mbt​ 会被编译到 target/native/release/build/main/main.c​。

配置链接​

仅仅编译是不够的，我们还需要告诉 MoonBit 编译器如何找到并链接到我们的 mymath​ 库。这需要在项目的 moon.pkg.json​ 文件中进行配置。

{
  "supported-targets": ["native"],
  "link": {
    "native": {
      "cc": "clang",
      "cc-flags": "-I/usr/include",
      "cc-link-flags": "-L/usr/lib -lmymath"
    }
  }
}

• ​cc​: 指定用于编译C代码的编译器，例如 clang​ 或 gcc​。
• ​cc-flags​: 编译C文件时需要的标志，通常用来指定头文件搜索路径（-I​）。
• ​cc-link-flags​: 链接时需要的标志，通常用来指定库文件搜索路径（-L​）和具体要链接的库（-l​）。

同时，我们还需要一个 "胶水" C 文件，我们这里命名为 cwrap.c​，用来包含 C 库的头文件和 MoonBit 的运行时头文件。

// cwrap.c
#include <mymath.h>
#include <moonbit.h>

这个胶水文件也需要通过 moon.pkg.json​ 告知 MoonBit 编译器：

{
  // ... 其他配置
  "native-stub": ["cwrap.c"]
}

完成这些配置后，我们的项目就已经准备好与 mymath​ 库进行链接了。

第一次跨语言调用 (The First FFI Call)​

万事俱备，让我们来进行第一次真正的跨语言调用。在 MoonBit 中声明一个外部 C 函数，语法如下：

extern "C" fn moonbit_function_name(arg: Type) -> ReturnType = "c_function_name"

• ​extern "C"​：告诉 MoonBit 编译器，这是一个外部 C 函数。
• ​moonbit_function_name​：在 MoonBit 代码中使用的函数名。
• ​"c_function_name"​：实际链接到的 C 函数的名称。

让我们用 mymath.h​ 中最简单的 version_major​ 函数来小试牛刀：

extern "C" fn version_major() -> 
Int
Int = "version_major"

注意：MoonBit 拥有强大的死代码消除（DCE）能力。如果你只是声明了上面的 FFI 函数但从未在代码中（例如 main​ 函数）实际调用它，编译器会认为它是无用代码，并不会在最终生成的 C 代码中包含它的声明。所以，请确保你至少在一个地方调用了它！

跨越类型系统的鸿沟 (Navigating the Type System Chasm)​

真正的挑战在于处理两种语言之间的数据类型差异，对于一些复杂的类型情况，需要读者有一定的C语言知识。

3.1 基本类型：(Basic Types)​

对于基础的数值类型，MoonBit 和 C 之间有直接且清晰的对应关系。

MoonBit Type	C Type	Notes
​Int​	​int32_t​
​Int64​	​int64_t​
​UInt​	​uint32_t​
​UInt64​	​uint64_t​
​Float​	​float​
​Double​	​double​
​Bool​	​int32_t​	C语言标准没有原生 bool​，通常用 int32_t​ (0/1) 表示
​Unit​	​void​ (返回值)	用于表示 C 函数没有返回值的情况
​Byte​	​uint8_t​

根据这个表格，我们可以轻松地为 mymath.h​ 中的大部分简单函数编写 FFI 声明：

extern "C" fn print_version() -> 
Unit
Unit = "print_version"
extern "C" fn version_major() -> 
Int
Int = "version_major"

// 返回值语义上是布尔值，使用 MoonBit 的 Bool 类型更清晰
extern "C" fn is_normal(input: 
Double
Double) -> 
Bool
Bool = "is_normal"

extern "C" fn sinf(input: 
Float
Float) -> 
Float
Float = "sinf"
extern "C" fn cosf(input: 
Float
Float) -> 
Float
Float = "cosf"
extern "C" fn tanf(input: 
Float
Float) -> 
Float
Float = "tanf"

extern "C" fn sin(input: 
Double
Double) -> 
Double
Double = "sin"
extern "C" fn cos(input: 
Double
Double) -> 
Double
Double = "cos"
extern "C" fn tan(input: 
Double
Double) -> 
Double
Double = "tan"

3.2 字符串 (Strings)​

事情在遇到字符串时开始变得有趣。你可能会想当然地把 C 的 char*​ 映射到 MoonBit 的 String​，但这是一个常见的陷阱。

​MoonBit​ 的 String​ 和 C 的 char*​ 在内存布局上完全不同。char*​ 是一个指向以 \0​ 结尾的字节序列的指针，而 MoonBit​ 的 String​ 是一个由 GC 管理的、包含长度信息和 UTF-16 编码数据的复杂对象。

参数传递：从 MoonBit 到 C

当我们需要将一个 MoonBit 字符串传递给一个接受 char*​ 的 C 函数时（如 parse_int​），我们需要手动进行转换。一个推荐的做法是将其转换为 Bytes​ 类型。

// 一个辅助函数，将 MoonBit String 转换为 C 期望的 null-terminated byte array
fn 
fn string_to_c_bytes(s : String) -> Bytes
string_to_c_bytes(
String
s: 
String
String) -> 
Bytes
Bytes {
  let mut 
Array[Byte]
arr = 
String
s.
fn String::to_bytes(self : String) -> Bytes
String holds a sequence of UTF-16 code units encoded in little endian format
to_bytes().
fn Bytes::to_array(self : Bytes) -> Array[Byte]
Converts a bytes sequence into an array of bytes.
Parameters:

bytes : A sequence of bytes to be converted into an array.
Returns an array containing the same bytes as the input sequence.
Example:
test {
  let bytes = b"hello"
  let arr = bytes.to_array()
  inspect(arr, content="[b'\\x68', b'\\x65', b'\\x6C', b'\\x6C', b'\\x6F']")
}
to_array()
  // 确保以 \0 结尾
  if 
Array[Byte]
arr.
fn[A] Array::last(self : Array[A]) -> A?
Returns the last element of the array, or None if the array is empty.
Parameters:

array : The array to get the last element from.
Returns an optional value containing the last element of the array. The
result is None if the array is empty, or Some(x) where x is the last
element of the array.
Example:
test {
  let arr = [1, 2, 3]
  inspect(arr.last(), content="Some(3)")
  let empty : Array[Int] = []
  inspect(empty.last(), content="None")
}
last() 
(x : Byte?, y : Byte?) -> Bool
!= 
(Byte) -> Byte?
Some(0) {
    
Array[Byte]
arr.
fn[T] Array::push(self : Array[T], value : T) -> Unit
Adds an element to the end of the array.
If the array is at capacity, it will be reallocated.
Example
test {
  let v = []
  v.push(3)
}
push(0)
  }
  
(ArrayView[Byte]) -> Bytes
Bytes::
fn Bytes::from_array(arr : ArrayView[Byte]) -> Bytes
Creates a new bytes sequence from a byte array.
Parameters:

array : An array of bytes to be converted.
Returns a new bytes sequence containing the same bytes as the input array.
Example:
test {
  let arr = [b'h', b'i']
  let bytes = Bytes::from_array(arr)
  inspect(
    bytes,
    content=(
      #|b"hi"
    ),
  )
}

test {
  let arr : FixedArray[Byte] = [b'h', b'e', b'l', b'l', b'o']
  let bytes = Bytes::from_array(arr)
  inspect(
    bytes,
    content=(
      #|b"hello"
    ),
  )
}
from_array(
Array[Byte]
arr)
}

// FFI 声明，注意参数类型是 Bytes
#borrow(s) // 告诉编译器我们只是借用 s，不要增加其引用计数
extern "C" fn __parse_int(s: 
Bytes
Bytes) -> 
Int
Int = "parse_int"

// 封装成一个对用户友好的 MoonBit 函数
fn 
fn parse_int(str : String) -> Int
parse_int(
String
str: 
String
String) -> 
Int
Int {
  let 
Bytes
s = 
fn string_to_c_bytes(s : String) -> Bytes
string_to_c_bytes(
String
str)
  
fn __parse_int(s : Bytes) -> Int
__parse_int(
Bytes
s)
}

​ ​#borrow​​ 标记 ​borrow​ 标记是一个优化提示。它告诉编译器，C函数只是"借用"这个参数，不会持有它的所有权。这可以避免不必要的引用计数操作，防止潜在的内存泄漏。

返回值：从 C 到 MoonBit

反过来，当 C 函数返回一个 char*​ 时（如 version​），情况更加复杂。我们绝对不能直接将其声明为返回 Bytes​ 或 String​：

// 错误的做法！
extern "C" fn version() -> 
Bytes
Bytes = "version"

这是因为 C 函数返回的只是一个裸指针，它缺少 MoonBit GC 所需的头部信息。直接这样转换会导致运行时崩溃。

正确的做法是，将返回的 char*​ 视为一个不透明的句柄，然后在 C "胶水" 代码中编写一个转换函数，手动将其转换为一个合法的 MoonBit 字符串。

MoonBit 侧：

// 1. 声明一个外部类型来代表 C 字符串指针
#extern
type CStr

// 2. 声明一个 FFI 函数，它调用 C 包装器
extern "C" fn 
type CStr
CStr::to_string(self: 
type CStr
Self) -> 
String
String = "cstr_to_moonbit_str"

// 3. 声明原始的 C 函数，它返回我们的不透明类型
extern "C" fn __version() -> 
type CStr
CStr = "version"

// 4. 封装成一个安全的 MoonBit 函数
fn 
fn version() -> String
version() -> 
String
String {
  
fn __version() -> CStr
__version().
fn CStr::to_string(self : CStr) -> String
to_string()
}

C 侧 (在 ​cwrap.c​​ 中添加):

#include <string.h> // for strlen

// 这个函数负责将 char* 正确地转换为带 GC 头的 moonbit_string_t
moonbit_string_t cstr_to_moonbit_str(char *ptr) {
  if (ptr == NULL) {
    return moonbit_make_string(0, 0);
  }
  int32_t len = strlen(ptr);
  // moonbit_make_string 会分配一个带 GC 头的 MoonBit 字符串对象
  moonbit_string_t ms = moonbit_make_string(len, 0);
  for (int i = 0; i < len; i++) {
    ms[i] = (uint16_t)ptr[i]; // 假设是 ASCII 兼容的
  }
  // 注意：是否需要 free(ptr) 取决于 C 库的 API 约定。
  // 如果 version() 返回的内存需要调用者释放，这里就需要 free。
  return ms;
}

这个模式虽然初看有些繁琐，但它保证了内存安全，是处理 C 字符串返回值的标准做法。

3.3 指针的艺术：传递引用与数组 (The Art of Pointers: Passing by Reference and Arrays)​

C 语言大量使用指针来实现"输出参数"和传递数组。MoonBit 为此提供了专门的类型。

单个值的"输出"参数

当 C 函数使用指针来返回一个额外的值时，如 tan_with_errcode(double input, double* output)​，MoonBit 使用 Ref[T]​ 类型来对应。

extern "C" fn tan_with_errcode(input: 
Double
Double, output: 
struct Ref[A] {
  mut val: A
}
Ref[
Double
Double]) -> 
Int
Int = "tan_with_errcode"

​Ref[T]​ 在 MoonBit 中是一个包含单个 T​ 类型字段的结构体。当它传递给 C 时，MoonBit 会传递这个结构体的地址。从 C 的角度看，一个指向 struct { T val; }​ 的指针和一个指向 T​ 的指针在内存地址上是等价的，因此可以直接工作。

数组：传递数据集合

当 C 函数需要处理一个数组时（例如 double* inputs​），MoonBit 使用 FixedArray[T]​ 类型来映射。FixedArray[T]​ 在内存中就是一块连续的 T​ 类型元素，其指针可以直接传递给 C。

extern "C" fn sin_array(len: 
Int
Int, inputs: 
type FixedArray[A]
FixedArray[
Double
Double], outputs: 
type FixedArray[A]
FixedArray[
Double
Double]) -> 
Int
Int = "sin_array"
extern "C" fn cos_array(len: 
Int
Int, inputs: 
type FixedArray[A]
FixedArray[
Double
Double], outputs: 
type FixedArray[A]
FixedArray[
Double
Double]) -> 
Int
Int = "cos_array"
extern "C" fn tan_array(len: 
Int
Int, inputs: 
type FixedArray[A]
FixedArray[
Double
Double], outputs: 
type FixedArray[A]
FixedArray[
Double
Double]) -> 
Int
Int = "tan_array"

3.4 外部类型：拥抱不透明的 C 结构体 (External Types: Embracing Opaque C Structs)​

对于 C 中的 struct​，比如 Complex​，最佳实践通常是将其视为一个"不透明类型"（Opaque Type）。我们只在 MoonBit 中创建一个对它的引用（或句柄），而不关心其内部的具体字段。

这通过 #extern type​ 语法实现：

#extern
type Complex

这个声明告诉 MoonBit："存在一个名为 Complex​ 的外部类型。你不需要知道它的内部结构，只要把它当成一个指针大小的句柄来传递就行了。" 在生成的 C 代码中，Complex​ 类型会被处理成 void*​。这通常是安全的，因为所有对 Complex​ 的操作都是在 C 库内部完成的，MoonBit 侧只负责传递指针。

基于这个原则，我们可以为 mymath.h​ 中与 Complex​ 相关的函数编写 FFI：

// C: Complex* new_complex(double r, double i);
// 返回一个指向 Complex 的指针，在 MoonBit 中就是返回一个 Complex 句柄
extern "C" fn new_complex(r: 
Double
Double, i: 
Double
Double) -> 
type Complex
Complex = "new_complex"

// C: void multiply(Complex* a, Complex* b, Complex** result);
// Complex* 对应 Complex，而 Complex** 对应 Ref[Complex]
extern "C" fn multiply(a: 
type Complex
Complex, b: 
type Complex
Complex, res: 
struct Ref[A] {
  mut val: A
}
Ref[
type Complex
Complex]) -> 
Unit
Unit = "multiply"

// C: void init_n_complexes(int n, Complex** complex_array);
// Complex** 在这里作为数组使用，对应 FixedArray[Complex]
extern "C" fn init_n_complexes(n: 
Int
Int, complex_array: 
type FixedArray[A]
FixedArray[
type Complex
Complex]) -> 
Unit
Unit = "init_n_complexes"

最佳实践：封装原生 FFI 直接暴露 FFI 函数会让使用者感到困惑（比如 Ref​ 和 FixedArray​）。强烈建议在 FFI 声明之上再构建一层对 MoonBit 用户更友好的 API。

// 在 Complex 类型上定义方法，隐藏 FFI 细节
fn 
type Complex
Complex::
fn Complex::mul(self : Complex, other : Complex) -> Complex
mul(
Complex
self: 
type Complex
Complex, 
Complex
other: 
type Complex
Complex) -> 
type Complex
Complex {
  // 创建一个临时的 Ref 用于接收结果
  let 
Ref[Complex]
res: 
struct Ref[A] {
  mut val: A
}
Ref[
type Complex
Complex] = 
struct Ref[A] {
  mut val: A
}
Ref::{ 
Complex
val: 
fn new_complex(r : Double, i : Double) -> Complex
new_complex(0, 0) }
  
fn multiply(a : Complex, b : Complex, res : Ref[Complex]) -> Unit
multiply(
Complex
self, 
Complex
other, 
Ref[Complex]
res)
  
Ref[Complex]
res.
Complex
val // 返回结果
}

fn 
fn init_n(n : Int) -> Array[Complex]
init_n(
Int
n: 
Int
Int) -> 
type Array[T]
An Array is a collection of values that supports random access and can
grow in size.
Array[
type Complex
Complex] {
  // 使用 FixedArray::make 创建数组
  let 
FixedArray[Complex]
arr = 
type FixedArray[A]
FixedArray::
fn[T] FixedArray::make(len : Int, init : T) -> FixedArray[T]
Creates a new fixed-size array with the specified length, initializing all
elements with the given value.
Parameters:

length : The length of the array to create. Must be non-negative.
initial_value : The value used to initialize all elements in the array.
Returns a new fixed-size array of type FixedArray[T] with length
elements, where each element is initialized to initial_value.
Throws a panic if length is negative.
Example:
test {
  let arr = FixedArray::make(3, 42)
  inspect(arr[0], content="42")
  inspect(arr.length(), content="3")
}
WARNING: A common pitfall is creating with the same initial value, for example:
test {
  let two_dimension_array = FixedArray::make(10, FixedArray::make(10, 0))
  two_dimension_array[0][5] = 10
  assert_eq(two_dimension_array[5][5], 10)
}
This is because all the cells reference to the same object (the FixedArray[Int] in this case).
One should use makei() instead which creates an object for each index.
make(
Int
n, 
fn new_complex(r : Double, i : Double) -> Complex
new_complex(0, 0))
  
fn init_n_complexes(n : Int, complex_array : FixedArray[Complex]) -> Unit
init_n_complexes(
Int
n, 
FixedArray[Complex]
arr)
  // 将 FixedArray 转换为对用户更友好的 Array
  
type Array[T]
An Array is a collection of values that supports random access and can
grow in size.
Array::
fn[T] Array::from_fixed_array(arr : FixedArray[T]) -> Array[T]
Creates a new dynamic array from a fixed-size array.
Parameters:

arr : The fixed-size array to convert. The elements of this array will be
copied to the new array.
Returns a new dynamic array containing all elements from the input fixed-size
array.
Example:
test {
  let fixed = FixedArray::make(3, 42)
  let dynamic = Array::from_fixed_array(fixed)
  inspect(dynamic, content="[42, 42, 42]")
}
from_fixed_array(
FixedArray[Complex]
arr)
}

3.5 函数指针：当 C 需要回调 MoonBit (Function Pointers: When C Needs to Call Back)​

​mymath.h​ 中最复杂的函数是 for_each_complex​，它接受一个函数指针作为参数。

void for_each_complex(int n, Complex** arr, void (*call_back)(Complex*));

一个常见的误解是试图将 MoonBit 的闭包类型 (Complex) -> Unit​ 直接映射到 C 的函数指针。这是不行的，因为 MoonBit 的闭包在底层是一个包含两部分的结构体：一个指向实际函数代码的指针，以及一个指向其捕获的环境数据的指针。

为了传递一个纯粹的、无环境捕获的函数指针，MoonBit 提供了 FuncRef​ 类型：

extern "C" fn for_each_complex(
  n: 
Int
Int,
  arr: 
type FixedArray[A]
FixedArray[
type Complex
Complex],
  call_back: FuncRef[(
type Complex
Complex) -> 
Unit
Unit] // 使用 FuncRef 包装函数类型
) -> 
Unit
Unit = "for_each_complex"

任何被 FuncRef​ 包裹的函数类型，在传递给 C 时，都会被转换成一个标准的 C 函数指针。

如何声明一个FuncRef​？只要使用let​就可以了，只要函数没有捕获外部变量，就可以声明成功。

fn 
fn print_complex(c : Complex) -> Unit
print_complex(
Complex
c: 
type Complex
Complex) -> 
Unit
Unit { ... }

fn main {
  let 
FuncRef[(Complex) -> Unit]
print_complex
FuncRef[(Complex) -> Unit]
 : FuncRef[(
type Complex
Complex
FuncRef[(Complex) -> Unit]
) -> 
Unit
Unit
FuncRef[(Complex) -> Unit]
] = (
Complex
c) => 
fn print_complex(c : Complex) -> Unit
print_complex(
Complex
c)
  // ...
}

第四站：高级课题——GC管理(Advanced Topic: GC Management)​

我们已经了解了大部分类型的转换问题，但还有一个非常重大的问题：内存管理。C 依赖手动的 malloc​/free​，而 MoonBit 拥有自动的垃圾回收（GC）。当 C 库创建了一个对象（如 new_complex​），谁来负责释放它？

可以不要GC吗？ ​

一些库作者可能会选择不做GC，而是把所有的析构操作都留给用户。这种做法在一些库上有其合理性，因为有些库，例如一些高性能计算库，图形库等，为了提高性能或者稳定性，本身就会放弃掉一些GC特性，但带来的问题就是对程序员的水平要求较高。大多数库还是需要提供GC来增强用户体验的。

理想情况下，我们希望 MoonBit 的 GC 能够自动管理这些 C 对象的生命周期。MoonBit 提供了两种机制来实现这一点。

4.1 简单情况​

如果 C 结构体非常简单，并且你确信它的内存布局在所有平台上都是稳定不变的，你可以直接在 MoonBit 中重新定义它。

// mymath.h: typedef struct { double real; double img; } Complex;
// MoonBit:
struct Complex {
  r: Double,
  i: Double
}

这样做，Complex​ 就成了一个真正的 MoonBit 对象。MoonBit 编译器会自动为它管理内存，添加 GC 头。当你把它传递给 C 函数时，MoonBit 会传递一个指向其数据部分的指针，这通常是可行的。

但这种方法有很大的局限性：

• 它要求你精确知道 C 结构体的内存布局、对齐方式等，这可能很脆弱。
• 如果 C 函数返回一个 Complex*​，你不能直接使用它。你必须像处理字符串返回值一样，编写一个 C 包装函数，将 C 结构体的数据复制到一个新创建的、带 GC 头的 MoonBit Complex​ 对象中。

因此，这种方法只适用于最简单的情况。对于大多数场景，我们推荐更健壮的析构方案。

4.2 复杂情况，使用析构函数（Finalizer） (The Complex Situation: Using Finalizers)​

这是一种更通用和安全的方法。核心思想是：创建一个 MoonBit 对象来"包装"C 指针，并告诉 MoonBit 的 GC，当这个包装对象被回收时，应该调用一个特定的 C 函数（析构函数）来释放底层的 C 指针。

这个过程分为几步：

1. 在 MoonBit 中声明两种类型

#extern
type C_Complex // 代表原始的、不透明的 C 指针

type Complex C_Complex // 一个 MoonBit 类型，它内部包装了一个 C_Complex

​type Complex C_Complex​ 是一个特殊的声明，它创建了一个名为 Complex​ 的 MoonBit 对象类型，其内部有一个字段，类型为 C_Complex​。我们可以通过 .inner()​ 方法访问到这个内部字段。

2. 在 C 中提供析构函数和包装函数

我们需要一个 C 函数来释放 Complex​ 对象，以及一个函数来创建我们带 GC 功能的 MoonBit 包装对象。

C 侧 (在 ​cwrap.c​​ 中添加):

// mymath 库应该提供一个释放 Complex 的函数，假设是 free_complex
// void free_complex(Complex* c);

// 我们需要一个 void* 版本的析构函数给 MoonBit GC 使用
void free_complex_finalizer(void* obj) {
    // MoonBit 外部对象的布局是 { void (*finalizer)(void*); T data; }
    // 我们需要从 obj 中提取出真正的 Complex 指针
    // 假设 MoonBit 的 Complex 包装器只有一个字段
    Complex* c_obj = *((Complex**)obj);
    free_complex(c_obj); // 调用真正的析构函数, 如果mymath库提供的话
    // free(c_obj); // 如果是标准的 malloc 分配的
}

// 定义 MoonBit 的 Complex 包装器在 C 中的样子
typedef struct {
  Complex* val;
} MoonBit_Complex;

// 创建 MoonBit 包装对象的函数
MoonBit_Complex* new_mbt_complex(Complex* c_complex) {
  // `moonbit_make_external_obj` 是关键
  // 它创建一个由 GC 管理的外部对象，并注册其析构函数。
  MoonBit_Complex* mbt_complex = moonbit_make_external_obj(
      &free_complex_finalizer,
      sizeof(MoonBit_Complex)
  );
  mbt_complex->val = c_complex;
  return mbt_complex;
}

3. 在 MoonBit 中使用包装函数

现在，我们不直接调用 new_complex，而是调用我们的包装函数 new_mbt_complex。

// FFI 声明指向我们的 C 包装函数
extern "C" fn __new_managed_complex(c_complex: 
type C_Complex
C_Complex) -> 
type Complex
Complex = "new_mbt_complex"

// 原始的 C new_complex 函数返回一个裸指针
extern "C" fn __new_unmanaged_complex(r: 
Double
Double, i: 
Double
Double) -> 
type C_Complex
C_Complex = "new_complex"

// 最终提供给用户的、安全的、GC 友好的 new 函数
fn 
type Complex
Complex::
fn Complex::new(r : Double, i : Double) -> Complex
new(
Double
r: 
Double
Double, 
Double
i: 
Double
Double) -> 
type Complex
Complex {
  let 
C_Complex
c_ptr = 
fn __new_unmanaged_complex(r : Double, i : Double) -> C_Complex
__new_unmanaged_complex(
Double
r, 
Double
i)
  
fn __new_managed_complex(c_complex : C_Complex) -> Complex
__new_managed_complex(
C_Complex
c_ptr)
}

现在，当 Complex::new 创建的对象在 MoonBit 中不再被使用时，GC 会自动调用 free_complex_finalizer，从而安全地释放了 C 库分配的内存。

当需要将我们管理的 Complex 对象传递给其他 C 函数时，只需使用 .inner() 方法：

// 假设有一个C函数 `double length(Complex*);`
extern "C" fn length(c_complex: 
type C_Complex
C_Complex) -> 
Double
Double = "length"

fn 
type Complex
Complex::
fn Complex::length(self : Complex) -> Double
length(
Complex
self: 
type Complex
Self) -> 
Double
Double {
  // self.inner() 返回内部的 C_Complex (即 C 指针)
  
fn length(c_complex : C_Complex) -> Double
length(
Complex
self.
() -> C_Complex
inner())
}

结语 (Conclusion)​

这篇文章带你从基本类型，到复杂的结构体类型，再到函数指针类型，梳理了在MoonBit中做C-FFI的流程。末尾讨论了MoonBit管理c对象的GC问题。希望对广大读者的库开发有帮助。