erlang NIF部分接口实现（一）加载过程及编写框架 - Erlang中文论坛

最近在项目中频繁用到erlang的NIF接口，以扩展erlang虚拟机的功能，同时又能提供较高的性能。

NIF（native implemented functions）从R14B开始支持，其功能在于，能够使得erlang module的功能通过c/c++实现。

erlang虚拟机有很多与外部进行功能交互的方式，如通过spawn_executable类型的port调用其它程序，port_driver，nif等，它们各有适应的场合：

spawn_executable类型的port会产生一个外部进程执行命令，不会干扰到erlang虚拟机本身，但是性能较低；

port_driver遵循erlang虚拟机的port机制，功能强大，但需要对虚拟机有较多的了解，编程门槛较高，内嵌入虚拟机，会影响到虚拟机执行，执行结果异步地通过消息队列返回，一些同步的环境下不适合；

nif功能强大但编程接口相对简单，不需要对虚拟机了解太多即可编写，调用一个nif实现的erlang接口就如同调用一个c函数一般，同时也有异步向进程投递消息的能力，极大的提升了erlang虚拟机的扩展能力，缺点也是需要内嵌入虚拟机，会影响到虚拟机执行。

如何利用NIF编写接口，初学者可以看看《erlang otp in action》上的例子，进阶者可以看看一些开源项目，如riak依赖的bitcask、eleveldb、ebloom等等，都是非常好的范例。

本次将分析NIF的部分重要接口的实现，其中涉及到erlang虚拟机的部分仅介绍基本原理而不会深入分析。

照抄官方文档上给出的例子：

#include "erl_nif.h"
static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
{
return enif_make_string(env, "Hello world!", ERL_NIF_LATIN1);
}
static ErlNifFunc nif_funcs[] =
{
{"hello", 0, hello}
};
ERL_NIF_INIT(niftest,nif_funcs,NULL,NULL,NULL,NULL)

复制代码

ERL_NIF_INIT的第一个参数是该NIF的模块名，第二个参数是该模块包含的所有可供外部调用的函数定义数组，本例中，niftest即为NIF的模块名，而nif_funcs即为函数定义数组，nif_funcs包含了一个函数定义hello，其参数个数为0，具体实现为c函数static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])。

NIF的模块名可以将其与同名的erlang module对应起来。

对于linux平台，按照官方文档给出的编译方法，

gcc -fPIC -shared -o niftest.so niftest.c -I $ERL_ROOT/usr/include/

niftest.c将被编译为共享库niftest.so，以供虚拟机在需要的时候加载。

相应的erlang模块实现：

-module(niftest).
-export([init/0, hello/0]).
init() ->
erlang:load_nif("./niftest", 0).
hello() ->
"NIF library not loaded".

复制代码

niftest.erl定义了一个erlang模块niftest，包含一个init函数和一个hello函数，init函数用于初始化模块，通过load_nif函数加载niftest.so，这个定义与NIF对模块和函数的定义是一致的。

官方文档介绍时，明确的给出了调用结果：

"NIF library not loaded"

这是为什么呢？

首先来看加载时做了什么。

erlang:load_nif/2是一个bif，也即erlang的内建函数，要求必须由NIF对应的erlang module的某个函数直接调用。

