LuaAPI finishing

By Lua

ref: https://blog.csdn.net/ouyangshima/article/details/43339571

​ < /div>

LUAand C/C++ the communication bridge——Stack< /span>

Lua was born to interact with C, so use CExpandLuaOr change LuaEmbed in CThese are very popular practices. To understand Cand Lua< Span style="font-size: 14px;">The interactive method, first of all, we must review the Chow the language is Processing function parameters.

CFunctions and parameters

Everyone knows CLanguage is implemented in assembly. There is no concept of function in assembly language. The corresponding function is What is called a sub-process, a sub-process is a piece of instruction, a sub-process and the sub-process it calls through the stack of Perform parameter transfer interaction. Before a sub-process calls other sub-processes, the parameters required by the sub-process to be called will be pushed into the stack according to the agreed format. In the called sub-process , The parameters can be taken out of the stack according to the agreed rules. In the same way, the transfer of the return value is also carried out through the stack. CThe format in which the parameters of the language convention are put into the stack, It’s the “call convention“. CThe function prototype of the language determines the The number and types of parameters put into the stack. p>

Luathe virtual stack

LuaThe interaction between C is cleverly simulated< span style="font-family: SimSun; font-size: 14px;">CLanguage stack,Luaand CMutual calling and Access is carried out through the stack, which ingeniously solves the problem of mutual access between variables of different types. Specifically, let’s imagine the following picture

Share pictures

Because C and Lua are languages ​​of different levels, the C language Variables and variables and functions in Lua cannot directly interact. We assume that C language and Lua have their own “spaces (C Space and Lua Space)”. The interaction between these two spaces is solved by the virtual stack in the figure above. Why use a virtual stack to interact? Its purpose is to provide great flexibility while avoiding the explosion of the combination of two language variable types during interaction.

The use of the stack solves the two differences between C and Lua Coordination issue: First, Lua will automatically perform garbage collection, while C requires the display of the allocated storage unit, which is a contradiction between the two. Second, the confusion caused by the inconsistency between the dynamic types in Lua and the static types in C.

LuaAPI first program

  1. /*
  2. download and install, LuaForWindows software (http://download.csdn.net/download/ivastest/3713327), after installation, there will be two files../lua5.1/inclue/;../lua5.1/lib/, which is The header files and library files we need to use for programming;

  3. Or, go to the official website (http://www.lua.org/download.html) to download the source code, compile the library file by yourself, Baidu search (vs2012 compile using lua ) Tutorial

  5. 1. New, Win32 console application-empty project,

  6. 2. Configuration, additional include directory, additional library directory, additional dependencies

  7. */

  9. #include< /span>

  10. using namespace std;

  12. #include

  13. /*#includeThe content is:

  14. extern “C” {
  15. #include “lua .h”

  16. #include “lualib.h”

  17. #include “lauxlib.h”

  18. }

  19. */

  21. //#pragma comment(lib, “lua5.1.lib”) // This is the Debug version.

  22. //#pragma comment(lib, “lua51.lib”) // This is the Release version.

  24. /*

  25. C language to read and write Lua global variables (basic types)

  26. C language reading Lua global variables is the simplest operation. From the above figure, we can guess that if you read the global variables in Lua through the C language, two steps are required: 1. Push the global variables from Lua Space into the virtual stack; 2. Read the global variables from the stack into the C language Space . In the interaction between Lua and C, Lua cannot see and manipulate the virtual stack, but only has the right to manipulate the stack in the C language, so the two steps mentioned above are all done in the C language.

  27. */

  28. void get_global(lua_State *L)< /span>

  29. {

  30. int global_var1;

  31. lua_getglobal(L, “global_var1”); /* read the global variable global_var1 from the variable space of lua and put it into the virtual stack*/

  32. global_var1 = lua_tonumber(L, -1); /* read the variable that was just pushed onto the stack from the virtual stack, -1 Means to read the top element of the stack*/

  33. printf(“Read global var from C: %d
    “, global_var1);    < /span>

  34. }
  36. int main()< /span>

  37. {

  38. lua_State *l = luaL_newstate(); // Create a Lua state. It is actually a data structure.

  39. luaL_openlibs(l); // Load all standard libraries, math, table, os, debug,. ..

  40. luaL_dofile(l, < span class="hljs-string">“test.lua”);

  41. //When debugging, the test.lua file must be in the same directory as the .cpp file; and the code of test.lua must be in ANSI format, otherwise it will Execution failed (0: success), (1: failure)

  42. get_global(l);

  43. lua_close(l);

  44. system( “pause”);

  45. return 0;

    46. < li>

    }

  46. /*

  47. test.lua file content :

  48. print(“Hello world, from “,_VERSION,”!”)

  49. global_var1 = 5

  50. print(“Print global varb from lua”, global_var1)
  52. Output:

  53. Hello world, from Lua 5.1 !

  54. Print global varb from lua 5

    < /div>

  55. Read global var from C: 5

  56. */

  58. /*

  59. The compilation and execution of Lua scripts are independent of each other and are executed on different threads. You can apply for a virtual machine through the luaL_newstate() function and return the pointer type lua_State. All future calls of other Lua Api functions will require this pointer as the first parameter to specify a virtual machine. So lua_State represents a lua virtual machine object, and luaL_newstate() allocates a virtual machine. The lua library manages all virtual machines. Destroy all objects of the specified virtual machine (if there is no method related to garbage collection, this method will be called) and recover all the memory generated by the dynamic allocation of the virtual machine. On some platforms, we do not need to call this function, because when the master When the program exits, resources will be naturally released, but a long-running program, such as a web server running in the background, needs to immediately reclaim virtual machine resources to avoid excessive memory usage.

  60. */

