分类存档: Coding

编写 .NET 与非托管资源互操作的绑定代码

TL;DR

建议使用 ClangSharpPInvokeGenerator 生成 P/Invoke 绑定代码。在需要人工介入的情况下可以参照本文前半部分介绍绑定技巧的部分进行修改。生成绑定后仍然建议对其二次封装使之更符合 .NET 的使用习惯。

展示

我在 OptimeGBA.io 中手写了 libvpx 的绑定,而用 ClangSharpPInvokeGenerator 生成了 libopenh264 的绑定,供各位对比绑定生成的质量。此外,这两个库的二次封装也可作为案例参考如何将 .NET 与非托管资源的互操作体验更加原生。

运行效果可以在此体验:https://aws.martincl2.me/OptimeGBA.io/。部署的版本使用了 h264 编码。

P/Invoke 是什么

P/Invoke 是 .NET 中与二进制代码库互操作的机制。得益于 .NET 优秀的底层操作能力,P/Invoke 可以在没有额外非托管代码包装的情况下直接与二进制接口互操作。相较 Java 的 JNI 或是 Node.js 的 V8 binding 之下,P/Invoke 可以省去一部分 native code 编译链的耦合,而更重要的是 P/Invoke 的绑定不受 .NET 大版本更新的影响,即一次绑定,所有大版本兼容。

P/Invoke 举例来说, getpid 的 C 接口可以被直接在 C# 中引用:

当然, getpid 是极为简单的例子。常见的互操作中需要使用更为复杂的结构体、指针、生命周期管理,同时还要保证 C# 侧调用的时候能尽可能贴合 C# 的代码风格。此文就以我在 OptimeGBA.io 中的经验为基础,简单分享一下如何迅速而优雅地为一个二进制库实现 P/Invoke 绑定。

生成 P/Invoke 绑定

简单结构体

C# 的结构体声明与内存结构(Layout)几乎是完美兼容 C 的。甚至对于一个简单的结构体而言,只需要简单的复制粘贴就能完成绑定。例如以下的 C 结构体便可以直接翻译为 C# 的结构体:

其中字段的顺序、大小,甚至是内存对齐( byte b 后会留空三字节),C# 都与 C 的行为一致。

翻译 typedef – 预设别名

C 接口中大量使用了 typedef,甚至可以说是无可避免地会使用 typedef,因为在实际操作上 C 依赖各种编译器预设的 typedef 来实现跨平台源代码兼容,因而 C 标准库中的函数签名就大量使用了 typedef。例如在上文 getpid 的例子中,该函数的返回值是 pid_t,而如果在 amd64 的目标平台编译器下顺着标准库的头文件查找并且把 typedef 的声明全都实体化,最终就会发现 pid_t 在本平台的定义实际上是 int

在 C# 中显然并没有诸如 pid_t 的类型别名,因此在写 P/Invoke binding 的时候需要逐个找到这些别名在本平台的实际定义。通常这在 IDE 环境下跳转几次就能找到了。如果对结果不确定可以用 sizeof 验算一下字段长度——毕竟只要字段长度对了,最不济也就一个字段数据不对,而如果长度错了那后面的字段偏移量就全部完蛋了。

此外,虽说如今主流平台的这些 *_t 类型的实际类型基本上是一致的,还是要小心跨平台的时候会有平台差异。

翻译 typedef – 自定义别名

一些情况下 typedef 可以为某个类型设置一个友好而可读的别名。例如说在 C API 中非常常见的一种做法是在结构体或参数里放一个 void* 存放一些内部实现相关的数据。调用方并不需要知道这个指针怎么来的以及存了什么,而只需要保证指针传递到了就行。而此时设计函数签名的时候就可以通过 typedef 给这个 void* 设置别名以便跟别的指针做出区隔:

