[Tarantool-patches] [PATCH v3 11/16] module api: add box_key_def_dump_parts()

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

The function dumps an opaque <box_key_def_t> structure into a non-opaque
array of <box_key_part_def_t> structures in order to allow an external
module to obtain information about the key definition.

Part of #5273
---
 src/box/key_def.c                |  78 ++++++++++++++++++
 src/box/key_def.h                |  13 +++
 src/exports.h                    |   1 +
 test/app-tap/module_api.c        | 135 +++++++++++++++++++++++++++++++
 test/app-tap/module_api.test.lua |   2 +-
 5 files changed, 228 insertions(+), 1 deletion(-)

diff --git a/src/box/key_def.c b/src/box/key_def.c
index 43d0c92c8..3c2cf1d7f 100644
--- a/src/box/key_def.c
+++ b/src/box/key_def.c
@@ -513,6 +513,84 @@ box_key_def_delete(box_key_def_t *key_def)
 	key_def_delete(key_def);
 }
 
+box_key_part_def_t *
+box_key_def_dump_parts(const box_key_def_t *key_def, uint32_t *part_count_ptr)
+{
+	struct region *region = &fiber()->gc;
+	size_t region_svp = region_used(region);
+	size_t size;
+	box_key_part_def_t *parts = region_alloc_array(
+		region, typeof(parts[0]), key_def->part_count, &size);
+	if (parts == NULL) {
+		diag_set(OutOfMemory, size, "region_alloc_array", "parts");
+		return NULL;
+	}
+
+	for (uint32_t i = 0; i < key_def->part_count; i++) {
+		const struct key_part *part = &key_def->parts[i];
+		box_key_part_def_t *part_def = &parts[i];
+		box_key_part_def_create(part_def);
+
+		/* Set part->{fieldno,flags,field_type}. */
+		part_def->fieldno = part->fieldno;
+		part_def->flags = 0;
+		if (key_part_is_nullable(part))
+			part_def->flags |= BOX_KEY_PART_DEF_IS_NULLABLE;
+		assert(part->type >= 0 && part->type < field_type_MAX);
+		part_def->field_type = field_type_strs[part->type];
+
+		/* Set part->collation. */
+		if (part->coll_id != COLL_NONE) {
+			struct coll_id *coll_id = coll_by_id(part->coll_id);
+			/*
+			 * A collation may be removed after
+			 * key_def creation.
+			 */
+			if (coll_id == NULL) {
+				diag_set(CollationError,
+					 "key_def holds dead collation id %d",
+					 part->coll_id);
+				region_truncate(region, region_svp);
+				return NULL;
+			}
+			/*
+			 * A collation may be removed while the
+			 * resulting key parts array is in use.
+			 */
+			char *collation = region_alloc(region,
+						       coll_id->name_len + 1);
+			if (collation == NULL) {
+				diag_set(OutOfMemory, coll_id->name_len + 1,
+					 "region_alloc", "part_def->collation");
+				region_truncate(region, region_svp);
+				return NULL;
+			}
+			memcpy(collation, coll_id->name, coll_id->name_len);
+			collation[coll_id->name_len] = '\0';
+			part_def->collation = collation;
+		}
+
+		/* Set part->path. */
+		if (part->path != NULL) {
+			char *path = region_alloc(region, part->path_len + 1);
+			if (path == NULL) {
+				diag_set(OutOfMemory, part->path_len + 1,
+					 "region", "part_def->path");
+				region_truncate(region, region_svp);
+				return NULL;
+			}
+			memcpy(path, part->path, part->path_len);
+			path[part->path_len] = '\0';
+			part_def->path = path;
+		}
+	}
+
+	if (part_count_ptr != NULL)
+		*part_count_ptr = key_def->part_count;
+
+	return parts;
+}
+
 int
 box_tuple_compare(box_tuple_t *tuple_a, box_tuple_t *tuple_b,
 		  box_key_def_t *key_def)
