特定于体系结构的 Golang 函数的文档

Question

我有一个函数，我想为其提供程序集实现 关于 amd64 架构。为了便于讨论，我们假设它是一个 Add 函数，但实际上比这更复杂。我有 汇编版本有效，但我的问题是让 godoc 显示 正确。我有一种感觉这是目前不可能的，但我想寻求 建议。

更多细节：

• 这个函数的汇编实现只包含了几个 指示。特别是，调用该函数的成本仅为 整个成本的很大一部分。
• 它使用特殊指令（BMI2）因此只能使用 CPUID 能力检查之后。

实施是structured like this gist。高层次：

• 在一般情况下（非 amd64 情况下）函数是通过委托给定义的 addGeneric.
• 在amd64的情况下函数实际上是一个变量，初始设置为 addGeneric 但在 init 函数中被 addAsm 替换，如果 cpuid 检查通行证。

这种方法有效。然而 godoc 输出很糟糕，因为在 amd64 case函数实际上是一个变量。注意 godoc 似乎是 选择与 运行 所在机器相同的构建标签。我不确定 godoc.org 会做什么。

考虑的备选方案：

• Add 函数委托给 addImpl。然后我们使用一些类似的技巧 在 amd64 情况下替换 addImpl。这个问题是（在我的 实验）Go 似乎无法内联调用，并且程序集 现在包含在两个函数调用中。由于组件已经很小 这对性能有显着影响。
• 在 amd64 的情况下，我们定义了一个具有 useAsm 的普通函数 Add 检查里面，并调用 addGeneric 和 addAsm 之一 结果。这会对性能产生更糟糕的影响。

所以我想问题是：

1. 有没有更好的方法来构造代码来实现我的性能 想要，并让它在文档中正确显示。
2. 如果别无选择，有没有其他方法可以"trick" godoc？

Answer 1

有关如何执行此操作的示例，请参阅 math.Sqrt。

• 写一个stub function with the documentation
• 写一个generic implementation as an unexported function.
• 对于每个体系结构，在汇编程序中编写一个函数 jumps to the unexported generic implementation or implements the function directly。

为了处理 cpuid 检查，在 init() 中设置一个包变量，并在程序集实现中根据该变量有条件地跳转。