虽说 C 编译器不会对设置了别名的 void* 做出任何区隔,换言之随便传一个指针进去都能通过编译(然后运行的时候爆炸),但在函数中使用了别名后作为调用方可以更直观地理解应该具体传什么指针进去而不是完全依赖阅读文档。

而当翻译这段 API 到 C# 的时候,固然可以直接使用 void* 作为变量类型,但也可以通过一个但字段的结构体包装这个指针以达到类似 typedef 的效果,甚至可以通过这种方法在编译时就能完成指针类型的检查:

由于这个包装的结构体的数据长度和一个指针完全相同,通过包装结构体定义的函数签名与使用指针在效果上是同样的。

Enum

C 的枚举类型本质上是 int——「正巧」C# 也是。因此如果 C header 中有 enum 的定义,或是函数签名中有用作 flag 的 int,都可以用 C# 替换。例如:

* 与其说是「正巧」应该说是 C# 一步到位直接把 enum 的语法与行为定义为与 C 一致。

如果万一遇到不一致的情况,或是需要手动调整字段的内存布局,则可以使用 StructLayoytFieldOffset 作细致的调整。具体可以参照下文介绍 union 的部分。

Fixed buffer

在 C 标准中,结构体上是可以定义固定长度的数组的。例如:

对于不熟悉 C 的读者请注意:这不同于定义一个指针字段并赋值一个数组指针(如 int* plane),这个数组字段的实际数据是存在于结构体内部的,因而在使用的时候编译器只需简单地将结构体的指针偏移几个字段就能拿到这个定长数组的指针。

而在 C# 中,简单情况下可以用 fixed buffer 声明这种数组:

但是 C# 目前只支持 primitive unmanaged type 用作 fixed buffer,也就是 intulong 等类型。换言之,结构体或指针之类的数据类型就不能这样定义了。这种情况下就必须手动展开了:

Union

Union 是一种 C 中非常常用的结构体布局。具体而言,union 允许将多个不同的数据段存储在同一段内存中。例如:

在 C# 中可以通过手动指定字段偏移量的方式定义一个 union 结构体。结构体上的 StructLayoyt 属性告诉编译器一个结构体需要手动设置字段偏移量,而字段上的 FieldOffset 属性则设置了具体字段偏移量的数值。对于 union 而言,只需要将 FieldOffset 全部设置为 0 即可。

自动生成绑定

虽说以上讲了这么多使用场景、解决方案与技巧,在了解与攻破了这些场景以后写绑定这件事本身其实是个体力活。尤其是 C header 很可能散落各地,编排顺序也并无逻辑,而逐个翻译 header 中的每一个定义既吃力又容易出错。那么有没有方便又可靠的工具可以一键无脑生成绑定代码的呢?有!那便是 ClangSharpPInvokeGenerator

Clang 是 llvm 工具链中处理 C 与 C++ 的前端。编译器里的前端大致上指的是处理分析源代码的部分——将源代码 parse 成抽象语法树(AST)、分析符号、处理宏,等等。而 ClangSharp 是一个 Clang 的 C# 绑定,换言之,ClangSharp 是一个在 .NET 中处理 C/C++ 源代码的工具。为何要花篇幅介绍 Clang?因为 Clang 普遍认为是最模组化、功能齐全,而业界又广泛采用的 C/C++ 前端。也就是说,如果采用 ClangSharp 分析 C/C++ 源码,将会得到与业界主流编译器 clang 完全一致的结果。这也就意味着 ClangSharp 可以为自动生成 P/Invoke 绑定提供非常可靠的信息源。顺带一提,这与 C# 编译器 Roslyn 的设计目的之一相同:编译器一次实现,多处应用,包括编译本身、静态分析、Language Server (IDE 集成)等等,以保证结果的一致性。

* 注:ClangSharp 本身就是通过 ClangSharpPInvokeGenerator 自己生成的绑定代码。

安装 ClangSharpPInvokeGenerator:

生成绑定:

然后将生成的绑定代码复制到项目的源码即可。

