为了兼容已有的生态,仓颉支持调用 C 语言的函数,也支持 C 语言调用仓颉的函数。
一、仓颉调用 C 的函数
在仓颉中要调用 C 的函数,需要在仓颉语言中用 @C 和 foreign 关键字声明这个函数,但 @C 在修饰 foreign 声明的时候,可以省略。
举个例子,假设我们要调用 C 的 rand 和 printf 函数,它的函数签名是这样的:
那么在仓颉中调用这两个函数的方式如下:
需要注意的是:
foreign 修饰函数声明,代表该函数为外部函数。被 foreign 修饰的函数只能有函数声明,不能有函数实现。
foreign 声明的函数,参数和返回类型必须符合 C 和仓颉数据类型之间的映射关系。
由于 C 侧函数很可能产生不安全操作,所以调用 foreign 修饰的函数需要被 unsafe 块包裹,否则会发生编译错误。
@C 修饰的 foreign 关键字只能用来修饰函数声明,不可用来修饰其他声明,否则会发生编译错误。
@C 只支持修饰 foreign 函数、top-level 作用域中的非泛型函数和 struct 类型。
foreign 函数不支持命名参数和参数默认值。foreign 函数允许变长参数,使用 …表达,只能用于参数列表的最后。变长参数均需要满足 CType 约束,但不必是同一类型。
仓颉(CJNative 后端)虽然提供了栈扩容能力,但是由于 C 侧函数实际使用栈大小仓颉无法感知,所以 ffi 调用进入 C 函数后,仍然存在栈溢出的风险,需要开发者根据实际情况,修改 cjStackSize 的配置。
一些不合法的 foreign 声明的示例代码如下:
二、CFunc
仓颉中的 CFunc 指可以被 C 语言代码调用的函数,共有以下三种形式:
@C 修饰的 foreign 函数
@C 修饰的仓颉函数
类型为 CFunc 的 lambda 表达式,与普通的 lambda 表达式不同,CFunc lambda 不能捕获变量。
以上三种形式声明/定义的函数的类型均为 CFunc<(CPointer<Int8>) -> Unit>。CFunc 对应 C 语言的函数指针类型。这个类型为泛型类型,其泛型参数表示该 CFunc 入参和返回值类型,使用方式如下:
foreign func atexit(cb: CFunc<() -> Unit>): Int32
与 foreign 函数一样,其他形式的 CFunc 的参数和返回类型必须满足 CType 约束,且不支持命名参数和参数默认值。
CFunc 在仓颉代码中被调用时,需要处在 unsafe 上下文中。
仓颉语言支持将一个 CPointer<T> 类型的变量类型转换为一个具体的 CFunc,其中 CPointer 的泛型参数 T 可以是满足 CType 约束的任意类型,使用方式如下:
注意
将一个指针强制类型转换为 CFunc 并进行函数调用是危险行为,需要用户保证指针指向的是一个切实可用的函数地址,否则将发生运行时错误。
三、inout 参数
在仓颉中调用 CFunc 时,其实参可以使用 inout 关键字修饰,组成引用传值表达式,此时,该参数按引用传递。引用传值表达式的类型为 CPointer<T>,其中 T 为 inout 修饰的表达式的类型。
引用传值表达式具有以下约束:
仅可用于对 CFunc 的调用处;
其修饰对象的类型必须满足 CType 约束,但不可以是 CString;
其修饰对象不可以是用 let 定义的,不可以是字面量、入参、其他表达式的值等临时变量;
通过仓颉侧引用传值表达式传递到 C 侧的指针,仅保证在函数调用期间有效,即此种场景下 C 侧不应该保存指针以留作后用。
inout 修饰的变量,可以是定义在 top-level 作用域中的变量、局部变量、struct 中的成员变量,但不能直接或间接来源于 class 的实例成员变量。
下面是一个例子:
注意
使用宏扩展特性时,在宏的定义中,暂时不能使用 inout 参数特性。
四、unsafe
在引入与 C 语言的互操作过程中,同时也引入了 C 的许多不安全因素,因此在仓颉中使用 unsafe 关键字,用于对跨 C 调用的不安全行为进行标识。
关于 unsafe 关键字,有以下几点说明:
unsafe 可以修饰函数、表达式,也可以修饰一段作用域。
被 @C 修饰的函数,被调用处需要在 unsafe 上下文中。
在调用 CFunc 时,使用处需要在 unsafe 上下文中。
foreign 函数在仓颉中进行调用,被调用处需要在 unsafe 上下文中。
当被调用函数被 unsafe 修饰时,被调用处需要在 unsafe 上下文中。
使用方式如下:
需要注意的是,普通 lambda 无法传递 unsafe 属性,当 unsafe 的 lambda 逃逸后,可以不在 unsafe 上下文中直接调用而未产生任何编译错误。当需要在 lambda 中调用 unsafe 函数时,建议在 unsafe 块中进行调用,参考如下用例:
五、调用约定
函数调用约定描述调用者和被调用者双方如何进行函数调用(如参数如何传递、栈由谁清理等),函数调用和被调用双方必须使用相同的调用约定才能正常运行。仓颉编程语言通过 @CallingConv 来表示各种调用约定,支持的调用约定如下:
CDECL:CDECL 表示 clang 的 C 编译器在不同平台上默认使用的调用约定。
STDCALL:STDCALL 表示 Win32 API 使用的调用约定。
通过 C 语言互操作机制调用的 C 函数,未指定调用约定时将采用默认的 CDECL 调用约定。如下调用 C 标准库函数 rand 示例:
@CallingConv 只能用于修饰 foreign 块、单个 foreign 函数和 top-level 作用域中的 CFunc 函数。当 @CallingConv 修饰 foreign 块时,会为 foreign 块中的每个函数分别加上相同的 @CallingConv 修饰。
六、类型映射
(一)基础类型
仓颉与 C 语言支持基本数据类型的映射,总体原则是:
仓颉的类型不包含指向托管内存的引用类型;
仓颉的类型和 C 的类型具有同样的内存布局。
比如说,一些基本的类型映射关系如下:
说明
int 类型、long 类型等由于其在不同平台上的不确定性,需要程序员自行指定对应仓颉编程语言类型。在 C 互操作场景中,与 C 语言类似,Unit 类型仅可作为 CFunc 中的返回类型和 CPointer 的泛型参数。
仓颉也支持与 C 语言的结构体和指针类型的映射。
(二)结构体
对于结构体类型,仓颉用 @C 修饰的 struct 来对应。比如说 C 语言里面有这样的一个结构体:
那么它对应的仓颉类型可以这么定义:
如果 C 语言里有这样的一个函数:
Point3D addPoint(Point3D p1, Point3D p2);
那么对应的,在仓颉里面可以这样声明这个函数:
foreign func addPoint(p1: Point3D, p2: Point3D): Point3D
用 @C 修饰的 struct 必须满足以下限制:
成员变量的类型必须满足 CType 约束
不能实现或者扩展 interfaces
不能作为 enum 的关联值类型
不允许被闭包捕获
不能具有泛型参数
用 @C 修饰的 struct 自动满足 CType 约束。
(三)指针
对于指针类型,仓颉提供 CPointer<T> 类型来对应 C 侧的指针类型,其泛型参数 T 需要满足 CType 约束。比如对于 malloc 函数,在 C 里面的签名为:
void* malloc(size_t size);
那么在仓颉中,它可以声明为:
foreign func malloc(size: UIntNative): CPointer<Unit>
CPointer 可以进行读写、偏移计算、判空以及转为指针的整型形式等,详细 API 可以参考《仓颉编程语言库 API》。其中读写和偏移计算为不安全行为,当不合法的指针调用这些函数时,可能发生未定义行为,这些 unsafe 函数需要在 unsafe 块中调用。
CPointer 的使用示例如下:
仓颉语言支持 CPointer 之间的强制类型转换,转换前后的 CPointer 的泛型参数 T 均需要满足 CType 的约束,使用方式如下:
仓颉语言支持将一个 CFunc 类型的变量类型转换为一个具体的 CPointer,其中 CPointer 的泛型参数 T 可以是满足 CType 约束的任意类型,使用方式如下:
注意
将一个 CFunc 强制类型转换为指针通常是安全的,但是不应该对转换后的指针执行任何的 read,write 操作,可能会导致运行时错误。
(四)数组
仓颉使用 VArray 类型与 C 的数组类型映射,VArray 可以用户作为函数参数和 @C struct 成员。当 VArray<T, $N> 中的元素类型 T 满足 CType 约束时, VArray<T, $N> 类型也满足 CType 约束。
作为函数参数类型:
当 VArray 作为 CFunc 的参数时, CFunc 的函数签名仅可以是 CPointer<T> 类型或 VArray<T, $N> 类型。当函数签名中的参数类型为 VArray<T, $N> 时,传递的参数仍以 CPointer<T> 形式传递。
VArray 作为参数的使用示例如下:
对应的 C 侧函数定义可以是:
调用 CFunc 时,需要通过 inout 修饰 VArray 类型变量:
VArray 不允许作为 CFunc 的返回值类型。
作为 @C struct 成员:
当 VArray 作为 @C struct 成员时,它的内存布局与 C 侧的结构体排布一致,需要保证仓颉侧声明长度与类型也与 C 完全一致:
在仓颉中,可以声明为如下结构体与 C 代码对应:
注意
C 语言中允许结构体的最后一个字段为未指明长度的数组类型,该数组被称为柔性数组(flexible array),仓颉不支持包含柔性数组的结构体的映射。
(五)字符串
特别地,对于 C 语言中的字符串类型,仓颉中设计了一个 CString 类型来对应。为简化为 C 语言字符串的操作,CString 提供了以下成员函数:
init(p: CPointer<UInt8>) 通过 CPointer 构造一个 CString
func getChars() 获取字符串的地址,类型为 CPointer<UInt8>
func size(): Int64 计算该字符串的长度
func isEmpty(): Bool 判断该字符串的长度是否为 0,如果字符串的指针为空返回 true
func isNotEmpty(): Bool 判断该字符串的长度是否不为 0,如果字符串的指针为空返回 false
func isNull(): Bool 判断该字符串的指针是否为 null
func startsWith(str: CString): Bool 判断该字符串是否以 str 开头
func endsWith(str: CString): Bool 判断该字符串是否以 str 结尾
func equals(rhs: CString): Bool 判断该字符串是否与 rhs 相等
func equalsLower(rhs: CString): Bool 判断该字符串是否与 rhs 相等,忽略大小写
func subCString(start: UInt64): CString 从 start 开始截取子串,返回的子串存储在新分配的空间中
func subCString(start: UInt64, len: UInt64): CString 从 start 开始截取长度为 len 的子串,返回的子串存储在新分配的空间中
func compare(str: CString): Int32 该字符串与 str 比较,返回结果与 C 语言的 strcmp(this, str) 一样
func toString(): String 用该字符串构造一个新的 String 对象
func asResource(): CStringResource 获取 CString 的 Resource 类型
另外,将 String 类型转换为 CString 类型,可以通过调用 LibC 中的 mallocCString 接口,使用完成后需要对 CString 进行释放。
CString 的使用示例如下:
(六)sizeOf/alignOf
仓颉还提供了 sizeOf 和 alignOf 两个函数,用于获取上述 C 互操作类型的内存占用和内存对齐数值(单位:字节),函数声明如下:
使用示例:
在 64 位机器上运行,将输出:
16
8
七、CType
除类型映射一节提供的与 C 侧类型进行映射的类型外,仓颉还提供了一个 CType 接口,接口本身不包含任何方法,它可以作为所有 C 互操作支持的类型的父类型,便于在泛型约束中使用。
需要注意的是:
CType 接口是仓颉中的一个接口类型,它本身不满足 CType 约束;
CType 接口不允许被继承、扩展;
CType 接口不会突破子类型的使用限制。
CType 的使用示例如下:
执行结果如下:
1
true
Hello
match failed
(一)C 调用仓颉的函数
仓颉提供 CFunc 类型来对应 C 侧的函数指针类型。C 侧的函数指针可以传递到仓颉,仓颉也可以构造出对应 C 的函数指针的变量传递到 C 侧。
假设一个 C 的库 API 如下:
typedef void (*callback)(int);
void set_callback(callback cb);
对应的,在仓颉里面这个函数可以声明为:
foreign func set_callback(cb: CFunc<(Int32) -> Unit>): Unit
CFunc 类型的变量可以从 C 侧传递过来,也可以在仓颉侧构造出来。在仓颉侧构造 CFunc 类型有两种办法,一个是用 @C 修饰的函数,另外一个是标记为 CFunc 类型的闭包。
@C 修饰的函数,表明它的函数签名是满足 C 的调用规则的,定义还是写在仓颉这边。foreign 修饰的函数定义是在 C 侧的。
注意
foreign 修饰的函数与 @C 修饰的函数,这两种 CFunc 的命名不建议使用 CJ_(不区分大小写)作为前缀,否则可能与标准库及运行时等编译器内部符号出现冲突,导致未定义行为。
示例如下:
假设 C 函数编译出来的库是 “libmyfunc.so”,那么需要使用 cjc -L. -lmyfunc test.cj -o test.out 编译命令,使仓颉编译器去链接这个库。最终就能生成想要的可执行程序。
另外,在编译 C 代码时,请打开 -fstack-protector-all/-fstack-protector-strong 栈保护选项,仓颉侧代码默认拥有溢出检查与栈保护功能。在引入 C 代码后,需要同步保证 unsafe 块中的溢出的安全性。
(二)编译选项
使用 C 互操作通常需要手动链接 C 的库,仓颉编译器提供了相应的编译选项。
–library-path <value>, -L <value>, -L<value>:指定要链接的库文件所在的目录。
–library-path <value> 指定的路径会被加入链接器的库文件搜索路径。另外环境变量 LIBRARY_PATH 中指定的路径也会被加入链接器的库文件搜索路径中,通过 --library-path 指定的路径会比 LIBRARY_PATH 中的路径拥有更高的优先级。
–library <value>, -l <value>, -l<value>:指定要链接的库文件。
给定的库文件会被直接传给链接器,库文件名的格式应为 lib[arg].[extension]。
关于仓颉编译器支持的所有编译选项,详见cjc 编译选项。
(三)示例
假设我们有一个 C 库 libpaint.so,其头文件如下:
在仓颉代码中使用该 C 库的示例代码如下:
编译仓颉代码的命令如下(以 CJNative 后端为例):
cjc -L . -l paint ./main.cj
其中编译命令中 -L . 表示链接库时从当前目录查找(假设 libpaint.so 存在于当前目录),-l paint 表示链接的库的名字,编译成功后默认生成二进制文件 main,执行二进制文件的命令如下:
LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH ./main
资料来源:HarmonyOS Developer 官方网站