[Tarantool-patches] [PATCH 1.10 06/16] WIP: module api/lua: expose luaT_tuple_new()

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

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

XXX: Add a module API test. There is unit test already, so maybe just
verify some basic case in the module API test. Or, better, transform the
unit test into a module API test.

Part of #5273

(cherry picked from commit b525317d9056982ecfeff92e2e436554e0a605fd)
---
 extra/exports       |  1 +
 src/box/lua/tuple.c |  6 +++---
 src/box/lua/tuple.h | 22 ++++++++++++++++++----
 3 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/extra/exports b/extra/exports
index a7d8ef81b..7f8a27ea2 100644
--- a/extra/exports
+++ b/extra/exports
@@ -130,6 +130,7 @@ luaL_touint64
 luaL_toint64
 luaT_pushtuple
 luaT_istuple
+luaT_tuple_new
 luaT_error
 luaT_call
 luaT_cpcall
diff --git a/src/box/lua/tuple.c b/src/box/lua/tuple.c
index 8a8fd4d34..6732ac71a 100644
--- a/src/box/lua/tuple.c
+++ b/src/box/lua/tuple.c
@@ -97,7 +97,7 @@ luaT_istuple(struct lua_State *L, int narg)
 	return *(struct tuple **) data;
 }
 
-struct tuple *
+box_tuple_t *
 luaT_tuple_new(struct lua_State *L, int idx, box_tuple_format_t *format)
 {
 	if (idx != 0 && !lua_istable(L, idx) && !luaT_istuple(L, idx)) {
@@ -126,8 +126,8 @@ luaT_tuple_new(struct lua_State *L, int idx, box_tuple_format_t *format)
 		luamp_encode_tuple(L, &tuple_serializer, &stream, idx);
 	}
 	mpstream_flush(&stream);
-	struct tuple *tuple = box_tuple_new(format, buf->buf,
-					    buf->buf + ibuf_used(buf));
+	box_tuple_t *tuple = box_tuple_new(format, buf->buf,
+					   buf->buf + ibuf_used(buf));
 	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 dd3aa0f08..196a38c2d 100644
--- a/src/box/lua/tuple.h
+++ b/src/box/lua/tuple.h
@@ -67,8 +67,6 @@ luaT_pushtuple(struct lua_State *L, box_tuple_t *tuple);
 box_tuple_t *
 luaT_istuple(struct lua_State *L, int idx);
 
-/** \endcond public */
-
 /**
  * Create a new tuple with specific format from a Lua table, a
  * tuple, or objects on the lua stack.
@@ -76,11 +74,27 @@ luaT_istuple(struct lua_State *L, int idx);
  * Set idx to zero to create the new tuple from objects on the lua
  * stack.
  *
- * In case of an error set a diag and return NULL.
+ * 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 than with
+ *    <box_tuple_unref>().
+ *
+ * @sa box_tuple_ref()
+ *
+ * If encoding fails, raise an error.
+ *
+ * In case of any other 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)
 {
-- 
2.25.0