erlang NIF部分接口实现（一）加载过程及编写框架

dreamxyp

最近在项目中频繁用到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虚拟机的部分仅介绍基本原理而不会深入分析。

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

NIF实现：

niftest.c

1. #include "erl_nif.h"
   
2. static ERL_NIF_TERM hello(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[])
   
3. {
   
4.     return enif_make_string(env, "Hello world!", ERL_NIF_LATIN1);
   
5. }
   
6. static ErlNifFunc nif_funcs[] =
   
7. {
   
8.     {"hello", 0, hello}
   
9. };
   
10. 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模块实现：

niftest.erl

1. -module(niftest).
   
2. -export([init/0, hello/0]).
   
3. init() ->
   
4.       erlang:load_nif("./niftest", 0).
   
5. hello() ->
   
6.       "NIF library not loaded".

复制代码

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

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

1> c(niftest).

{ok,niftest}

2> niftest:hello().

"NIF library not loaded"

3> niftest:init().

ok

4> niftest:hello().

"Hello world!"

这是为什么呢？

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

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

erl_nif.c

1. BIF_RETTYPE load_nif_2(BIF_ALIST_2)
   
2. /*该函数的参数BIF_ALIST_2是一个数组，包含两个元素，对应了erlang:load_nif/2两个参数，第一个为共享库文件名，第二个为加载时用户传入的一些私有参数。*/
   