* 注意有一些库同时提供了 C 与 C++ 的头文件。这种情况下通常直接为 C++ 的头文件生成绑定会让生成的代码更干净。

通常来说生成的绑定无需修改已经足够可读了。不对生成的代码作任何修改可以保证今后再次生成头文件时可以无缝升级。当然我也遇到了一些不理想的生成,例如有一些库将 enum 通过 #define 定义为了常数,我会手动将其改成 enum。

将绑定封装为 .NET 库

绑定其实只完成了一半的工作。为了让非托管库的调用更符合 .NET 的使用习惯,同时也保证调用安全、减少 unsafe 的使用,我们仍然需要对绑定代码作二次封装。毕竟都用 .NET 了,总不能让调用方仍然手动操作指针吧。

内存管理——IDisposable

.NET 拥有 GC,而非托管代码则并没有。因而使用 P/Invoke 的时候要格外注意来自非托管对象的生命周期。

以 libvpx(已简化)为例,一个典型的 C 库需要这样管理生命周期:

对于手动管理生命周期的运行时而言,分配与销毁必须成对出现,包括出现异常的情况下,不然轻则内存泄漏,重则整个进程原地爆炸。

.NET 标准库中的 IDisposable 则提供了一个统一且设计良好的范式——调用方既可以通过 using 语句实现类似 RAII 的作用域级自动释放,也可以将非托管资源的生命周期与托管资源的生命周期(GC)挂钩自动释放。

举例而言,上述 libvpx 的例子使用 IDisposable 封装:

IDisposable 的模板看着很庞大,但其实已经考虑好了各种边角情况,因此最好还是按照模板实现。

内存操作——Span<T>

.NET 一类的托管语言的一大卖点在于全自动的边界检查。在 .NET 的数组中任何越界的访问都会触发异常,而不是造成越界访问的漏洞。然而在非托管资源上边界检查往往要手动实现。在 .NET 中,我们可以借助 Span<T> 对非托管内存块进行封装。

例如说一个典型的 C 结构会这样暴露一段内存:

使用 Span<T> 封装后:

迭代器——IEnumerable<T>

迭代器是非常常见的一种范式,但在非托管代码中的实现不尽相同。既然要封装成 .NET 库,就要让迭代器的使用体验更接近原生的 .NET 代码。

例如 libvpx 中,要获得编码后的帧数据需要多姿迭代,其 C 接口需要这样使用迭代器(代码已简化):

而 .NET 中的标准迭代器是 IEnumberable<T>,也就是 C# 中的 foreach 语句所使用的接口。因此这个 libvpx 的例子理想情况下在 C# 中的调用应该大致上是这样的:

为了达到这个效果, IEnumerable<VpxPacket> 的实现可以写作:

当然,如果为了追求零分配,也可以手写 struct Enumerable 与 struct Enumerator,只不过会长得多:

异步回调——Task<T>

在一些涉及到 IO 的非托管库中可能会提供基于回调的异步调用的接口,例如:

这种情况下可以用 TaskCompletionSource<T> 来将回调封装成异步调用( async/ await):

此外,如果该非托管库还支持 Cancellation Token,那一定要做好对接。

由于 OptimeGBA.io 项目中并未涉及到非托管回调,我手头并没有足够的案例,也因此暂无法展开更多细节。有机会的话再开坑补充。

va_list——建议手动添加签名

C 标准是支持可变参数的函数签名的。尽管 P/Invoke 也可以通过 __arglist 兼容此类函数签名,但其适用范围非常受限(例如很难多级传递),文档也非常模糊。个人建议不如根据实际调用情况多写几个函数签名。

结语

.NET 通过 P/Invoke 对非托管库的调用由于 ClangSharp 的出现在工程上让本就颇为强大的 P/Invoke 更具可行性与可维护性。但是要让 .NET 与非托管资源之间的互操作更贴近原生体验还是需要话心思作二次封装。在此也再次欢迎读者阅读 OptimeGBA.io 项目中的 libvpx(手写绑定)与 libopenh264(ClangSharp 生成绑定)交互代码作为参考案例。