LuaAPI finishing

The header file lua.h defines the basic functions provided by Lua. These include functions to create a new Lua environment (such as lua_open), functions to call Lua functions (such as lua_pcall), functions to read/write global variables in the Lua environment, functions to register new functions that can be called by Lua code, and many more. All defined in lua.h have a lua_ prefix.

The header file lauxlib.h defines the functions provided by the auxiliary library. Similarly, all functions defined in it start with luaL_ (for example, luaL_loadbuffer). The auxiliary library uses the basic functions provided in lua.h to provide a higher level of abstraction; all Lua standard libraries use auxlib. The basic API is dedicated to economy and orthogonality, while auxlib is dedicated to the practicality of general tasks. Of course, it is very easy to create other abstractions based on the needs of your program. It should be kept in mind that auxlib does not have access to Lua. It accomplishes all its work through the official basic API. API Chinese introduction, Lua 5.1 Reference Manual

Stack

Lua operates the stack according to a strict LIFO rule (last in, first out; that is, always access the top of the stack). When you call Lua, it only changes the top part of the stack. Your C code has more freedom; more specifically, you can query any element on the stack, and even insert and delete elements at any position. The elements in the stack are positioned by index values, where the top of the stack is -1, the stack The bottom is 1. Stack member access support index. < span style="color: #ff0000;">It should be noted that the stack operation is based on the top of the stack, that is, it will only manipulate the value at the top of the stack.

