Skip to content

Merge the read and write buffers - #543

Open
vsoulgard wants to merge 13 commits into
boostorg:developfrom
vsoulgard:feature/279-merge-read-write-buffers
Open

vsoulgard wants to merge 13 commits into
boostorg:developfrom
vsoulgard:feature/279-merge-read-write-buffers

Conversation

@vsoulgard

Copy link
Copy Markdown
Contributor

close #279

Because std::vector size is managed manually in read_buffer and never shrinks, we cannot directly change its size (with clear()) because read_buffer relies on std::vector state, thus we need to use another wrapper, which manages size manually just as read_buffer. Furthermore, we use next_power_of_two to grow.

There is no max_buffer_size_ for buffer_writer because such behaviour already implemented in serialization_context.

@vsoulgard
vsoulgard marked this pull request as draft November 7, 2026 18:51
@codecov

codecov Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.19%. Comparing base (c5e5382) to head (8a59ad0).
⚠️ Report is 3 commits behind head on develop.

Additional details and impacted files

Impacted file tree graph

@@             Coverage Diff             @@
##           develop     #543      +/-   ##
===========================================
+ Coverage    99.17%   99.19%   +0.02%     
===========================================
  Files          146      147       +1     
  Lines         7400     7493      +93     
===========================================
+ Hits          7339     7433      +94     
+ Misses          61       60       -1     
Files with missing lines Coverage Δ
include/boost/mysql/any_connection.hpp 100.00% <ø> (ø)
include/boost/mysql/impl/any_connection.ipp 100.00% <ø> (ø)
...ql/impl/internal/protocol/impl/binary_protocol.hpp 98.91% <100.00%> (ø)
...sql/impl/internal/protocol/impl/protocol_types.hpp 98.91% <100.00%> (ø)
...l/internal/protocol/impl/serialization_context.hpp 100.00% <ø> (ø)
...ost/mysql/impl/internal/protocol/serialization.hpp 100.00% <100.00%> (ø)
...sql/impl/internal/sansio/connection_state_data.hpp 100.00% <100.00%> (ø)
...oost/mysql/impl/internal/sansio/message_reader.hpp 100.00% <100.00%> (ø)
...ude/boost/mysql/impl/internal/sansio/rw_buffer.hpp 100.00% <100.00%> (ø)
...ost/mysql/impl/internal/sansio/start_execution.hpp 100.00% <100.00%> (ø)
... and 2 more

... and 5 files with indirect coverage changes


Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c5e5382...8a59ad0. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@vsoulgard
vsoulgard marked this pull request as ready for review November 7, 2026 21:50
@anarthal

Copy link
Copy Markdown
Collaborator

Hi! Thanks for the PR.

I think we need to do some redesigning to make this cleaner.