为 ES2018 移植的 LINQ 方法

为 ES2018 移植的 LINQ 方法

源码:https://github.com/Martin1994/es2018-linq

NPM:https://www.npmjs.com/package/es2018-linq

前言

自我在短暂的金融业生涯中短暂地接触过 C# 之后,对 C# / .NET 的喜爱便一发不可收拾,即便从此之后的工作中再没机会使用 .NET 却依然保持着对其的关注,而这份关注与喜爱这也一直延续到了 Andre 老爷子如今的工作重心——TypeScript。

最近在工作中大量使用了 TypeScript,但却苦于没有合适的函数式编程工具箱。underscore/lodash 对异步方法的支持有限且不支持延迟执行;RxJS 又感觉太过重量级、强制异步,而 API 又自成一派。有 C# 背景的我自然是以 LINQ 对标这些库,所以我想要不干脆自己移植一份 LINQ 好了。

LINQ

有些朋友可能对 C# 或是 LINQ 不太了解,在这里做一下简单的介绍。

LINQ 最初是设计成在 C# 代码中可以用类似 SQL 的方式操作一个可迭代对象(Enumerable),可以是普通的本地数据结构,甚至也可以是封装好的数据库操作。例如这个官方提供的样例

然而据我的理解,真正在代码里用 LINQ 语句的人并不多……大多数情况 LINQ 是直接通过扩展方法调用的:

继续阅读 »

在 .NET Core 3.0 中实现 JIT 编译的 JSON 序列化,及一些心得与随想

源码:https://github.com/Martin1994/JsonJitSerializer

NuGet:https://www.nuget.org/packages/MartinCl2.Text.Json.Serialization/

简介:Just-in-time 编译的 JSON 序列化

.NET Core 3.0 即将正式发布,其中一项令人振奋的功能是 corefx 集成了一个 JSON 库用来替代 JSON.NET,目前我按照 namespace 称这套库为 System.Text.Json。

这一套 JSON 库吸取了一部分 JSON.NET 的教训,将 API 的功能尽可能分离。例如它除了提供了 Object 与 String/Stream 之间的序列化与反序列化的高层 API 之外,还提供了逐 token 读写的底层 API。这为第三方开发者实现自己的 JSON 库提供了极大的方便。

了解到这一点后我意识到可以用这套底层 API(具体来说是 Utf8JsonWriter)来实现一个 just-in-time 编译(本质上其实是 IL generation)的 JSON 序列化库。

为何 JSON 序列化可以从 JIT 中受益呢?

System.Text.Json 实现 JSON 序列化的步骤是:

  1. 利用反射读出需要序列化的 class 的结构;
  2. 缓存每个需要序列化的 property,包括其名字(用 UTF-8 存储)、getter method 以及对应的 converter;
  3. 每次需要序列化的时候逐条读取这个结构化的缓存并利用 Utf8JsonWriter 序列化为 JSON stream。

可以注意到步骤 2 到 3 其实有点类似于解释执行的脚本语言。既然是解释执行,那自然可以有其对应的 JIT 优化,将解释的内容直接编译成可执行的代码。这样可以省去一些存取的开销和动态类型检查的开销。具体可以减小多少开销可以参照 benchmark 的结果:

Method Mean StdDev Median Min Max Gen 0/1k Op Gen 1/1k Op Allocated Memory/Op
System.Text.Json_Async 592.6 ns 1.3711 ns 592.6 ns 590.9 ns 594.8 ns 0.0471 304 B
MartinCl2.Text.Json_Async 346.0 ns 1.6620 ns 345.4 ns 344.4 ns 349.2 ns 0.0239 152 B

继续阅读 »

正确配置 vc4-fkms-v3d 驱动,避免使用 llvmpipe

