Add disconnected RowSet class for bulk row fetching

fdcastel · fdcastel · commit 8ee3212def6d · 2026-03-11T23:06:34.000-03:00
RowSet fetches up to N rows from a Statement's result set directly into a contiguous buffer at construction time. After construction, the RowSet is completely independent of the source Statement. This enables zero-copy N-row prefetch for the ODBC driver: allocate a RowSet with the desired batch size and access rows by index, without per-row memcpy from the Statement's internal buffer. Addresses asfernandes#42 (REQ-3).
diff --git a/src/fb-cpp/RowSet.cpp b/src/fb-cpp/RowSet.cpp
@@ -0,0 +1,60 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2026 F.D.Castel
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include "RowSet.h"
+#include "Client.h"
+#include "Statement.h"
+
+using namespace fbcpp;
+using namespace fbcpp::impl;
+
+
+RowSet::RowSet(Statement& statement, unsigned maxRows)
+{
+	assert(statement.isValid());
+	assert(statement.getResultSetHandle());
+
+	auto& attachment = statement.getAttachment();
+	auto status = attachment.getClient().newStatus();
+	StatusWrapper statusWrapper{attachment.getClient(), status.get()};
+
+	auto outMetadata = statement.getOutputMetadata();
+	messageLength = outMetadata->getMessageLength(&statusWrapper);
+
+	buffer.resize(static_cast<std::size_t>(maxRows) * messageLength);
+
+	auto resultSet = statement.getResultSetHandle();
+
+	for (unsigned i = 0; i < maxRows; ++i)
+	{
+		auto* dest = buffer.data() + static_cast<std::size_t>(i) * messageLength;
+
+		if (resultSet->fetchNext(&statusWrapper, dest) != fb::IStatus::RESULT_OK)
+			break;
+
+		++count;
+	}
+
+	buffer.resize(static_cast<std::size_t>(count) * messageLength);
+}
diff --git a/src/fb-cpp/RowSet.h b/src/fb-cpp/RowSet.h
@@ -0,0 +1,124 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2026 F.D.Castel
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#ifndef FBCPP_ROWSET_H
+#define FBCPP_ROWSET_H
+
+#include "fb-api.h"
+#include "SmartPtrs.h"
+#include "Exception.h"
+#include <cassert>
+#include <cstddef>
+#include <vector>
+
+
+///
+/// fb-cpp namespace.
+///
+namespace fbcpp
+{
+	class Statement;
+
+	///
+	/// @brief A disconnected buffer of rows fetched from a Statement's result set.
+	///
+	/// Rows are fetched into a contiguous buffer at construction time. After
+	/// construction the RowSet is independent of its source Statement and can
+	/// be used, moved, or destroyed freely.
+	///
+	class RowSet final
+	{
+	public:
+		///
+		/// @brief Fetches up to `maxRows` rows from the current result set of
+		/// `statement`.
+		///
+		/// The statement must have an open result set (i.e. `execute()` was
+		/// called and it is a SELECT-type statement). Rows are fetched via
+		/// `IResultSet::fetchNext()` directly into the internal buffer.
+		///
+		/// @param statement The statement with an open result set.
+		/// @param maxRows Maximum number of rows to fetch.
+		///
+		explicit RowSet(Statement& statement, unsigned maxRows);
+
+		RowSet(RowSet&& o) noexcept = default;
+		RowSet& operator=(RowSet&& o) noexcept = default;
+
+		RowSet(const RowSet&) = delete;
+		RowSet& operator=(const RowSet&) = delete;
+
+	public:
+		///
+		/// @brief Returns the number of rows actually fetched.
+		///
+		unsigned getCount() const noexcept
+		{
+			return count;
+		}
+
+		///
+		/// @brief Returns the message length (in bytes) of each row.
+		///
+		unsigned getMessageLength() const noexcept
+		{
+			return messageLength;
+		}
+
+		///
+		/// @brief Returns a pointer to the raw data of the row at `index`.
+		/// @param index Zero-based row index (must be < getCount()).
+		///
+		const std::byte* getRow(unsigned index) const
+		{
+			assert(index < count);
+			return buffer.data() + static_cast<std::size_t>(index) * messageLength;
+		}
+
+		///
+		/// @brief Returns a mutable pointer to the raw data of the row at `index`.
+		/// @param index Zero-based row index (must be < getCount()).
+		///
+		std::byte* getRow(unsigned index)
+		{
+			assert(index < count);
+			return buffer.data() + static_cast<std::size_t>(index) * messageLength;
+		}
+
+		///
+		/// @brief Returns the entire contiguous buffer containing all fetched rows.
+		///
+		const std::vector<std::byte>& getBuffer() const noexcept
+		{
+			return buffer;
+		}
+
+	private:
+		unsigned count = 0;
+		unsigned messageLength = 0;
+		std::vector<std::byte> buffer;
+	};
+}  // namespace fbcpp
+
+#endif  // FBCPP_ROWSET_H
diff --git a/src/fb-cpp/fb-cpp.h b/src/fb-cpp/fb-cpp.h
@@ -30,6 +30,7 @@
 #include "Transaction.h"
 #include "Descriptor.h"
 #include "Statement.h"