First, the unique_ptr in pipeline_request needs to go. As it is, it makes the class non-copyable, which is a breaking change (and something we don't want).

Second, I see some 'smells' with the current implementation:

  • read_buffer and message_reader used to own the storage, and prevent access to it by encapsulation. This encapsulation is now broken by providing an accessor to the internal read buffer. This works but makes invariants weaker.
  • This all works because we don't overlap reading and writing at any point, but we have no way to check this invariant.

There is also an internal/ header included in a public file, which should be avoided.

I don't see a perfect answer, but if I were writing this, I'd try this design and see if it looks clean:

  • Merge read buffer/write buffer functionality into a single class. My Claude suggested to use the free area for serialization, so we never end up clobbering data that we haven't consumed yet. I'd go further and assert that when we write (or have the intent to do so), we don't have any data in the current message/pending areas.
  • Keep pipeline_request as a vector. This implies templating serialization_context. I don't know how big/dirty the change would be, but all the serialization headers are internal, and thus should't contribute to build times if separate compilation is enabled (TL;DR: I think it should be OK). serialization_context should be okay any container having .data(), .size(), and an insert function that appends data to the end.

If you can think of an alternative proposal, I'm happy to discuss.

Best,
Ruben.

@vsoulgard

Copy link
Copy Markdown
Contributor Author

Your design suggestion looks clean for me. I will merge read_buffer with buffer_writer and rename it to rw_buffer.

We still need to expose rw_buffer field from message_reader class to pass it to serialization_context. I suggest refactoring message_reader to store a reference to rw_buffer, so we don't need to break encapsulation since rw_buffer is a shared object which asserts its state.

If pipeline_request must be copyable, then it looks like a UT gap. Should I cover this case in the PR?

Thanks.

@anarthal

Copy link
Copy Markdown
Collaborator

Storing a reference should be fine and looks good practice.

Please add UTs for these, it looks like I skipped them. Thank you.

@vsoulgard

Copy link
Copy Markdown
Contributor Author

Ready for review. Additionally, rearranged some fields - connection_state_data size reduced from 352 to 304.

@anarthal

Copy link
Copy Markdown
Collaborator

Thanks. Will have a look tomorrow.

@anarthal

Copy link
Copy Markdown
Collaborator

While I was doing the review (comments coming soon), I encountered this (new) potential pitfall:

Imagine you're using the multi-function API. You get rows with read_some_rows(). This hands out a rows_view object pointing to the connection's internal read buffer. In our own docs, the contract says:

The returned view points into memory owned by *this. It will be valid until
*this performs the next network operation or is destroyed.

Before this PR, the following used to work because serialization happened before the read buffer was touched at all:

execution_state st;
// start_execution, read more rows...
auto rows = conn.read_some_rows(st);
conn.execute(with_params{"SELECT ... {}"}, rows.at(0).at(0).as_string());

Now this is UB, because rw_buffer might reallocate during serialization, invalidating the row before any serialization might happen. Even if it doesn't reallocate, source and destination might overlap when serializing, which is UB if we use memcpy.

So before going on with this, we need to make a decision. I see two options:

  1. We consider that this case was never supported to begin with, and used to work out of luck. We clarify it in the wording, we can even write a "don't do" section covering this specifically.
  2. We consider that this would be a breaking change. I don't see a way of realistically fixing this, other than not merging the buffers at all.

Honestly, I don't think this use case is very common. read_some_rows should usually be called in a loop, because you can't trigger another operation until the current one runs out of rows. On the other hand, merging the buffers is a small optimization, which I don't expect to have a big impact, so I'd be fine to retract it, too.

Before I go on with the review, what do you think of this?

@vsoulgard

Copy link
Copy Markdown
Contributor Author

This is a good catch, indeed.

I have some thoughts on a possible compromise solution: could we just change return type of field_view::as_string() from string_view to std::string and add separate field_view::as_string_view(). With SSO it would be very cheap, but it would be a breaking change for usage like:

// Dangling Pointer
std::string_view sv = rows.at(0).at(0).as_string();

But it's just a random idea that occurred to me and I haven't really given it much thought.

Regarding your suggestions, I don't think merging buffers is worth the breaking change. If you want to revert this change, I would not be against it. But if we choose to support such usage of the multi-function API, we should cover this specific case to avoid breaking it in the future.

Thanks.

@anarthal

Copy link
Copy Markdown
Collaborator

I have some thoughts on a possible compromise solution: could we just change return type of field_view::as_string() from string_view to std::string and add separate field_view::as_string_view(). With SSO it would be very cheap, but it would be a breaking change for usage like:

That's a dangerous change, yes. I wouldn't go down this route.

At the moment, the recommended way to get an owning type would be using field, row or rows, but these need to be constructed explicitly by the user.

But if we choose to support such usage of the multi-function API, we should cover this specific case to avoid breaking it in the future.

I complete agree with this. I've been trying to compose an example reproducing the problem, but I'm failing to see a plausible case where this breaks and that is not highly dubious to begin with. For instance:

mysql::execution_state st;
co_await conn.async_start_execution("SELECT first_name, last_name, salary FROM employee WHERE id = 42", st);
mysql::rows_view employees = co_await conn.async_read_some_rows(st);
assert(!st.shoud_read_rows());
co_await conn.async_execute(with_params("... {}", employees.at(0).at(0)), some_result);

This works most of the time when you have only 1 row, but is not guaranteed to, because the EOF packet is not guaranteed to be read in the same batch as the row (it likely is, but it may not, depending on the network and the row size).

Another try:

mysql::rows_view employees;
do
{
    mysql::rows_view employees = co_await conn.async_read_some_rows(st);
    for (auto employee : employees)
        print_employee(employee);
} while (st.should_read_rows());
if (!employees.empty())
    co_await conn.async_execute(mysql::with_params("... {}", employees.at(0).at(0)), some_result);

This doesn't trigger the assert, but once again, you don't have any guarantee that this async_execute will run at all, for the same reason I described above.

So: can you think of a use case that is plausible and actually breaks? I'm a bit divided. On the one hand, keeping it as-is is the safest, and the gains aren't that big. On the other hand, I don't want to encourage use cases that aren't sound at all.

@vsoulgard

vsoulgard commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

I have researched and haven't found any guaranteed way to fetch a row with an EOF packet over TCP even if we control row size with query SELECT 'first_name', 'last_name', 100.
Furthermore, MariaDB and MySQL use TCP_NODELAY, which indicates that the row and EOF packets could be received in separate TCP packets (UPD: As TCP_NODELAY is the mark of design, where is latency preferred over integrity). And I would say that, usually, we do not expect to receive all at once for TCP connections of any kind.

When using async_read_some_rows, do we expect an unspecified number of rows? That means in a common use case every row would be processed separately, so the most realistic usage I see is:

std::vector<std::string> names;
do
{
    mysql::rows_view employees = co_await conn.async_read_some_rows(st);
    for (auto employee : employees)
        names.push_back(employee.at(0));
} while (st.should_read_rows());
// Process received names with async_execute()

@anarthal

Copy link
Copy Markdown
Collaborator

When using async_read_some_rows, do we expect an unspecified number of rows?

Yes. The docs state it.

That means in a common use case every row would be processed separately, so the most realistic usage I see is:

Back when I wrote it, I envisioned it for large resultsets within ETL processes. Imagine you want to write your rows into a file:

do
{
    mysql::rows_view employees = co_await conn.async_read_some_rows(st);
    for (auto employee : employees)
        // write the employee to the file, or to a socket, database, HTTP connection...
} while (st.should_read_rows());

@vsoulgard

Copy link
Copy Markdown
Contributor Author

Back when I wrote it, I envisioned it for large resultsets within ETL processes. Imagine you want to write your rows into a file:

In that case where large rows are consumed inside of a loop and copying is expensive, I would rather use connection pool if I need to write to database. Using last received mysql::rows_view after the loop looks unsound to me, because in a real scenario we must process rows received on each iteration.

And the problem stays the same: there is no guaranteed way to reproduce breaking use case, especially for a big row.

@anarthal

Copy link
Copy Markdown
Collaborator

Decided: we proceed with this. I'd ask you to slightly change (async)_read_some_rows docs to state that the views are valid only until the connection initiates the next network operation, so the contract stays clear. I'll come up with the full review as soon as I can - the C++ std committee is happening this week so I'm having less time.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Merge the read and write buffers

2 participants