[译][Perl 6] Native Calling Interface

About

• Perl 6 document(2016-03-25)

• 翻译

Translation

原文

按照C调用约定调用动态库

入门指南

最简单的能想象出的 NativeCall 应该类似于这样：

use NativeCall; sub some_argless_function() is native('something') { * } some_argless_function();

改变名字

有时你想要你的 Perl subroutine 使用一个与加载的库中原本不同的名字，这个名字可能长一点或者有不同的大小写或者在你想要创建的模块的上下文中的其他繁琐的名字。NativeCall 支持一个“symbol”trait，这使你可以指定你的 Perl subroutine 使用与库中原生 routine 不同的名字。

module Foo; use NativeCall; our sub init() is native('foo') is symbol('FOO_INIT') { * }

在“libfoo”库里面有一个 routine 叫“FOO_INIT”，因为我们创建了一个模块叫做Foo，我们宁愿使用 Foo::init 调用子例程，我们使用“symbol”特性指定在“libfoo”库名字符号的名字，以任何我们想要的方式调用这个 subroutine（这种情况下是“init”）。

参数传递和返回值

普通的 Perl 6 signatures 和 returns trait 的使用是为了传达原生函数期望的参数类型以及返回的类型，下面举个例子：

sub add(int32, int32) returns int32 is native('calculator') { * }

这里，我们声明这个函数接受两个32位整型的参数，返回一个32位整数。下面是一些其它你可能需要传递的参数类型（以后会慢慢增加）。

int8            （c中的char） int16           （c中的short) int32           （c中的int) int64           （明确的64位int，就像C99中的int64_t） long            （32位或者64位，依赖与本地long） longlong        （至少64位，跟本地的long long一样） num32           （c中的float） num64           （c中的double） Str             （c中的string，即char *） CArray[int32]   （c中的int*，一个整型的数组） Pointer[void]   （c中的void*，可以指向任何其它类型） bool            （C99中的bool） size_t          （C中的size_t） 

sub message_box(Str is encoded('utf8')) is native('gui') { * }

为了指定如何对返回类型进行编组，只需要在 routine 本身加上这个特性即可。

sub input_box() returns Str is encoded('utf8') is native('gui') { * }

# C 原型是 void set_foo(const char * foo) sub set_foo(Str) is native('foo') { * }  # C 原型是 void use_foo(void) sub use_foo() is native('foo') { * } # 将会使用set_foo函数设置的指针  my $string = "FOO";  # 变量的生命期必须与 C 函数期待的生命期相等 my $array = CArray[uint8].new($string.encode.list);  set_foo($array); # ... 其它代码 use_foo(); # 使用完毕之后，$arrray就可以安全的销毁了

指针的基本使用

当你的原生函数 signature 需要一个指向原生类型（ int32 、 uint32 等等）的指针时，所有你需要做的就是为参数加上 is rw ：

# C 原型是 void my_version(int *major, int *minor)  sub my_version(int32 is rw, int32 is rw) is native('foo') { * }  my int32 ($major, $minor); ... my_version($major, $minor); //传递一个指针

有的时候你需要获取一个从C库返回的指针（比如一个库句柄），你不需要这个它指向什么 - 你只需要保存它就可以了，Pointer 类型就是为此而生的：

sub Foo_init() returns Pointer is native('foo') { * } sub Foo_free(Pointer) is native('foo') { * }

这个可以正常工作，但是你可能梦想可以使用某种比 Pointer 更好的类型一起工作，实际上任何声明为“CPointer”的类都可以充当这个角色，这意味着你可以通过编写一个工作在句柄上的类暴露库，就像这样：

