Re: [Tarantool-patches] [PATCH 2.X v3 3/3] module api: luaL_checkibuf

[Alexander Turenko <alexander.turenko@tarantool.org>]

I CCed Igor, because he is maybe interested about the topic regarding
naming of Lua/C helpers.

Answered inline.

WBR, Alexander Turenko.

> diff --git a/src/lua/utils.h b/src/lua/utils.h
> index e80e2b1a2..7658c67f8 100644
> --- a/src/lua/utils.h
> +++ b/src/lua/utils.h
> @@ -539,6 +539,14 @@ luaT_tolstring(lua_State *L, int idx, size_t *ssize);
>  LUA_API int
>  luaL_iscallable(lua_State *L, int idx);
>  
> +/**
> + * Check if a value on @a L stack by index @a idx is an ibuf
> + * object. Both 'struct ibuf' and 'struct ibuf *' are accepted.
> + * Returns NULL, if can't convert - not an ibuf object.
> + */
> +struct ibuf *
> +luaL_checkibuf(struct lua_State *L, int idx);
> +

First, some background: luaL_checkfoo() raise a Lua error when type
checking fails. lua_isfoo() returns zero in such case, lua_tofoo()
return NULL. IMHO, lua_isfoo() / lua_tofoo() is often more convenient
for Lua/C code, because you may need to free some resources explicitly.
It also allows to return / raise a domain specific error (say, give
short usage information).

 | [-0, +0, -]
 | int lua_isuserdata (lua_State *L, int index);
 |
 | Returns 1 if the value at the given acceptable index is a userdata
 | (either full or light), and 0 otherwise. 

 | [-0, +0, -]
 | void *lua_touserdata (lua_State *L, int index);
 |
 | If the value at the given acceptable index is a full userdata,
 | returns its block address. If the value is a light userdata, returns
 | its pointer. Otherwise, returns NULL. 

You may find more examples in https://pgl.yoyo.org/luai/i/_

So I would either implement `int luaT_isibuf(L, idx, box_ibuf_t **)` or
rename the function to `box_ibuf_t *luaT_toibuf(L, idx)`.

Regarding prefixes: we use 'luaL_' for general purpose functions, but
'luaT_' for tarantool specific objects. ibuf is tarantool's thing.

BTW, Vlad tells me it possibly should be named as 'box ibuf', not just
'ibuf'. However the name would be a bit ugly (luaT_is_box_ibuf()), so I
guess 'luaT_' prefix is enough to say that it is something tarantool
specific.

BTW, it seems the patch re ibuf functions should come before this one to
use the public type name (box_ibuf_t) in the declaration.

> +local function test_buffers(test, module)
> +    test:plan(8)
> +    local ffi = require('ffi')
> +    local buffer = require('buffer')
> +
> +    local bufalloc = buffer.static_alloc("char", 128)
> +    local ibuf = buffer.ibuf()

Let's also check <struct ibuf *>.

 | tarantool> ffi.typeof(buffer.ibuf())
 | ---
 | - ctype<struct ibuf>
 | ...
 | 
 | tarantool> ffi.typeof(buffer.IBUF_SHARED)
 | ---
 | - ctype<struct ibuf *>
 | ...