Home Explore Blog CI



neovim

25th chunk of `runtime/doc/luaref.txt`
629ea49cce07232c59e60795586fdd6d21d5242cadfe3a5b0000000100000fa0
 `realloc`,
        but not exactly the same. Its arguments are `ud`, an opaque pointer
        passed to `lua_newstate` (see |lua_newstate()|); `ptr`, a pointer
        to the block being allocated/reallocated/freed; `osize`, the original
        size of the block; `nsize`, the new size of the block. `ptr` is `NULL`
        if and only if `osize` is zero. When `nsize` is zero, the allocator
        must return `NULL`; if `osize` is not zero, it should free the block
        pointed to by `ptr`. When `nsize` is not zero, the allocator returns
        `NULL` if and only if it cannot fill the request. When `nsize` is not
        zero and `osize` is zero, the allocator should behave like `malloc`.
        When `nsize` and `osize` are not zero, the allocator behaves like
        `realloc`. Lua assumes that the allocator never fails when
        `osize >= nsize`.

        Here is a simple implementation for the allocator function. It is used
        in the auxiliary library by `luaL_newstate` (see
        |luaL_newstate()|).
>c
            static void *l_alloc (void *ud, void *ptr, size_t osize,
                                                       size_t nsize) {
              (void)ud;  (void)osize;  /* not used */
              if (nsize == 0) {
                free(ptr);
                return NULL;
              }
              else
                return realloc(ptr, nsize);
            }
<
        This code assumes that `free(NULL)` has no effect and that
        `realloc(NULL, size)` is equivalent to `malloc(size)`. ANSI C ensures both
        behaviors.

lua_atpanic                                                      *lua_atpanic()*
>c
    lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
<
        Sets a new panic function and returns the old one.

        If an error happens outside any protected environment, Lua calls a
        `panic` `function` and then calls `exit(EXIT_FAILURE)`, thus exiting
        the host application. Your panic function may avoid this exit by never
        returning (e.g., doing a long jump).

        The panic function can access the error message at the top of the
        stack.

lua_call                                                            *lua_call()*
>c
    void lua_call (lua_State *L, int nargs, int nresults);
<
        Calls a function.

        To call a function you must use the following protocol: first, the
        function to be called is pushed onto the stack; then, the arguments to
        the function are pushed in direct order; that is, the first argument
        is pushed first. Finally you call `lua_call`; `nargs` is the number of
        arguments that you pushed onto the stack. All arguments and the
        function value are popped from the stack when the function is called.
        The function results are pushed onto the stack when the function
        returns. The number of results is adjusted to `nresults`, unless
        `nresults` is `LUA_MULTRET`. In this case, `all` results from the
        function are pushed. Lua takes care that the returned values fit into
        the stack space. The function results are pushed onto the stack in
        direct order (the first result is pushed first), so that after the
        call the last result is on the top of the stack.

        Any error inside the called function is propagated upwards (with a
        `longjmp`).

        The following example shows how the host program may do the equivalent
        to this Lua code:
>lua
            a = f("how", t.x, 14)
<
        Here it is in C:
>c
            lua_getfield(L, LUA_GLOBALSINDEX, "f"); // function to be called
            lua_pushstring(L, "how");                        // 1st argument
            lua_getfield(L, LUA_GLOBALSINDEX, "t");   // table to be indexed
            lua_getfield(L, -1, "x");        // push result of t.x (2nd arg)
            lua_remove(L, -2);                  // remove 't' from the stack
            lua_pushinteger(L, 14);     

Title: Lua C API: Memory Allocator, Panic Function, and Function Calls
Summary
This passage describes the `lua_Alloc` function used for memory allocation in Lua, providing a sample implementation using `realloc`. It then explains the `lua_atpanic` function, which sets a new panic function to be called when an error occurs outside a protected environment. Finally, it details the `lua_call` function for calling Lua functions from C, outlining the stack protocol for pushing the function and its arguments, and retrieving the results.