class FooHandle  is repr('CPointer') {     has $!initialized;      # 这里是一些实际的*原生调用*函数     sub Foo_init() returns FooHandle is native('foo') { * }     sub Foo_free(FooHandle) is native('foo') { * }      # 这里是我们要使用的方法，它们可以让类暴露自己给外界     method new() {         Foo_init();         $!initialized = True;     }      method free() {         if $!initialized {             Foo_free(self);             $!initialized = False; # 防止double free错误         }     }      # 当对象被垃圾收集时释放数据     method DESTROY() {         self.free;     } }

注意 CPointer 声明的类除了保持一个 C 指针，并不能做更多的事情，这意味着你的类不能有额外的 attributes 。然而，对于简单的库来说这是一个用来暴露面向对象接口的灵活的方式。当然，你总是可以定义一个空的类：

class DoorHandle is repr('CPointer') { }

然后把这个类用在你需要使用指针的地方，为了更好的类型安全以及代码的可读性。再一次提示，使用类型对象来表示空。

函数指针

C 库可以暴露指向 C 函数的指针，作为函数的返回值或者结构体的成员（比如 structs、unions）。例子中调用了一个由函数“f”返回的函数指针“$fptr”，使用 signature 定义了函数期望的参数以及返回值：

sub f() returns Pointer is native('mylib') { * }  my $fptr    = f(); my $nfptr   = nativecast(:(Str, size_t --> int32), $fptr);  say $nfptr("test", 4);

数组

sub RenderBarChart(Str, int32, CArray[Str], CArray[num]) is native('chart') { * }  my @titles := CArray[Str].new;  @titles[0] = 'Me'; @titles[1] = 'You'; @titles[2] = 'Hagrid';  my @values := CArray[num].new;  @values[0] = 59.5e0; @values[1] = 61.2e0; @values[2] = 180.7e0;  RenderBarChart('Weight (kg)', 3, @titles, @values);

注意我们对 @titles 使用了绑定，而不是赋值，如果你使用赋值，会将一个放进一个 Perl 6 的数组，然后它就不会工作了。如果这令你发疯，忘记你所知道的关于 @ 魔符的事情，使用 NativeCall 的时候直接使用 $ 吧。:-)

my $title = CArray[Str].new;  $titles[0] = 'Me'; $titles[1] = 'You'; $titles[2] = 'Hagrid';

获取数组形式的返回值也是相同的方式。有些库的 APIs 可能接受一个数组作为缓冲区，缓冲区将会由 C 函数填充，并返回实际填充的元素数量：

sub get_n_items(CArray[int32], int32) returns int32 is native('ints') { * }

在这些情况下，在传递参数给原生子例程之前，务必确保 CArray 至少含有将会被C函数填充的元素数量，否则 C 函数将破坏 Perl 的内存导致不可预料的行为发生：

my $ints = CArray[int32].new; my $number_of_ints = 10;  $ints[$number_of_ints - 1] = 0; # 将数组的大小扩展到10 my $n = get_n_items($ints, $number_of_ints);

搞清楚数组的内存管理是非常重要的，当你创建一个数组，那么你可以向其中添加元素，数组为根据你的需求自动扩展，然而，这可能导致数组在内存中被移动（然而，向一个已经存在的元素赋值时不会引发这个），这意味着当你向一个 C 库传递数组的时候，你最好清楚你在做什么。作为对比，当C库返回一个数组的时候，NativeCall 就不能管理这一块内存，它也不知道数组的结尾，大概，库的 API 可能会告诉这一点（比如，你知道当你看到一个 null 元素的时候，你就不能继续往前读了）。注意，NativeCall 不为你提供任何的保护，一旦事情做错了，你将会得到一个段错误并导致内存崩溃。这不是 NativeCall 的缺点，这就是整个原生世界工作的方式，很惊奇，好吧，来个拥抱吧，祝你好运！:-)

结构体

感谢表示多态性，你可以声明一个普通的 Perl 6类，实际上，C 编译器会把它们放在类似的结构体定义中，以相同的方式保存 attributes。所有你需要做到就是使用“repr”trait：

class Point is repr('CStruct') {     has num64 $.x;     has num64 $.y; }

CUnions

同样地，我们可以声明一个 Perl 6 类，它的属性拥有和 C 编译器中 联合体（union） 的相同的内存布局，这可以使用 CUnion 声明：

class MyUnion is repr('CUnion') {     has int32 $.flags32;     has int64 $.flags64; }  say nativesizeof(MyUnion.new); # 输出 8 同 max(sizeof(MyUnion.flags32), sizeof(MyUnion.flags64))

嵌套的 CStructs 和 CUnions

你可以引用 CStructs 和 CUnions，或者将它们嵌入到其他的 CStructs 和 CUnions 里面，前者我们像往常一样使用 has 来声明，而后者则使用 HAS 替代：