BIF_RETTYPE load_nif_2(BIF_ALIST_2)
/*该函数的参数BIF_ALIST_2是一个数组，包含两个元素，对应了erlang:load_nif/2两个参数，第一个为共享库文件名，第二个为加载时用户传入的一些私有参数。*/
{
len = list_length(BIF_ARG_1);
if (len < 0) {
BIF_ERROR(BIF_P, BADARG);
}
lib_name = (char *) erts_alloc(ERTS_ALC_T_TMP, len + 1);
if (intlist_to_buf(BIF_ARG_1, lib_name, len) != len) {
erts_free(ERTS_ALC_T_TMP, lib_name);
BIF_ERROR(BIF_P, BADARG);
}
lib_name[len] = '\0';
/* 首先，为待加载nif的共享库文件名单独分配一个缓冲区lib_name，并将文件名拷入这个缓冲区中 */
caller = find_function_from_pc(BIF_P->cp);
mod_atom = caller[0];
mod=erts_get_module(mod_atom);
/* 接着，从进程程序计数器中取得当前指令所在的模块的描述符mod，由于进程当前调用的函数是erlang:load_nif/2，该函数必须由NIF对应的erlang module调用，否则将会在之后的检查过程中报错 */
erts_sys_ddll_open2(lib_name, &handle, &errdesc);
/* 使用dlopen打开NIF的共享库文件 */
erts_sys_ddll_load_nif_init(handle, &init_func, &errdesc);
/* 找打共享库文件中一个名为"nif_init"的函数，记录到init_func中 */
entry = erts_sys_ddll_call_nif_init(init_func);
/* 调用init_func进行初始化工作，该函数会返回一个ErlNifEntry结构，相当于NIF的描述符，正是由宏ERL_NIF_INIT构造的，它的作用将在稍后介绍 */
for (i=0; i < entry->num_of_funcs && ret==am_ok; i++) {
BeamInstr** code_pp;
ErlNifFunc* f = &entry->funcs[i];
if (!erts_atom_get(f->name, sys_strlen(f->name), &f_atom)
|| (code_pp = get_func_pp(mod->code, f_atom, f->arity))==NULL) {
ret = load_nif_error(BIF_P,bad_lib,"Function not found %T:%s/%u",
mod_atom, f->name, f->arity);
}
/* 检查NIF描述符的每一个函数，这些函数必须要在NIF对应的erlang module中有同名构造，否则将会报错，这也就是为什么要求load_nif仅能由NIF对应的erlang module调用的原因了，若NIF出现任何一个没有在erlang module中定义的函数，则会影响到erlang的模块定义 */
ErlNifEnv env;
struct erl_module_nif* lib = erts_alloc(ERTS_ALC_T_NIF, sizeof(struct erl_module_nif));
lib->handle = handle;
lib->entry = entry;
erts_refc_init(&lib->rt_cnt, 0);
erts_refc_init(&lib->rt_dtor_cnt, 0);
lib->mod = mod;
env.mod_nif = lib;
/* 为NIF构建一个模块描述符，分别记录了NIF的共享库文件句柄handle，NIF描述符entry，NIF对应的模块的描述符mod */
if (entry->load != NULL) {
erts_pre_nif(&env, BIF_P, lib);
veto = entry->load(&env, &lib->priv_data, BIF_ARG_2);
erts_post_nif(&env);
}
/* 此处仅仅介绍第一次加载时的动作，即调用NIF描述符的load函数进行加载，该函数也是由NIF文件定义的 */
mod->nif = lib;
for (i=0; i < entry->num_of_funcs; i++)
/* 遍历NIF描述符中的每一个函数 */
{
BeamInstr* code_ptr;
erts_atom_get(entry->funcs[i].name, sys_strlen(entry->funcs[i].name), &f_atom);
/* 取得该函数的在erlang module中的同名函数的位置，记录到f_atom中 */
code_ptr = *get_func_pp(mod->code, f_atom, entry->funcs[i].arity);
/* 由f_atom得到对于的函数描述符，mod->code是一个数组，记录了erlang module的所有信息，包括每个函数的名字、参数个数、入口点、表达式等 */
if (code_ptr[1] == 0) {
code_ptr[5+0] = (BeamInstr) BeamOp(op_call_nif);
/* 将原先的函数指令替换为op_call_nif，表名下一步将进行调用nif的过程，该指令的执行过程将在稍后介绍 */
}
else { /* Function traced, patch the original instruction word */
BpData** bps = (BpData**) code_ptr[1];
BpData* bp = (BpData*) bps[erts_bp_sched2ix()];
bp->orig_instr = (BeamInstr) BeamOp(op_call_nif);
}
code_ptr[5+1] = (BeamInstr) entry->funcs[i].fptr;
/* 紧接在op_call_nif指令后要放入实际的c函数入口点，才能在调用具体nif函数时正确找到对应的c函数 */
code_ptr[5+2] = (BeamInstr) lib;
}
/* 进行一个patch工作，将原先erlang module中定义的函数替换为NIF描述符包含的同名函数 */
}

复制代码

至此，加载的主要工作就完成了，其主要任务是通过dlopen加载NIF的共享库文件，然后调用其中定义的函数nif_init，该函数将返回一个NIF描述符，该描述符中若包含一个load函数，则调用该函数进行NIF的一些加载工作，NIF描述符中必须包含NIF向外导出的函数定义数组，每个函数定义是一个ErlNifFunc结构，定义了函数名、参数个数、c函数入口点，根据该数组的定义，需要原先erlang module中的同名函数替换为函数数组中的定义，替换过程为首先找到erlang module中同名函数的函数描述符，然后将其第一条指令替换为op_call_nif，后跟NIF中该函数对于的c函数入口点，以保证在虚拟机执行process_main时，能够正确地将对erlang module的函数的调用导向到对NIF的c函数的调用。

接下来看这个宏的定义：

#define ERL_NIF_INIT_DECL(MODNAME) ErlNifEntry* nif_init(void)
#define ERL_NIF_INIT(NAME, FUNCS, LOAD, RELOAD, UPGRADE, UNLOAD) \
ERL_NIF_INIT_PROLOGUE \
ERL_NIF_INIT_GLOB \
ERL_NIF_INIT_DECL(NAME); \
ERL_NIF_INIT_DECL(NAME) \
{ \
static ErlNifEntry entry = \
{ \
ERL_NIF_MAJOR_VERSION, \
ERL_NIF_MINOR_VERSION, \
#NAME, \
sizeof(FUNCS) / sizeof(*FUNCS), \
FUNCS, \
LOAD, RELOAD, UPGRADE, UNLOAD, \
ERL_NIF_VM_VARIANT \
}; \
ERL_NIF_INIT_BODY; \
return &entry; \
} \
ERL_NIF_INIT_EPILOGUE

复制代码

原来，NIF文件中使用ERL_NIF_INIT将定义一个名为nif_init的函数，该函数将会在load_nif_2中加载NIF共享库文件后进行调用，这个函数会填充并返回一个ErlNifEntry结构，来看看它的定义：

typedef struct enif_entry_t
{
int major;
int minor;
const char* name;
int num_of_funcs;
ErlNifFunc* funcs;
int (*load) (ErlNifEnv*, void** priv_data, ERL_NIF_TERM load_info);
int (*reload) (ErlNifEnv*, void** priv_data, ERL_NIF_TERM load_info);
int (*upgrade)(ErlNifEnv*, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info);
void (*unload) (ErlNifEnv*, void* priv_data);
const char* vm_variant;
}ErlNifEntry;

复制代码

nif_init将ErlNifEntry.name填充为宏参数NAME，ErlNifEntry.funcs填充为FUNCS，ErlNifEntry.load填充为LOAD，对于niftest.c，NAME为"niftest"，这也是niftest模块的模块名，FUNCS为nif_funcs，LOAD为NULL。

ErlNifEntry.funcs是一个数组，其元素ErlNifFunc的定义如下：

typedef struct
{
const char* name;
unsigned arity;
ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
}ErlNifFunc;

复制代码

对于niftest.c，仅包含一个函数hello的定义，name函数名为"hello"，arity参数个数为0，c函数入口点为static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])。