3. {
   
4. 
   
5.     len = list_length(BIF_ARG_1);
   
6.     if (len < 0) {
   
7.         BIF_ERROR(BIF_P, BADARG);
   
8.     }
   
9.     lib_name = (char *) erts_alloc(ERTS_ALC_T_TMP, len + 1);
   
10. 
    
11.     if (intlist_to_buf(BIF_ARG_1, lib_name, len) != len) {
    
12.         erts_free(ERTS_ALC_T_TMP, lib_name);
    
13.         BIF_ERROR(BIF_P, BADARG);
    
14.     }
    
15.     lib_name[len] = '\0';
    
16.     /* 首先，为待加载nif的共享库文件名单独分配一个缓冲区lib_name，并将文件名拷入这个缓冲区中 */
    
17. 
    
18. 
    
19. 
    
20.     caller = find_function_from_pc(BIF_P->cp);
    
21.     mod_atom = caller[0];
    
22.     mod=erts_get_module(mod_atom);
    
23.     /* 接着，从进程程序计数器中取得当前指令所在的模块的描述符mod，由于进程当前调用的函数是erlang:load_nif/2，该函数必须由NIF对应的erlang module调用，否则将会在之后的检查过程中报错 */
    
24. 
    
25. 
    
26. 
    
27.     erts_sys_ddll_open2(lib_name, &handle, &errdesc);
    
28.     /* 使用dlopen打开NIF的共享库文件 */
    
29.     erts_sys_ddll_load_nif_init(handle, &init_func, &errdesc);
    
30.     /* 找打共享库文件中一个名为"nif_init"的函数，记录到init_func中 */
    
31.     entry = erts_sys_ddll_call_nif_init(init_func);
    
32.     /* 调用init_func进行初始化工作，该函数会返回一个ErlNifEntry结构，相当于NIF的描述符，正是由宏ERL_NIF_INIT构造的，它的作用将在稍后介绍 */
    
33. 
    
34. 
    
35.     for (i=0; i < entry->num_of_funcs && ret==am_ok; i++) {
    
36.         BeamInstr** code_pp;
    
37.         ErlNifFunc* f = &entry->funcs[i];
    
38.         if (!erts_atom_get(f->name, sys_strlen(f->name), &f_atom)
    
39.                 || (code_pp = get_func_pp(mod->code, f_atom, f->arity))==NULL) {
    
40.         ret = load_nif_error(BIF_P,bad_lib,"Function not found %T:%s/%u",
    
41.                              mod_atom, f->name, f->arity);
    
42.     }
    
43. 
    
44.     /* 检查NIF描述符的每一个函数，这些函数必须要在NIF对应的erlang module中有同名构造，否则将会报错，这也就是为什么要求load_nif仅能由NIF对应的erlang module调用的原因了，若NIF出现任何一个没有在erlang module中定义的函数，则会影响到erlang的模块定义 */
    
45. 
    
46.     ErlNifEnv env;
    
47.     struct erl_module_nif* lib = erts_alloc(ERTS_ALC_T_NIF, sizeof(struct erl_module_nif));
    
48. 
    
49.     lib->handle = handle;
    
50.     lib->entry = entry;
    
51.     erts_refc_init(&lib->rt_cnt, 0);
    
52.     erts_refc_init(&lib->rt_dtor_cnt, 0);
    
53.     lib->mod = mod;
    
54.     env.mod_nif = lib;
    
55.     /* 为NIF构建一个模块描述符，分别记录了NIF的共享库文件句柄handle，NIF描述符entry，NIF对应的模块的描述符mod */
    
56. 
    
57. 
    
58.     if (entry->load != NULL) {
    
59. 
    
60.         erts_pre_nif(&env, BIF_P, lib);
    
61.         veto = entry->load(&env, &lib->priv_data, BIF_ARG_2);
    
62.         erts_post_nif(&env);
    
63.     }
    
64. 
    
65.     /* 此处仅仅介绍第一次加载时的动作，即调用NIF描述符的load函数进行加载，该函数也是由NIF文件定义的 */
    
66. 
    
67. 
    
68.     mod->nif = lib;
    
69.     for (i=0; i < entry->num_of_funcs; i++)
    
70.     /* 遍历NIF描述符中的每一个函数 */
    
71.     {
    
72.         BeamInstr* code_ptr;
    
73.         erts_atom_get(entry->funcs[i].name, sys_strlen(entry->funcs[i].name), &f_atom);
    
74.         /* 取得该函数的在erlang module中的同名函数的位置，记录到f_atom中 */
    
75.         code_ptr = *get_func_pp(mod->code, f_atom, entry->funcs[i].arity);
    
76.         /* 由f_atom得到对于的函数描述符，mod->code是一个数组，记录了erlang module的所有信息，包括每个函数的名字、参数个数、入口点、表达式等 */
    
77. 
    
78.         if (code_ptr[1] == 0) {
    
79.             code_ptr[5+0] = (BeamInstr) BeamOp(op_call_nif);
    
80.             /* 将原先的函数指令替换为op_call_nif，表名下一步将进行调用nif的过程，该指令的执行过程将在稍后介绍 */
    
81.         }
    
82.         else { /* Function traced, patch the original instruction word */
    
83.             BpData** bps = (BpData**) code_ptr[1];
    
84.             BpData*  bp  = (BpData*) bps[erts_bp_sched2ix()];
    
85.             bp->orig_instr = (BeamInstr) BeamOp(op_call_nif);
    
86.         }            
    
87.         code_ptr[5+1] = (BeamInstr) entry->funcs[i].fptr;
    
88.         /* 紧接在op_call_nif指令后要放入实际的c函数入口点，才能在调用具体nif函数时正确找到对应的c函数 */
    
89.         code_ptr[5+2] = (BeamInstr) lib;
    
90.     }
    
91.     /* 进行一个patch工作，将原先erlang module中定义的函数替换为NIF描述符包含的同名函数 */
    
92. 
    
93. }

复制代码

至此，加载的主要工作就完成了，其主要任务是通过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函数的调用。

接下来看这个宏的定义：

erl_nif.h

1. #define ERL_NIF_INIT_DECL(MODNAME) ErlNifEntry* nif_init(void)
   
2. 
   
3. 
   
4. #define ERL_NIF_INIT(NAME, FUNCS, LOAD, RELOAD, UPGRADE, UNLOAD) \
   
5. ERL_NIF_INIT_PROLOGUE                   \
   
6. ERL_NIF_INIT_GLOB                       \
   
7. ERL_NIF_INIT_DECL(NAME);                \
   
8. ERL_NIF_INIT_DECL(NAME)                        \
   
9. {                                        \
   
10.     static ErlNifEntry entry =                 \
    
11.     {                                        \
    
12.         ERL_NIF_MAJOR_VERSION,                \
    
13.         ERL_NIF_MINOR_VERSION,                \
    
14.         #NAME,                                \
    
15.         sizeof(FUNCS) / sizeof(*FUNCS),        \
    
16.         FUNCS,                                \
    
17.         LOAD, RELOAD, UPGRADE, UNLOAD,        \
    
18.         ERL_NIF_VM_VARIANT                \
    
19.     };                                  \
    
20.     ERL_NIF_INIT_BODY;                  \
    
21.     return &entry;                        \
    
22. }                                       \
    
23. ERL_NIF_INIT_EPILOGUE

复制代码

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

1. typedef struct enif_entry_t
   
2. {
   
3.     int major;
   
4.     int minor;
   
5.     const char* name;
   
6.     int num_of_funcs;
   
7.     ErlNifFunc* funcs;
   
8.     int  (*load)   (ErlNifEnv*, void** priv_data, ERL_NIF_TERM load_info);
   
9.     int  (*reload) (ErlNifEnv*, void** priv_data, ERL_NIF_TERM load_info);
   
10.     int  (*upgrade)(ErlNifEnv*, void** priv_data, void** old_priv_data, ERL_NIF_TERM load_info);
    
11.     void (*unload) (ErlNifEnv*, void* priv_data);
    
12.     const char* vm_variant;
    
13. }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的定义如下：

1. typedef struct
   
2. {
   
3.     const char* name;
   
4.     unsigned arity;
   
5.     ERL_NIF_TERM (*fptr)(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]);
   
6. }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函数的调用后，再来看一下它在虚拟机中的实际执行过程：