vc4-fkms-v3d 是树莓派的开源 GPU 驱动,支持 OpenGL 2.1。正确配置的情况下 mesa 应该使用 V3D 驱动而不是 llvmpipe,后者使用的是 CPU。树莓派本来就贫弱的 CPU 并不经得起桌面渲染的折腾。此外 Chrome 也应能打开大多数硬件加速。

首先需要切换到开源驱动。前往 raspi-config -> Advanced Options -> GL Driver -> GL (Fake KMS)。树莓派 4 是默认使用这个开源驱动的。

继续阅读 »

将树莓派用作 SD 读卡器

需求

  • 树莓派
  • SD 卡 2 张,其中一张可引导系统
  • USB 存储(可选)

不需要

  • SD 读卡器
  • 显示器
  • 键盘

最近买了第四代树莓派,但等到 SD 卡寄到了我才意识到我的读卡器忘记带在身边了。环顾四周,唯一有 SD 卡槽的居然只有那只老的树莓派 3B+。理论上我可以直接用 U 盘引导系统,但我不知为何一直无法成功。我更无法冒险将唯一可以引导系统的 SD 卡改为引导到 U 盘,因为万一失败了我在搞到读卡器之前都再也进不去系统了。

于是我就想到了一个骚操作:先用一张 SD 卡引导系统,ssh 进去,然后利用 pivot_root 将 root 转移到 SD 卡以外的地方(U 盘或者内存盘),这样我就能把引导系统的 SD 卡拔下来换新的上去了。全程都可以在 ssh 上完成。

继续阅读 »

在 MSYS2 中安装 Git for Windows 并自定义 PATH 中的 toolchain

背景

Git Bash 在 WSL 出现之前一直是 Windows 开发必不可少的工具。哪怕不使用 unix toolchain,git 也是免不了要用的。在 WSL 出现后它依然没有退出历史舞台——至少 VS Code 目前还需要 Git for Windows 来整合 git 功能。此外,Git bash 是基于 MSYS2 开发的,而 MSYS2 在一些从 *nix 移植到 Windows 的项目上不可或缺。

然而,Git for Windows 中的 MSYS2 环境是刻意缩减过的。最重要的是他没有 pacman 包管理系统。如果不想装两份 MSYS2(一份完整的,一份 Git for Windows),那么 Git for Windows 官方提供了两种方案:使用 Git for Windows SDK,或在已有的 MSYS2 中安装 Git for Windows SDK

注:Git for Windows 修改过 MSYS2 的运行环境。未经修改的运行环境不能很好的在 Windows 下互操作,例如 Powershell 中连 git status 都会无法执行。因此在 MSYS2 中安装 Git for Windows 会覆盖原版的 MSYS2 运行环境。

摆脱 SDK

Git for Windows SDK 是一套为了开发 Git for Windows 而存在的环境。把这套 SDK 当 MSYS2 使用会有诸多不便。我只是想把完整的 MSYS 和 Git for Windows 合二为一而已,但在已有的 MSYS2 中安装 Git for Windows SDK 教程中却把 SDK 一同装上了。不装 SDK 其实很简单,不安装 git-extra 包即可。也就是最后一步的命令改为: pacboy sync git:x git-doc-html:x git-doc-man:x curl:x

继续阅读 »

TypeScript on Electron 解决 Renderer 没有 exports 的问题

Electron 的 Renderer process 虽然和 main process 是不同的进程,但依然可以使用 node 的环境,比如 require(‘fs’) 之类. 但如果一个 js 脚本是在浏览器环境中用 <script> 标签加载的话,exports 变量是缺的,会报 exports is not defined.

而解决方法是不要使用 <script src=”./script.js”></script> 而是 <script>require(‘script’);</script>. 这样所有的脚本就是以 module 的方式加载而不是页面脚本了. 以 module 方式加载的脚本是有 exports 变量的.

继续阅读 »

