关于 go:架构特定的 Golang 函数的文档

Documentation for architecture-specific Golang function

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

更多细节:

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

实现的结构类似于此要点。在高层次上:

  • 在通用(非 amd64 情况)中,该函数是通过委托给
    addGeneric
  • amd64 的情况下,函数实际上是一个变量,最初设置为
    addGeneric 但在 init 函数中替换为 addAsm 如果 CPUID
    检查通过。

这种方法有效。但是 godoc 输出很糟糕,因为在
amd64 情况下函数实际上是一个变量。注意 godoc 似乎是
拾取与运行它的机器相同的构建标签。我不确定
godoc.org 会做什么。

考虑的替代方案:

  • Add 函数委托给 addImpl。然后我们拉一些类似的技巧
    amd64 的情况下替换 addImpl。这个问题是(在我的
    实验)Go 似乎无法内联调用,而汇编
    现在包含在两个函数调用中。由于组件已经很小了
    这对性能有显着影响。
  • amd64 的情况下,我们定义了一个普通函数 Add,它具有 useAsm
    检查里面,并调用 addGenericaddAsm 取决于
    结果。这将对性能产生更严重的影响。

所以我想问题是:

  • 有没有更好的方法来构造代码以实现我的性能
    想要,并让它正确地出现在文档中。
  • 如果没有其他选择,还有其他方法可以"欺骗"godoc吗?

  • 有关如何执行此操作的示例,请参见 math.Sqrt。

    • 使用文档编写Stubbing函数
    • 将通用实现编写为未导出的函数。
    • 对于每个架构,在汇编程序中编写一个函数,该函数会跳转到未导出的通用实现或直接实现该函数。

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