diff --git a/src/box/key_def.h b/src/box/key_def.h
index 5f76890b7..3e5922302 100644
--- a/src/box/key_def.h
+++ b/src/box/key_def.h
@@ -458,6 +458,19 @@ box_key_def_new_v2(box_key_part_def_t *parts, uint32_t part_count);
 API_EXPORT void
 box_key_def_delete(box_key_def_t *key_def);
 
+/**
+ * Dump key part definitions of given key_def.
+ *
+ * The function allocates key parts and storage for pointer fields
+ * (e.g. collation names) on the box region.
+ * @sa <box_region_truncate>().
+ *
+ * <box_key_part_def_t> fields that are unknown at given tarantool
+ * version are set to zero. The same for unknown <flags> bits.
+ */
+API_EXPORT box_key_part_def_t *
+box_key_def_dump_parts(const box_key_def_t *key_def, uint32_t *part_count_ptr);
+
 /**
  * Compare tuples using the key definition.
  * @param tuple_a first tuple
diff --git a/src/exports.h b/src/exports.h
index 604c1dfaa..8ffc4d887 100644
--- a/src/exports.h
+++ b/src/exports.h
@@ -30,6 +30,7 @@ EXPORT(box_insert)
 EXPORT(box_iterator_free)
 EXPORT(box_iterator_next)
 EXPORT(box_key_def_delete)
+EXPORT(box_key_def_dump_parts)
 EXPORT(box_key_def_new)
 EXPORT(box_key_def_new_v2)
 EXPORT(box_key_part_def_create)
diff --git a/test/app-tap/module_api.c b/test/app-tap/module_api.c
index 50a7fb54e..e3f127b5e 100644
--- a/test/app-tap/module_api.c
+++ b/test/app-tap/module_api.c
@@ -378,6 +378,22 @@ test_key_def_api(lua_State *L)
  * modules (gh-5273, gh-5384).
  */
 