class MyStruct is repr('CStruct') {     has Point $.point; # 引用     has int32 $.flags; }  say nativesizeof(MyStruct.new); # 输出 16 同 sizeof(struct Point *) + sizeof(int32_t)  class MyStruct2 is repr('CStruct') {     HAS Point $.point; # 嵌入     has int32 $.flags; }  say nativesizeof(MyStruct2.new); # 输出 24 同 sizeof(struct Point) + sizeof(int32_t)

类型指针

my Pointer[int32] $p; # 一个int32类型的指针 my Pointer[MyStruct] $p2 = some_c_function();  my MyStruct $mc = $p2.deref;  say $mc.field1; 

Buffers and Blobs

TBD

函数参数

NativeCall 也支持把函数作为原生函数的参数，一个常用的情况就是事件驱动模型中，使用函数指针作为回调。当通过 NativeCall 绑定了这些函数，只需要提供对等的 signature 作为函数参数的约束。

# void SetCallBack(int (*callback)(char const *)) my sub SetCallBack(&callback(Str --> int32)) is native('mylib') { * }

注意：原生代码负责传递给 Perl 6 回调的值的内存管理，换句话说，NativeCall 将不会释放传递给回调的字符串占用的内存。

库路径以及名字

constant LIBMYSQL = 'mysqlclient'; constant LIBFOO = '/usr/lib/libfoo.so.1';  sub mysql_affectied_rows( .. ) returns int32 is native(LIBMYSQL); sub bar is native(LIBFOO);

constant LIBMYSQL = %*ENV<P6LIB_MYSQLCLIENT> || 'mysqlclient';

这将在编译期保持给定的值，在一个模块预编译时， LIBMYSQL 将会始终保持那个值。

ABI/API版本

假设你写的原生库为 native('foo') ， 在类Unix系统下，NativeCall 将会搜索'libfoo.so'（对于OS X是libfoo.dynlib，win32是foo.dll）。在大多数的现代系统上，将会需要你或者模块的使用者安装开发环境包，因为它们总是建议支持动态库的API/ABI的版本控制，所以'libfoo.so'大多数是一个符号链接，并且只被开发包提供。

sub foo is native('foo', v1);         # 将会查找并加载 libfoo.so.1 sub foo is native('foo', v1.2.3);    # 将会查找并加载 libfoo.so.1.2.3  my List $lib = ('foo', 'v1'); sub foo is native($lib);

Routine

native trait 也可以接受一个 Callable 作为参数，允许你使用自己的方式指定将会被加载的库文件：

sub foo is native(sub  { 'libfoo.so.42' } );

这个函数只会在第一个调用者访问的时候调用。

调用标准库

use NativeCall; my class PwStruct is repr('CStruct') {     has Str $.pw_name;     has Str $.pw_passwd;     has uint32 $.pw_uid;     has uint32 $.pw_gid;     has Str $.pw_gecos;     has Str $.pw_dir;     has Str $.pw_shell; }  sub getuid()                returns uint32         is native(Str) { * } sub getpwuid(uint32 $uid)    returns PwStruct     is native(Str) { * }  say getpwuid(getuid());

不过，使用 $*HOME 更方便一些 :-)

导出的变量

一个库导出的变量 -- 也被叫做“全局（global）”或者 “外部（extern）”变量 -- 可以使用 cglobal 访问。比如：

my $var := cglobal('libc.so.6', 'error', int32);

这将会为 $var 绑定一个新的 Proxy 对象，并且将对它的访问重定向到被“libc.so.6”导出的叫做 errno 的整数变量。

对C++的支持

NativeCall 也支持使用来自 c++ 的类以及方法，就像 这个例子 展示的那样（还有相关的 c++ 文件），注意现阶段还不像 C 一样支持测试和开发。

例子

MYSQL

这是一个如何使用MYSQL客户端库的例子， 这个工程 包装了这些函数做成一个DBI兼容的接口，(???)你可能需要安装下面的库，在基于Debian的发行版上可以这么安装：

sudo apt-get install libmysqlclient

在运行例子之前，你需要一些准备工作：

$ mysql -u root -p CREATE DATABASE zavolaj; CREATE USER 'testuser'@'localhost' IDENTIFIED BY 'testpass'; GRANT CREATE         ON zavolaj.* TO 'testuser'@'localhost'; GRANT DROP           ON zavolaj.* TO 'testuser'@'localhost'; GRANT INSERT         ON zavolaj.* TO 'testuser'@'localhost'; GRANT DELETE         ON zavolaj.* TO 'testuser'@'localhost'; GRANT SELECT         ON zavolaj.* TO 'testuser'@'localhost'; GRANT LOCK TABLES    ON zavolaj.* TO 'testuser'@'localhost'; GRANT SELECT         ON   mysql.* TO 'testuser'@'localhost'; # or maybe otherwise GRANT ALL PRIVILEGES ON zavolaj.* TO 'testuser'@'localhost';

通过一个简单的mysql连接， 你将会看到下面的结果：

$ mysql -utestuser -ptestpass USE zavolaj; SHOW TABLES; SELECT * FROM nom;

Microsoft Windows

win32-api-call.p6脚本文件展示了一些通过 Perl 6 调用 windows API 的例子，参见 这里 。