beam_emu.c

1. void process_main(void)
   
2. {
   
3.     ...
   
4. 
   
5.     OpCase(call_nif):
   
6.         {
   
7.             /*
   
8.              * call_nif is always first instruction in function:
   
9.              *
   
10.              * I[-3]: Module
    
11.              * I[-2]: Function
    
12.              * I[-1]: Arity
    
13.              * I[0]: &&call_nif
    
14.              * I[1]: Function pointer to NIF function
    
15.              * I[2]: Pointer to erl_module_nif
    
16.              */
    
17. 
    
18.             /* 在这里我们也可以看到之前patch函数时code_ptr数组的全貌了 */
    
19. 
    
20.             BifFunction vbf;
    
21. 
    
22.             DTRACE_NIF_ENTRY(c_p, (Eterm)I[-3], (Eterm)I[-2], (Uint)I[-1]);
    
23.             c_p->current = I-3; /* current and vbf set to please handle_error */
    
24.             SWAPOUT;
    
25.             c_p->fcalls = FCALLS - 1;
    
26.             PROCESS_MAIN_CHK_LOCKS(c_p);
    
27.             bif_nif_arity = I[-1];
    
28.             ERTS_SMP_UNREQ_PROC_MAIN_LOCK(c_p);
    
29.             ERTS_VERIFY_UNUSED_TEMP_ALLOC(c_p);
    
30. 
    
31.             ASSERT(!ERTS_PROC_IS_EXITING(c_p));
    
32.             {
    
33.                 typedef Eterm NifF(struct enif_environment_t*, int argc, Eterm argv[]);
    
34.                 NifF* fp = vbf = (NifF*) I[1];
    
35.                 struct enif_environment_t env;
    
36.                 erts_pre_nif(&env, c_p, (struct erl_module_nif*)I[2]);
    
37.                 /* 初始化env，将env附着在当前进程c_p上 */
    
38.                 reg[0] = r(0);
    
39.                 nif_bif_result = (*fp)(&env, bif_nif_arity, reg);
    
40.                 /* 调用具体的c函数，reg为参数数组 */
    
41.                 erts_post_nif(&env);
    
42.             }
    
43.             ASSERT(!ERTS_PROC_IS_EXITING(c_p) || is_non_value(nif_bif_result));
    
44.             PROCESS_MAIN_CHK_LOCKS(c_p);
    
45.             ERTS_VERIFY_UNUSED_TEMP_ALLOC(c_p);
    
46. 
    
47.             DTRACE_NIF_RETURN(c_p, (Eterm)I[-3], (Eterm)I[-2], (Uint)I[-1]);
    
48.             goto apply_bif_or_nif_epilogue;
    
49.     ...
    
50. }

复制代码

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

1. struct enif_environment_t /* ErlNifEnv */
   
2. {
   
3.     struct erl_module_nif* mod_nif;
   
4.     Process* proc;
   
5.     Eterm* hp;
   
6.     Eterm* hp_end;
   
7.     ErlHeapFragment* heap_frag;
   
8.     int fpe_was_unmasked;
   
9.     struct enif_tmp_obj_t* tmp_obj_list;
   
10. };

复制代码

其中，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的几类接口的实现。