对于每一个用户实现的NIF函数，其原型必须是：

ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);

对于该原型的解释，官方文档上已经很详尽了，此处就不再介绍。

在成功的将erlang module的函数调用替换为对c函数的调用后，再来看一下它在虚拟机中的实际执行过程：

void process_main(void)
{
...
OpCase(call_nif):
{
/*
* call_nif is always first instruction in function:
*
* I[-3]: Module
* I[-2]: Function
* I[-1]: Arity
* I[0]: &&call_nif
* I[1]: Function pointer to NIF function
* I[2]: Pointer to erl_module_nif
*/
/* 在这里我们也可以看到之前patch函数时code_ptr数组的全貌了 */
BifFunction vbf;
DTRACE_NIF_ENTRY(c_p, (Eterm)I[-3], (Eterm)I[-2], (Uint)I[-1]);
c_p->current = I-3; /* current and vbf set to please handle_error */
SWAPOUT;
c_p->fcalls = FCALLS - 1;
PROCESS_MAIN_CHK_LOCKS(c_p);
bif_nif_arity = I[-1];
ERTS_SMP_UNREQ_PROC_MAIN_LOCK(c_p);
ERTS_VERIFY_UNUSED_TEMP_ALLOC(c_p);
ASSERT(!ERTS_PROC_IS_EXITING(c_p));
{
typedef Eterm NifF(struct enif_environment_t*, int argc, Eterm argv[]);
NifF* fp = vbf = (NifF*) I[1];
struct enif_environment_t env;
erts_pre_nif(&env, c_p, (struct erl_module_nif*)I[2]);
/* 初始化env，将env附着在当前进程c_p上 */
reg[0] = r(0);
nif_bif_result = (*fp)(&env, bif_nif_arity, reg);
/* 调用具体的c函数，reg为参数数组 */
erts_post_nif(&env);
}
ASSERT(!ERTS_PROC_IS_EXITING(c_p) || is_non_value(nif_bif_result));
PROCESS_MAIN_CHK_LOCKS(c_p);
ERTS_VERIFY_UNUSED_TEMP_ALLOC(c_p);
DTRACE_NIF_RETURN(c_p, (Eterm)I[-3], (Eterm)I[-2], (Uint)I[-1]);
goto apply_bif_or_nif_epilogue;
...
}

复制代码

NIF函数在执行时，就相当于调用c函数本身一样，稍微特别的地方在于，需要将输入输出参数的类型转换为erlang类型，每次调用时，NIF函数会建立一个上下文环境结构enif_environment_t，它记录了NIF执行时必要的进程上下文，其定义如下：

struct enif_environment_t /* ErlNifEnv */
{
struct erl_module_nif* mod_nif;
Process* proc;
Eterm* hp;
Eterm* hp_end;
ErlHeapFragment* heap_frag;
int fpe_was_unmasked;
struct enif_tmp_obj_t* tmp_obj_list;
};

复制代码

其中，proc成员即为当前进程，env的主要作用体现在内存分配和进程身份标识上，通过NIF接口分配的内存，实际都是由env附着的进程的堆分配的。

至此，NIF的加载和执行位置已经介绍完毕了，编写NIF主要会涉及到如下类型的NIF库接口：

1.类型系统，由于nif和erlang代码分处在两个世界，因此需要对输入输出参数进行转换，这类接口主要包括get系列和make系列函数，包括元组、列表、整型、字符串、binary等；

2.内存管理，类型系统的make系列函数已经包含了对特定erlang类型的数据结构的内存分配，但对于c类型的数据结构，还需要一些通用的接口，enif_alloc/enif_free等；

3.消息发送，NIF只能附着在一个进程上执行，因此没有消息接收的能力，只能进行消息发送，使用enif_send接口进行消息发送；

4.持久资源，这是NIF的一大特色，可以创建一个持久资源描述符，跨进程传递数据，资源可以是任意的数据结构；

5.条件变量、信号量、读写锁，这些功能是通过driver的同类操作实现的；

6.操作系统线程及线程私有资源，这个功能也是通过driver的同类操作实现的；

7.系统信息，这个功能也是通过driver的同类操作实现的。

稍侯将介绍nif的几类接口的实现。