30 Techniques for Writing C Functions

The registry is a global table that can be accessed only by C code.^[32] Typically, we use it to store data to be shared among several modules.

The registry is always located at the pseudo-index LUA_REGISTRYINDEX. A pseudo-index is like an index into the stack, except that its associated value is not on the stack. Most functions in the Lua API that accept indices as arguments also accept pseudo-indices —the exceptions being those functions that manipulate the stack itself, such as lua_remove and lua_insert. For instance, to get a value stored with key "Key" in the registry, we can use the following call:

      lua_getfield(L, LUA_REGISTRYINDEX, "Key");

The registry is a regular Lua table. As such, we can index it with any non-nil Lua value. However, because all C modules share the same registry, we must choose with care what values we use as keys, to avoid collisions. String keys are particularly useful when we want to allow other independent libraries to access our data, because all they need to know is the key name. For those keys, there is no bulletproof method of choosing names, but there are some good practices, such as avoiding common names and prefixing our names with the library name or something like it. (Prefixes like lua or lualib are not good choices.)

We should never use our own numbers as keys in the registry, because Lua reserves numeric keys for its reference system. This system comprises a pair of functions in the auxiliary library that allow us to store values in a table without worrying about how to create unique keys. The function luaL_ref creates new references:

      int ref = luaL_ref(L, LUA_REGISTRYINDEX);

The previous call pops a value from the stack, stores it into the registry with a fresh integer key, and returns this key. We call this key a reference.

As the name implies, we use references mainly when we need to store a reference to a Lua value inside a C structure. As we have seen, we should never store pointers to Lua strings outside the C function that retrieved them. Moreover, Lua does not even offer pointers to other objects, such as tables or functions. So, we cannot refer to Lua objects through pointers. Instead, when we need such pointers, we create a reference and store it in C.

To push the value associated with a reference ref onto the stack, we simply write this:

      lua_rawgeti(L, LUA_REGISTRYINDEX, ref);

Finally, to release both the value and the reference, we call luaL_unref:

      luaL_unref(L, LUA_REGISTRYINDEX, ref);

After this call, a new call to luaL_ref may return this reference again.

The reference system treats nil as a special case. Whenever we call luaL_ref for a nil value, it does not create a new reference, but instead returns the constant reference LUA_REFNIL. The following call has no effect:

      luaL_unref(L, LUA_REGISTRYINDEX, LUA_REFNIL);

The next one pushes a nil, as expected:

      lua_rawgeti(L, LUA_REGISTRYINDEX, LUA_REFNIL);

The reference system also defines the constant LUA_NOREF, which is an integer different from any valid reference. It is useful to signal that a value treated as a reference is invalid.

When we create a Lua state, the registry comes with two predefined references:

Another safe way to create unique keys in the registry is to use as key the address of a static variable in our code: The C link editor ensures that this key is unique across all loaded libraries. To use this option, we need the function lua_pushlightuserdata, which pushes on the stack a value representing a C pointer. The following code shows how to store and retrieve a string from the registry using this method:

      /* variable with a unique address */
      static char Key = 'k';
      
      /* store a string */
      lua_pushlightuserdata(L, (void *)&Key);  /* push address */
      lua_pushstring(L, myStr);  /* push value */
      lua_settable(L, LUA_REGISTRYINDEX);  /* registry[&Key] = myStr */
      
      /* retrieve a string */
      lua_pushlightuserdata(L, (void *)&Key);  /* push address */
      lua_gettable(L, LUA_REGISTRYINDEX);  /* retrieve value */
      myStr = lua_tostring(L, -1);  /* convert to string */

We will discuss light userdata in more detail in the section called “Light Userdata”.

To simplify the use of variable addresses as unique keys, Lua 5.2 introduced two new functions: lua_rawgetp and lua_rawsetp. They are similar to lua_rawgeti and lua_rawseti, but they use C pointers (translated to light userdata) as keys. With them, we can write the previous code like this:

      static char Key = 'k';
      
      /* store a string */
      lua_pushstring(L, myStr);
      lua_rawsetp(L, LUA_REGISTRYINDEX, (void *)&Key);
      
      /* retrieve a string */
      lua_rawgetp(L, LUA_REGISTRYINDEX, (void *)&Key);
      myStr = lua_tostring(L, -1);

Both functions use raw accesses. As the registry does not have a metatable, a raw access has the same behavior as a regular access, and it is slightly more efficient.

While the registry offers global variables, the upvalue mechanism implements an equivalent of C static variables that are visible only inside a particular function. Every time we create a new C function in Lua, we can associate with it any number of upvalues, each one holding a single Lua value. Later, when we call the function, it has free access to any of its upvalues, using pseudo-indices.

We call this association of a C function with its upvalues a closure. A C closure is a C approximation to a Lua closure. In particular, we can create different closures using the same function code, but with different upvalues.

To see a simple example, let us create a function newCounter in C. (We defined a similar function in Lua in Chapter 9, Closures.) This function is a factory: it returns a new counter function each time it is called, as in this example:

      c1 = newCounter()
      print(c1(), c1(), c1())   --> 1    2    3
      c2 = newCounter()
      print(c2(), c2(), c1())   --> 1    2    4

Although all counters share the same C code, each one keeps its own independent counter. The factory function is like this:

      static int counter (lua_State *L);  /* forward declaration */
      
      int newCounter (lua_State *L) {
        lua_pushinteger(L, 0);
        lua_pushcclosure(L, &counter, 1);
        return 1;
      }

The key function here is lua_pushcclosure, which creates a new closure. Its second argument is the base function (counter, in the example) and the third is the number of upvalues (1, in the example). Before creating a new closure, we must push on the stack the initial values for its upvalues. In our example, we push zero as the initial value for the single upvalue. As expected, lua_pushcclosure leaves the new closure on the stack, so the closure is ready to be returned as the result of newCounter.

