[Tarantool-patches] [PATCH v3 07/16] module api/lua: expose luaT_tuple_new()

[Alexander Turenko]

It is convenient wrapper around box_tuple_new() to create a tuple from a
Lua table (or from another tuple).

Part of #5273
---
 src/box/lua/tuple.c              |  6 ++---
 src/box/lua/tuple.h              | 20 +++++++++++++---
 src/exports.h                    |  1 +
 test/app-tap/module_api.c        | 40 ++++++++++++++++++++++++++++++++
 test/app-tap/module_api.test.lua |  2 +-
 5 files changed, 62 insertions(+), 7 deletions(-)

diff --git a/src/box/lua/tuple.c b/src/box/lua/tuple.c
index 191e84539..255fd0bc9 100644
--- a/src/box/lua/tuple.c
+++ b/src/box/lua/tuple.c
@@ -257,15 +257,15 @@ luaT_tuple_encode(struct lua_State *L, int idx, size_t *tuple_len_ptr)
 
 /* }}} Encode a Lua table as an MsgPack array */
 
-struct tuple *
+box_tuple_t *
 luaT_tuple_new(struct lua_State *L, int idx, box_tuple_format_t *format)
 {
 	size_t tuple_len;
 	char *tuple_data = luaT_tuple_encode_on_lua_ibuf(L, idx, &tuple_len);
 	if (tuple_data == NULL)
 		return NULL;
-	struct tuple *tuple = box_tuple_new(format, tuple_data,
-					    tuple_data + tuple_len);
+	box_tuple_t *tuple = box_tuple_new(format, tuple_data,
+					   tuple_data + tuple_len);
 	if (tuple == NULL)
 		return NULL;
 	ibuf_reinit(tarantool_lua_ibuf);
diff --git a/src/box/lua/tuple.h b/src/box/lua/tuple.h
index aadcf7f59..f6384ddb8 100644
--- a/src/box/lua/tuple.h
+++ b/src/box/lua/tuple.h
@@ -92,21 +92,35 @@ luaT_istuple(struct lua_State *L, int idx);
  * should call <box_region_truncate>() to release the data.
  *
  * In case of an error set a diag and return NULL.
+ *
+ * @sa luaT_tuple_new()
  */
 API_EXPORT char *
 luaT_tuple_encode(struct lua_State *L, int idx, size_t *tuple_len_ptr);
 
-/** \endcond public */
-
 /**
  * Create a new tuple with specific format from a Lua table or a
  * tuple.
  *
+ * The new tuple is referenced in the same way as one created by
+ * <box_tuple_new>(). There are two possible usage scenarious:
+ *
+ * 1. A short living tuple may not be referenced explicitly and
+ *    will be collected automatically at the next module API call
+ *    that yields or returns a tuple.
+ * 2. A long living tuple must be referenced using
+ *    <box_tuple_ref>() and unreferenced then with
+ *    <box_tuple_unref>().
+ *
+ * @sa box_tuple_ref()
+ *
  * In case of an error set a diag and return NULL.
  */
-struct tuple *
+API_EXPORT box_tuple_t *
 luaT_tuple_new(struct lua_State *L, int idx, box_tuple_format_t *format);
 
+/** \endcond public */
+
 static inline int
 luaT_pushtupleornil(struct lua_State *L, struct tuple *tuple)
 {
diff --git a/src/exports.h b/src/exports.h
index 7bdba5693..299bb9fc1 100644
--- a/src/exports.h
+++ b/src/exports.h
@@ -407,6 +407,7 @@ EXPORT(luaT_pushtuple)
 EXPORT(luaT_state)
 EXPORT(luaT_tolstring)
 EXPORT(luaT_tuple_encode)
+EXPORT(luaT_tuple_new)
 EXPORT(mp_char2escape)
 EXPORT(mp_decode_double)
 EXPORT(mp_decode_extl)
diff --git a/test/app-tap/module_api.c b/test/app-tap/module_api.c
index 0090a35a5..d7304f86d 100644
--- a/test/app-tap/module_api.c
+++ b/test/app-tap/module_api.c
@@ -669,6 +669,45 @@ test_tuple_encode(struct lua_State *L)
 
 /* }}} test_tuple_encode */
 
+/* {{{ test_tuple_new */
+
+/**
+ * Create a tuple from a Lua table or another tuple.
+ *
+ * Just basic test. More cases in the luaT_tuple_new.c unit test.
+ */
+static int
+test_tuple_new(struct lua_State *L)
+{
+	box_tuple_format_t *default_format = box_tuple_format_default();
+
+	/* Prepare the Lua stack. */
+	luaL_loadstring(L, "return {1, 2, 3}");
+	lua_call(L, 0, 1);
+
+	/* Create a tuple. */
+	int top = lua_gettop(L);
+	box_tuple_t *tuple = luaT_tuple_new(L, -1, default_format);
+
+	/* Verify size, data and Lua stack top. */
+	size_t region_svp = box_region_used();
+	size_t tuple_size = box_tuple_bsize(tuple);
+	char *tuple_data = box_region_alloc(tuple_size);
+	ssize_t rc = box_tuple_to_buf(tuple, tuple_data, tuple_size);
+	assert(rc == (ssize_t) tuple_size);
+	check_tuple_data(tuple_data, tuple_size, lua_gettop(L) - top);
+
+	/* Clean up. */
+	box_region_truncate(region_svp);
+	lua_pop(L, 1);
+	assert(lua_gettop(L) == 0);
+
+	lua_pushboolean(L, 1);
+	return 1;
+}
+
+/* }}} test_tuple_new */
+
 LUA_API int
 luaopen_module_api(lua_State *L)
 {
@@ -700,6 +739,7 @@ luaopen_module_api(lua_State *L)
 		{"iscdata", test_iscdata},
 		{"test_box_region", test_box_region},
 		{"test_tuple_encode", test_tuple_encode},
+		{"test_tuple_new", test_tuple_new},
 		{NULL, NULL}
 	};
 	luaL_register(L, "module_api", lib);
diff --git a/test/app-tap/module_api.test.lua b/test/app-tap/module_api.test.lua
index e5cac9eb6..f1b377e17 100755
--- a/test/app-tap/module_api.test.lua
+++ b/test/app-tap/module_api.test.lua
@@ -177,7 +177,7 @@ local function test_iscdata(test, module)
 end
 
 local test = require('tap').test("module_api", function(test)
-    test:plan(27)
+    test:plan(28)
     local status, module = pcall(require, 'module_api')
     test:is(status, true, "module")
     test:ok(status, "module is loaded")
-- 
2.25.0