+#include "RowSet.h"
 #include "Batch.h"
 #include "Blob.h"
 #include "EventListener.h"
diff --git a/src/test/RowSet.cpp b/src/test/RowSet.cpp
@@ -0,0 +1,175 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2026 F.D.Castel
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include "TestUtil.h"
+#include "fb-cpp/RowSet.h"
+#include "fb-cpp/Statement.h"
+#include "fb-cpp/Transaction.h"
+#include <cstring>
+
+
+BOOST_AUTO_TEST_SUITE(RowSetSuite)
+
+BOOST_AUTO_TEST_CASE(fetchRowsIntoRowSet)
+{
+	const auto database = getTempFile("RowSet-fetchRowsIntoRowSet.fdb");
+
+	Attachment attachment{CLIENT, database, AttachmentOptions().setCreateDatabase(true)};
+	FbDropDatabase attachmentDrop{attachment};
+
+	Transaction transaction{attachment};
+
+	Statement ddl{attachment, transaction, "create table t (col integer)"};
+	ddl.execute(transaction);
+	transaction.commitRetaining();
+
+	Statement insert{attachment, transaction, "insert into t (col) values (?)"};
+	for (int i = 1; i <= 5; ++i)
+	{
+		insert.setInt32(0, i);
+		insert.execute(transaction);
+	}
+
+	Statement select{attachment, transaction, "select col from t order by col"};
+	BOOST_REQUIRE(select.execute(transaction));
+
+	// The first row (1) was fetched by execute(). Fetch remaining rows into RowSet.
+	RowSet rowSet{select, 10};
+
+	BOOST_CHECK_EQUAL(rowSet.getCount(), 4u);
+	BOOST_CHECK(rowSet.getMessageLength() > 0);
+	BOOST_CHECK_EQUAL(
+		rowSet.getBuffer().size(), static_cast<std::size_t>(rowSet.getCount()) * rowSet.getMessageLength());
+
+	// Verify row data by reading int32 values from the raw buffer using
+	// the output descriptor offsets.
+	const auto& descriptors = select.getOutputDescriptors();
+	BOOST_REQUIRE_EQUAL(descriptors.size(), 1u);
+
+	for (unsigned i = 0; i < rowSet.getCount(); ++i)
+	{
+		const auto* row = rowSet.getRow(i);
+		std::int32_t value;
+		std::memcpy(&value, row + descriptors[0].offset, sizeof(value));
+		BOOST_CHECK_EQUAL(value, static_cast<std::int32_t>(i + 2));
+	}
+}
+
+BOOST_AUTO_TEST_CASE(fetchFewerRowsThanMaxRows)
+{
+	const auto database = getTempFile("RowSet-fetchFewerRowsThanMaxRows.fdb");
+
+	Attachment attachment{CLIENT, database, AttachmentOptions().setCreateDatabase(true)};
+	FbDropDatabase attachmentDrop{attachment};
+
+	Transaction transaction{attachment};
+
+	Statement ddl{attachment, transaction, "create table t (col integer)"};
+	ddl.execute(transaction);
+	transaction.commitRetaining();
+
+	Statement insert{attachment, transaction, "insert into t (col) values (?)"};
+	for (int i = 1; i <= 3; ++i)
+	{
+		insert.setInt32(0, i);
+		insert.execute(transaction);
+	}
+
+	Statement select{attachment, transaction, "select col from t order by col"};
+	BOOST_REQUIRE(select.execute(transaction));
+
+	// execute() fetched row 1. Request 100 rows but only 2 remain.
+	RowSet rowSet{select, 100};
+
+	BOOST_CHECK_EQUAL(rowSet.getCount(), 2u);
+	BOOST_CHECK_EQUAL(
+		rowSet.getBuffer().size(), static_cast<std::size_t>(rowSet.getCount()) * rowSet.getMessageLength());
+}
+
+BOOST_AUTO_TEST_CASE(rowSetIsDisconnectedFromStatement)
+{
+	const auto database = getTempFile("RowSet-isDisconnectedFromStatement.fdb");
+
+	Attachment attachment{CLIENT, database, AttachmentOptions().setCreateDatabase(true)};
+	FbDropDatabase attachmentDrop{attachment};
+
+	Transaction transaction{attachment};
+
+	Statement ddl{attachment, transaction, "create table t (col integer)"};
+	ddl.execute(transaction);
+	transaction.commitRetaining();
+
+	Statement insert{attachment, transaction, "insert into t (col) values (?)"};
+	for (int i = 1; i <= 3; ++i)
+	{
+		insert.setInt32(0, i);
+		insert.execute(transaction);
+	}
+
+	Statement select{attachment, transaction, "select col from t order by col"};
+	BOOST_REQUIRE(select.execute(transaction));
+
+	RowSet rowSet{select, 10};
+	BOOST_CHECK_EQUAL(rowSet.getCount(), 2u);
+
+	// Free the statement; the RowSet data is still valid.
+	select.free();
+
+	const auto& descriptors_copy = rowSet.getBuffer();
+	BOOST_CHECK(!descriptors_copy.empty());
+	BOOST_CHECK_EQUAL(rowSet.getCount(), 2u);
+}
+
+BOOST_AUTO_TEST_CASE(moveConstructor)
+{
+	const auto database = getTempFile("RowSet-moveConstructor.fdb");
+
+	Attachment attachment{CLIENT, database, AttachmentOptions().setCreateDatabase(true)};
+	FbDropDatabase attachmentDrop{attachment};
+
+	Transaction transaction{attachment};
+
+	Statement ddl{attachment, transaction, "create table t (col integer)"};
+	ddl.execute(transaction);
+	transaction.commitRetaining();
+
+	Statement insert{attachment, transaction, "insert into t (col) values (?)"};
+	for (int i = 1; i <= 3; ++i)
+	{
+		insert.setInt32(0, i);
+		insert.execute(transaction);
+	}
+
+	Statement select{attachment, transaction, "select col from t order by col"};
+	BOOST_REQUIRE(select.execute(transaction));
+
+	RowSet rowSet1{select, 10};
+	const auto count = rowSet1.getCount();
+
+	RowSet rowSet2{std::move(rowSet1)};
+	BOOST_CHECK_EQUAL(rowSet2.getCount(), count);
+	BOOST_CHECK_EQUAL(rowSet1.getCount(), 0u);
+}
+
+BOOST_AUTO_TEST_SUITE_END()