+/**
+ * Verify that two zero terminated strings are either both NULL
+ * or have equal values.
+ */
+static void
+string_check_equal(const char *a, const char *b)
+{
+	if (a == NULL) {
+		assert(b == NULL);
+	} else {
+		assert(b != NULL);
+		assert(strlen(a) == strlen(b));
+		assert(strcmp(a, b) == 0);
+	}
+}
+
 /**
  * Verify type and message of an error in the diagnostics area.
  *
@@ -505,6 +521,25 @@ key_part_def_check_zeros(const box_key_part_def_t *part)
 	assert((part->flags & unknown_flags) == 0);
 }
 
+/**
+ * Check that two key part definitions are equal.
+ *
+ * It compares only known fields and flags, but ignores padding
+ * bytes and unknown flags.
+ */
+static void
+key_part_def_check_equal(const box_key_part_def_t *a,
+			 const box_key_part_def_t *b)
+{
+	uint32_t known_flags = key_part_def_known_flags();
+
+	assert(a->fieldno == b->fieldno);
+	assert((a->flags & known_flags) == (b->flags & known_flags));
+	string_check_equal(a->field_type, b->field_type);
+	string_check_equal(a->collation, b->collation);
+	string_check_equal(a->path, b->path);
+}
+
 /**
  * Basic <box_key_part_def_create>() and <box_key_def_new_v2>()
  * test.
@@ -602,6 +637,105 @@ test_key_def_new_v2(struct lua_State *L)
 	return 1;
 }
 
+/**
+ * Basic <box_key_def_dump_parts>() test.
+ */
+static int
+test_key_def_dump_parts(struct lua_State *L)
+{
+	size_t region_svp = box_region_used();
+	box_key_def_t *key_def = NULL;
+	box_key_part_def_t *dump = NULL;
+	uint32_t dump_part_count = 0;
+
+	/*
+	 * Create a key_def with a single key part with all fields
+	 * and flags set to non-default values.
+	 */
+	box_key_part_def_t part;
+	key_part_def_set_nondefault(&part);
+	key_def = box_key_def_new_v2(&part, 1);
+	assert(key_def != NULL);
+
+	/*
+	 * Verify that the same values are dumped, but unknown
+	 * fields and flags are set to zeros.
+	 */
+	dump = box_key_def_dump_parts(key_def, &dump_part_count);
+	assert(dump != NULL);
+	assert(dump_part_count == 1);
+	key_part_def_check_equal(&part, &dump[0]);
+	key_part_def_check_zeros(&dump[0]);
+
+	/* We can pass NULL as <part_count_ptr>. */
+	dump = box_key_def_dump_parts(key_def, NULL);
+	assert(dump != NULL);
+
+	/* Clean up. */
+	box_key_def_delete(key_def);
+
+	/* Create a key_def from two key part definitions. */
+	box_key_part_def_t parts[2];
+	box_key_part_def_create(&parts[0]);
+	box_key_part_def_create(&parts[1]);
+	parts[0].fieldno = 19;
+	parts[0].field_type = "unsigned";
+	parts[0].path = "foo";
+	parts[1].fieldno = 7;
+	parts[1].field_type = "string";
+	parts[1].collation = "unicode";
+	parts[1].flags |= BOX_KEY_PART_DEF_IS_NULLABLE;
+	key_def = box_key_def_new_v2(parts, 2);
+	assert(key_def != NULL);
+
+	/* Verify how it'll be dumped. */
+	dump = box_key_def_dump_parts(key_def, &dump_part_count);
+	assert(dump != NULL);
+	assert(dump_part_count == 2);
+	key_part_def_check_equal(&parts[0], &dump[0]);
+	key_part_def_check_equal(&parts[1], &dump[1]);
+
+	/* Clean up. */
+	box_key_def_delete(key_def);
+
+	/* Can we again create a key_def from the dumped parts? */
+	key_def = box_key_def_new_v2(dump, dump_part_count);
+	assert(key_def != NULL);
+
+	/* Verify this dump based key_def. */
+	dump = box_key_def_dump_parts(key_def, &dump_part_count);
+	assert(dump != NULL);
+	assert(dump_part_count == 2);
+	key_part_def_check_equal(&parts[0], &dump[0]);
+	key_part_def_check_equal(&parts[1], &dump[1]);
+
+	/* Clean up. */
+	box_key_def_delete(key_def);
+
+	/*
+	 * 'none' collation is the same as lack of a collation
+	 * from key_def point of view. In the dump it is present
+	 * as NULL.
+	 */
+	parts[1].collation = "none";
+	key_def = box_key_def_new_v2(parts, 2);
+	assert(key_def != NULL);
+	dump = box_key_def_dump_parts(key_def, &dump_part_count);
+	assert(dump != NULL);
+	assert(dump_part_count == 2);
+	/* Set to NULL just for ease verification. */
+	parts[1].collation = NULL;
+	key_part_def_check_equal(&parts[0], &dump[0]);
+	key_part_def_check_equal(&parts[1], &dump[1]);
+
+	/* Clean up. */
+	box_key_def_delete(key_def);
+	box_region_truncate(region_svp);
+
+	lua_pushboolean(L, 1);
+	return 1;
+}
+
 /* }}} key_def api v2 */
 
 static int
@@ -980,6 +1114,7 @@ luaopen_module_api(lua_State *L)
 		{"test_tuple_encode", test_tuple_encode},
 		{"test_tuple_new", test_tuple_new},
 		{"test_key_def_new_v2", test_key_def_new_v2},
+		{"test_key_def_dump_parts", test_key_def_dump_parts},
 		{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 5145ab164..f4edfad10 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(29)
+    test:plan(30)
     local status, module = pcall(require, 'module_api')
     test:is(status, true, "module")
     test:ok(status, "module is loaded")
-- 
2.25.0