C++ data is passed to the virtual stack

  1. /* push functions (C -> stack)——>Operation between C space and virtual stack

  2. C language presses variables that conform to Lua data types (nil, number, string, table, function, userdata, thread) into the virtual stack

  3. < div class="hljs-ln-code">
  • LUA_API void (lua_pushnil) (lua_State *L);

  • LUA_API void (lua_pushnumber) (lua_State *L, lua_Number n);–double,float

  • LUA_API void (lua_pushinteger) (lua_State *L, lua_Integer n);–int,long

  • LUA_API void (lua_pushlstring) (lua_State *L, const char *s, size_t l);–Any string (char *Type, allow to contain’’ characters)

  • LUA_API void (lua_pushstring) (lua_State *L, const char *s);–a string ending with’’ (const char*)

  • LUA_API const char *(lua_pushvfstring) (lua_State *L, const char *fmt,va_list argp);

  • LUA_API const char *(lua_pushfstring) (lua_State *L, const char *fmt, …);

    < /li>

  • LUA_API void (lua_pushcclosure) (lua_State *L, lua_CFunction fn, int n);

  • LUA_API void (lua_pushboolean) (lua_State *L, int b);

  • LUA_API void (lua_pushlightuserdata) (lua_State *L, void *p);

  • LUA_API int (lua_pushthread) (lua_State *L);

  • */

    • Strings in Lua are not zero-terminated; they rely on a clear length, so they can contain arbitrary binary data. The official function to push a string into a string is lua_pushlstring, which requires a clear length as a parameter. For zero-terminated strings, you can use lua_pushstring (it uses strlen to calculate the length of the string).
    Lua never maintains a pointer to an external string (or any other object, except for C functions-which are always static pointers). For all the strings it keeps, Lua either makes an internal copy or reuses the existing strings. Therefore, you can freely modify or release your buffer once these functions return.

    Transfer virtual stack data to C++

    1. /*access functions (stack -> C) ——>Operation between C space and virtual stack

    2. –API provides a set of lua_is* functions to check whether an element is a specified type, * can be any Lua type . The lua_isnumber and lua_isstring functions do not check whether the value is of the specified type, but whether it can be converted to the specified type.

    3. LUA_API int (lua_isnumber) (lua_State *L, int idx);

    4. LUA_API int (lua_isstring) (lua_State *L, int idx);

    5. LUA_API int (lua_iscfunction) (lua_State *L, int idx) ;

    6. LUA_API int (lua_isuserdata) (lua_State *L, int idx);

    7. < div class="hljs-ln-line"> LUA_API int (lua_type) (lua_State *L, int idx);

  • LUA_API const char *(lua_typename) (lua_State *L, int tp);

  • –API provides the relationship between two data on the virtual stack
  • LUA_API int (lua_equal ) (lua_State *L, int idx1, int idx2);–If the values ​​in index1 and index2 are the same, return 1. Otherwise it returns 0. It will also return 0 if any index is invalid.

  • LUA_API int (lua_rawequal) (lua_State *L, int idx1, int idx2);

  • LUA_API int (lua_lessthan) (lua_State *L, int idx1, int idx2);

  • –The lua type data on the virtual stack is converted into data conforming to the C++ language data type (int, double, char*, function, void, struct/class (userdata), pointer)

  • < span class="hljs-comment">LUA_API lua_Number (lua_tonumber) (lua_State *L, int idx);

  • LUA_API lua_Integer (lua_tointeger) (lua_State *L, int idx);

  • LUA_API int (lua_toboolean) (lua_State *L, int idx);
  • LUA_API const char *(lua_tolstring) (lua_State *L, int idx, size_t *len);

  • LUA_API size_t (lua_objlen) (lua_State *L, int idx);

  • LUA_API lua_CFunction (lua_tocfunction) (lua_State *L, int idx) ;

  • LUA_API void *(lua_touserdata) (lua_State *L, int idx);

  • LUA_API lua_State *(lua_tothread) (lua_State *L, int idx);

  • LUA_API const void *(lua_topointer) (lua_State *L, int idx);

  • */

    • Even if the type of the given element is incorrect, there is no problem in calling these functions. In this case, lua_toboolean, lua_tonumber, and lua_strlen return 0, and other functions return NULL. Since ANSI C does not provide a valid digital value that can be used to determine the occurrence of an error, the returned 0 is useless. For other functions, we generally do not need to use the corresponding lua_is* function: we only need to call lua_is* and test whether the returned result is NULL.
    The Lua_tostring function returns a pointer to the internal copy of the string. You cannot modify it (reminds you of a const)    . As long as the value corresponding to this pointer is still in the stack, Lua will ensure that this pointer is always valid. When a C function returns, Lua will clean up its stack. Therefore, there is a principle: never save pointers to Lua strings to external functions that access them.
    The end of the string returned by lua_tostring always has an end-of-character mark 0, but the middle of the string may also contain 0, lua_strlen returns the actual length of the string    . In special cases, assuming that the value at the top of the stack is a string, the following assertion (assert) is always valid:

    1. < div class="hljs-ln-code">
      const char *s = lua_tostring( L, -1); //any Lua string
  • size_t l = lua_strlen (L, -1); // its length
  • assert(s[l] == ‘’);

  • assert (strlen(s) <= l);

    • Lua data is passed to the virtual stack

      < li>

      /*get functions (Lua -> stack)——>Operation between Lua space and virtual stack

    2. LUA_API void (lua_gettable) (lua_State *L, int idx);//把t[k] 值压入堆栈，这里的t 是指有效索引index 指向的值，而k 则是栈顶放的值。这个函数会弹出堆栈上的 key （把结果放在栈上相同位置）。在 Lua 中，这个函数可能触发对应 “index” 事件的元方法

    3. lua_getglobal(L, “mytable”) <== push mytable

    4. lua_pushnumber(L, 1) <== push key 1

    5. lua_gettable(L, -2) <== pop key 1, push mytable[1]

    6.  
    7. LUA_API void (lua_getfield) (lua_State *L, int idx, const char *k);//把 t[k] 值压入堆栈，这里的 t 是指有效索引 index 指向的值。在 Lua 中，这个函数可能触发对应 “index” 事件的元方法

    8. lua_getglobal(L, “mytable”) <== push mytable

    9. lua_getfield(L, -1, “x”) <== push mytable["x"]，作用同下面两行调用

    10. –lua_pushstring(L, “x”) <== push key "x"

    11. –lua_gettable(L,-2) <== pop key "x", push mytable["x"]

    12.  
    13. LUA_API void (lua_rawget) (lua_State *L, int idx);//类似于 Lua_gettable，但是作一次直接访问（不触发元方法）。

    14. LUA_API void (lua_rawgeti) (lua_State *L, int idx, int n);//把 t[n] 的值压栈，这里的 t 是指给定索引 index 处的一个值。这是一个直接访问；就是说，它不会触发元方法。

    15. lua_getglobal(L, “mytable”) <== push mytable

    16. lua_rawgeti(L, -1, 1) <== push mytable[1]，作用同下面两行调用

    17. –lua_pushnumber(L, 1) <== push key 1

    18. –lua_rawget(L,-2) <== pop key 1, push mytable[1]

    19.  
    20. LUA_API void (lua_createtable) (lua_State *L, int narr, int nrec);//创建一个新的空 table 压入堆栈。这个新 table 将被预分配 narr 个元素的数组空间以及 nrec 个元素的非数组空间。当你明确知道表中需要多少个元素时，预分配就非常有用。如果你不知道，可以使用函数 Lua_newtable。

    21.  
    22. LUA_API void *(lua_newuserdata) (lua_State *L, size_t sz);//这个函数分配分配一块指定大小的内存块，把内存块地址作为一个完整的 userdata 压入堆栈，并返回这个地址。

    23. userdata 代表 Lua 中的 C 值。完整的 userdata 代表一块内存。它是一个对象（就像 table 那样的对象）：你必须创建它，它有着自己的元表，而且它在被回收时，可以被监测到。一个完整的 userdata 只和它自己相等（在等于的原生作用下）。

    24. 当 Lua 通过 gc 元方法回收一个完整的 userdata 时， Lua 调用这个元方法并把 userdata 标记为已终止。等到这个 userdata 再次被收集的时候，Lua 会释放掉相关的内存。

    25. LUA_API int (lua_getmetatable) (lua_State *L, int objindex);//把给定索引指向的值的元表压入堆栈。 If the index is invalid, or there is no metatable for this value, the function will return 0 and nothing will be pushed onto the stack.

    26. LUA_API void (lua_getfenv) (lua_State *L, int idx);//把索引处值的环境表压入堆栈。

    27. */

    虚拟栈数据传递到Lua空间中

    1. /*set functions (stack -> Lua)——>Lua空间与虚拟栈之间的操作

    2.  
    3. LUA_API void (lua_settable) (lua_State *L, int idx);作一个等价于 t[k] = v 的操作，这里 t 是一个给定有效索引 index 处的值， v 指栈顶的值，而 k 是栈顶之下的那个值。这个函数会把键和值都从堆栈中弹出。和在 Lua 中一样，这个函数可能触发 “newindex” 事件的元方法。 eg:

    4. lua_getglobal(L, “mytable”) <== push mytable

    5. lua_pushnumber(L, 1) <== push key 1

    6. lua_pushstring(L, “abc”) <== push value "abc"

    7. lua_settable(L, -3) <== mytable[1] = "abc", pop key & value

    8.  
    9. LUA_API void (lua_setfield) (lua_State *L, int idx, const char *k);//做一个等价于 t[k] = v 的操作，这里 t 是给出的有效索引 index 处的值，而 v 是栈顶的那个值。这个函数将把这个值弹出堆栈。跟在 Lua 中一样，这个函数可能触发一个 “newindex” 事件的元方法。 eg:

    10. lua_getglobal(L, “mytable”) <== push mytable

    11. lua_pushstring(L, “abc”) <== push value "abc"

    12. lua_setfield(L, -2, “x”) <== mytable["x"] = "abc", pop value "abc"

    13.  
    14. LUA_API void (lua_rawset) (lua_State *L, int idx);//类似于 Lua_settable，但是是作一个直接赋值（不触发元方法）。

    15. LUA_API void (lua_rawseti) (lua_State *L, int idx, int n);//等价于 t[n] = v，这里的 t 是指给定索引 index 处的一个值，而 v 是栈顶的值。函数将把这个值弹出栈。赋值操作是直接的；就是说，不会触发元方法。

    16. lua_getglobal(L, “mytable”) <== push mytable

    17. lua_pushstring(L, “abc”) <== push value "abc"

    18. lua_rawseti(L, -2, 1) <== mytable[1] = "abc", pop value "abc"

    19.  
    20. LUA_API int (lua_setmetatable) (lua_State *L, int objindex);//把一个 table 弹出堆栈，并将其设为给定索引处的值的 metatable 。

    21. LUA_API int (lua_setfenv) (lua_State *L, int idx);//从堆栈上弹出一个 table 并把它设为指定索引处值的新环境。如果指定索引处的值即不是函数又不是线程或是 userdata ， Lua_setfenv 会返回 0 ，否则返回 1 。

    22. */

    虚拟栈基本操作

    1. /* basic stack manipulation–基础栈操作

    2. LUA_API int (lua_gettop) (lua_State *L);//获取栈的高度，它也是栈顶元素的索引。注意一个负数索引-x对应于正数索引gettop-x+1

    3. LUA_API void (lua_settop) (lua_State *L, int idx);//设置栈的高度。如果开始的栈顶高于新的栈顶，顶部的值被丢弃。否则，为了得到指定的大小这个函数压入相应个数的空值（nil）到栈上。特别的，lua_settop(L,0)清空堆栈。

    4. LUA_API void (lua_pushvalue) (lua_State *L, int idx);//压入堆栈上指定索引的一个抟贝到栈顶,【增加一个元素到栈顶】

    5. LUA_API void (lua_remove) (lua_State *L, int idx);//移除指定索引位置的元素，并将其上面所有的元素下移来填补这个位置的空白，【删除了一个元素】

    6. LUA_API void (lua_insert) (lua_State *L, int idx);//移动栈顶元素到指定索引的位置，并将这个索引位置上面的元素全部上移至栈顶被移动留下的空隔，【没有增加一个元素，移动了元素的位置】

    7. LUA_API void (lua_replace) (lua_State *L, int idx);//从栈顶弹出元素值并将其设置到指定索引位置，没有任何移动操作。 【删除了一个元素，替换掉指定的元素】

    8. LUA_API int (lua_checkstack) (lua_State *L, int sz);//检查栈上是否有能插入n个元素的空间;没有返回0

    9. LUA_API void (lua_xmove) (lua_State *from, lua_State *to, int n);//将一个堆栈上的从栈顶起的n个元素 移到另一个堆栈上

    10.  
    11. lua的堆栈保持着后进先出的原则。如果栈开始于 10 20 30 40 50*（自底向上；`*´ 标记了栈顶），那么：

    12. lua_pushvalue(L, 3)    –> 10 20 30 40 50 30*

    13. lua_pushvalue(L, -1)   –> 10 20 30 40 50 30 30*

    14. lua_remove(L, -3)      –> 10 20 30 40 30 30*

    15. lua_remove(L, 6)      –> 10 20 30 40 30*

    16. lua_insert(L, 1)      –> 30 10 20 30 40*

    17. lua_insert(L, -1)      –> 30 10 20 30 40* (no effect)

    18. lua_replace(L, 2)      –> 30 40 20 30*

    19. lua_settop(L, -3)      –> 30 40*

    20. lua_settop(L, 6)      –> 30 40 nil nil nil nil*

    21. */

    宏定义

    1. /* some useful macros

    2. #define lua_pop(L,n) lua_settop(L, -(n)-1)

    3. #define lua_newtable(L) lua_createtable(L, 0, 0)

    4. #define lua_register(L,n,f) (lua_pushcfunction(L, (f)), lua_setglobal(L, (n)))

    5. #define lua_pushcfunction(L,f) lua_pushcclosure(L, (f), 0)

    6. #define lua_strlen(L,i) lua_objlen(L, (i))

    7.  
    8. #define lua_isfunction(L,n) (lua_type(L, (n)) == LUA_TFUNCTION)

    9. #define lua_istable(L,n) (lua_type(L, (n)) == LUA_TTABLE)

    10. #define lua_islightuserdata(L,n) (lua_type(L, (n)) == LUA_TLIGHTUSERDATA)

    11. #define lua_isnil(L,n) (lua_type(L, (n)) == LUA_TNIL)

    12. #define lua_isboolean(L,n) (lua_type(L, (n)) == LUA_TBOOLEAN)

    13. #define lua_isthread(L,n) (lua_type(L, (n)) == LUA_TTHREAD)

    14. #define lua_isnone(L,n) (lua_type(L, (n)) == LUA_TNONE)

    15. #define lua_isnoneornil(L, n) (lua_type(L, (n)) <= 0)

    16.  
    17. #define lua_pushliteral(L, s) lua_pushlstring(L, “” s, (sizeof(s)/sizeof(char))-1)

    18. #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, (s))

    19. #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, (s))

    20. #define lua_tostring(L,i) lua_tolstring(L, (i), NULL)

    21.  
    22.  
    23. //compatibility macros and functions

    24. #define lua_open() luaL_newstate()
    25. #define lua_getregistry(L) lua_pushvalue(L, LUA_REGISTRYINDEX)

    26. #define lua_getgccount(L) lua_gc(L, LUA_GCCOUNT, 0)

    27. #define lua_Chunkreader lua_Reader

    28. #define lua_Chunkwriter lua_Writer

    29. */

     

     

    1. /*