Now, let us see the definition of counter:

      static int counter (lua_State *L) {
        int val = lua_tointeger(L, lua_upvalueindex(1));
        lua_pushinteger(L, ++val);  /* new value */
        lua_copy(L, -1, lua_upvalueindex(1));  /* update upvalue */
        return 1;  /* return new value */
      }

Here, the key element is the macro lua_upvalueindex, which produces the pseudo-index of an upvalue. In particular, the expression lua_upvalueindex(1) gives the pseudo-index of the first upvalue of the running function. Again, this pseudo-index is like any stack index, except that it does not live on the stack. So, the call to lua_tointeger retrieves the current value of the first (and only) upvalue as an integer. Then, the function counter pushes the new value ++val, copies it as the new upvalue’s value, and returns it.

As a more advanced example, we will implement tuples using upvalues. A tuple is a kind of constant structure with anonymous fields; we can retrieve a specific field with a numerical index, or we can retrieve all fields at once. In our implementation, we represent tuples as functions that store their values in their upvalues. When called with a numerical argument, the function returns that specific field. When called without arguments, it returns all its fields. The following code illustrates the use of tuples:

      x = tuple.new(10, "hi", {}, 3)
      print(x(1))     --> 10
      print(x(2))     --> hi
      print(x())      --> 10  hi  table: 0x8087878  3

In C, we will represent all tuples by the same function t_tuple, presented in Figure 30.5, “An implementation of tuples”.

      #include "lauxlib.h"
      
      int t_tuple (lua_State *L) {
        lua_Integer op = luaL_optinteger(L, 1, 0);
        if (op == 0) {  /* no arguments? */
          int i;
          /* push each valid upvalue onto the stack */
          for (i = 1; !lua_isnone(L, lua_upvalueindex(i)); i++)
             lua_pushvalue(L, lua_upvalueindex(i));
          return i - 1;  /* number of values */
        }
        else {  /* get field 'op' */
          luaL_argcheck(L, 0 < op && op <= 256, 1,
                           "index out of range");
          if (lua_isnone(L, lua_upvalueindex(op)))
            return 0;  /* no such field */
          lua_pushvalue(L, lua_upvalueindex(op));
          return 1;
        }
      }
      
      int t_new (lua_State *L) {
        int top = lua_gettop(L);
        luaL_argcheck(L, top < 256, top, "too many fields");
        lua_pushcclosure(L, t_tuple, top);
        return 1;
      }
      
      static const struct luaL_Reg tuplelib [] = {
        {"new", t_new},
        {NULL, NULL}
      };
      
      int luaopen_tuple (lua_State *L) {
        luaL_newlib(L, tuplelib);
        return 1;
      }

Because we can call a tuple with or without a numeric argument, t_tuple uses luaL_optinteger to get its optional argument. This function is similar to luaL_checkinteger, but it does not complain if the argument is absent; instead, it returns a given default value (0, in the example).

The maximum number of upvalues to a C function is 255, and the maximum index we can use with lua_upvalueindex is 256. So, we use luaL_argcheck to ensure these limits.

When we index a non-existent upvalue, the result is a pseudo-value whose type is LUA_TNONE. (When we access a stack index above the current top, we also get a pseudo-value with this type LUA_TNONE.) Our function t_tuple uses lua_isnone to test whether it has a given upvalue. However, we should never use lua_upvalueindex with a negative index or with an index greater than 256 (which is one plus the maximum number of upvalues for a C function), so we must check for this condition when the user provides the index. The function luaL_argcheck checks a given condition, raising an error with a nice message if the condition fails:

      > t = tuple.new(2, 4, 5)
      > t(300)
        --> stdin:1: bad argument #1 to 't' (index out of range)

The third argument to luaL_argcheck provides the argument number for the error message (1, in the example), and the fourth argument provides a complement to the message ("index out of range").

The function to create tuples, t_new (also in Figure 30.5, “An implementation of tuples”), is trivial: because its arguments are already on the stack, it first checks that the number of fields respects the limit for upvalues in a closure and then call lua_pushcclosure to create a closure of t_tuple with all its arguments as upvalues. Finally, the array tuplelib and the function luaopen_tuple (also in Figure 30.5, “An implementation of tuples”) are the standard code to create a library tuple with that single function new.

Often, we need to share some values or variables among all functions in a library. Although we can use the registry for that task, we can also use upvalues.

Unlike Lua closures, C closures cannot share upvalues. Each closure has its own independent upvalues. However, we can set the upvalues of different functions to refer to a common table, so that this table becomes a common environment where the functions can share data.

Lua offers a function that eases the task of sharing an upvalue among all functions of a library. We have been opening C libraries with luaL_newlib. Lua implements this function as the following macro:

      #define luaL_newlib(L,lib)  \
           (luaL_newlibtable(L,lib), luaL_setfuncs(L,lib,0))

The macro luaL_newlibtable just creates a new table for the library. (This table has a preallocated size equal to the number of functions in the given library.) The function luaL_setfuncs then adds the functions in the list lib to that new table, which is on the top of the stack.

The third parameter to luaL_setfuncs is what we are interested in here. It gives the number of shared upvalues the new functions in the library will have. The initial values for these upvalues should be on the stack, as happens with lua_pushcclosure. Therefore, to create a library where all functions share a common table as their single upvalue, we can use the following code:

        /* create library table ('lib' is its list of functions) */
        luaL_newlibtable(L, lib);
        /* create shared upvalue */
        lua_newtable(L);
        /* add functions in list 'lib' to the new library, sharing
           previous table as upvalue */
        luaL_setfuncs(L, lib, 1);

The last call also removes the shared table from the stack, leaving there only the new library.