使用 VSCode 运行 Task 并自动 Attach Debugger

本文将讲述如何在 VSCode 中使用 Attach 模式 Debug 的时候,也能像 Launch 模式一样一键启动 Debuggee. 具体原理是使用 preLaunchTask 并将此 Task 的 isBackground 属性设置为 true.

VS Code Debug Protocol 描述了两种不同的 Debug 方式:Launch 以及 Attach. 他们分别对应了 VSCode 负责启动程序并 Debug,以及 VSCode 去 Debug 一个正在运行的程序,包括非本地的程序.

其中,Launch 模式的潜在含义是,VSCode 将负责管理 Debuggee 的生命周期,也就是说 VSCode 负责启动及停止,而这些操作对于用户而言就是按一下按钮. 反观 Attach 则是另一种设计:用户必须自行启动 Debuggee,可以在本地可以在远程,只要 Debugger 能够与之通信,而 VSCode 只负责将 Debugger 与 Debuggee 对接.

在本地开发本地运行本地调试的情况下,Launch 无疑是最好的选择,因为一旦配置完毕,今后 Debug 只需要一键启动及一键停止. 这种开发环境十分的理想化,尽管可以满足大多数需求,但当环境变得复杂时,Attach 模式将是无法避免的. 例如执行代码的机器一定是在远程,这常见于跨平台开发,包括在 Windows 上使用 WSL 做 Linux 开发,以及使用 QEMU + GDB 做内核开发. 尽管微软在近期对一些官方插件就 WSL 进行了优化,即可以使用 Launch 模式在 WSL 中运行程序,但第三方插件仍然不可避免地需要使用 Attach.

继续阅读 »

在 WSL 中使用 ssh-agent

在阅读前请注意,ssh-add 在没有 keychain 的情况下只能临时保存 SSH key. 也就是说重启 ssh-agent 后需要重新 ssh-add. 若要永久添加某个 SSH key,最快捷的方法是在 ~/.ssh/config 中添加 IdentityFile. 但如果要使用 SSH agent forwarding,就需要 ssh-agent 了.

在 WSL 中自动启用 ssh-agent 并不是那么直接,因为 WSL 的入口 bash.exe 并不能继承来自父进程关于 ssh-agent 的环境变量,毕竟父进程是个 Windows 进程. 此外另一点特殊的地方在于,当所有 bash.exe 进程结束的时候,所有的 WSL 进程会被杀掉,包括 ssh-agent.

ssh-agent 的启动比较特殊. 手动启动的方式是:

这是因为 ssh-agent 默认执行两件事:1. 后台运行 ssh-agent;2. 输出一段 shell script 以供执行. 这段 shell script 中包含着与这次启动的 ssh-agent 通信所需的环境变量.

一般情况下,例如在 Linux 桌面环境里,在桌面环境启动前 ssh-agent 就被启动并且环境变量也被设置了. 之后启动的桌面环境,以及桌面环境启动的 Terminal 都会自动继承这个环境变量.

继续阅读 »

Lambert W function 数值计算

由于一些很蠢的原因,我写了一份完全用不着的用于计算 Lambert W function 的 C# 代码. 具体原理是很粗暴的牛顿法求解,但有几个特别处理的地方:

首先是估算. W0比较好处理,其实随便给个初始值就好,我这里选择了偏移后的 ex. 而 W-1 则比较特殊,首先在 x < -2 的部分变成了 concave 的,而且越往左斜率越小,所以一律从 x = -2 开始尝试;而在 -2 < x < -1 的区间内其实也是随便给个初始值就好,我这里选择了偏移后的 cos 函数.

其次是精度处理. 通过 log2x 做差可以求出二进制下的有效数位,然而当 y 值较大的时候其实并不能把完整的 52 位双精度浮点数的小数部分求完整,大概只能求到 47 位左右,所以这里我保守选择了 42 位有效数字.

继续阅读 »