[Development] QDataStream: blackbox or document all versions?

[Stottlemyer, Brett (B.S.)]

On 9/24/16, 11:58 PM, "Development on behalf of Thiago Macieira" <development-bounces+bstottle=ford.com at qt-project.org on behalf of thiago.macieira at intel.com> wrote:



>A thread[1] on the interest mailing list started when someone asked for the 
>docs for the current format of the QDataStream wire protocol, to which I 
>replied that it doesn't exist as we don't maintain such docs.

Not really sure which reply to respond to with my thoughts, so I’m going back to the beginning.

When you talk about documenting QDataStream, you are talking about using it with IPC, either to other processes on the same machine or different devices.  What you care about depends very much on what you are trying to do, which brings up the question of what should Qt support.  Questions off the top of my head: Which types are supported?  What errors are checked/caught?  Are they concerned with speed?  Speed on which platform?  Or are they concerned with packet size?  Which languages are supported?

Which types?
I’m going to assume that when Thiago talks about documenting QDataStream, he is talking about the operators in qtbase only?  That is, all of the custom QDataStream operators in other modules, whether they get an internal index or not?  Or is it every internal type, not matter which module?  I guess I should ask, rather than assume.  As I understand it, Qt stores an internal list of known types, each with an index.  When data is written, the index is written first, then the element itself, in whatever format.  Custom types won’t have an index by default, so if you pass one of those, QDataStream sends the name as well, and I’d assume, a size.  Even if the type has the data stream operator in both processes (or on both devices), it likely won’t be the same index, thus the name provides the way to look up the index.

I think we should assume that people will want to pass custom types, which means there needs to be a documented way to describe them.  You know people will want to pass Q_ENUM values, right?

Hopefully the question of custom types is valid, even if my attempted description of the internals is faulty.

For all of the other questions.
Different answers would likely favor different protocols.  There simply isn’t one best answer.  If we selected a specific use-case, there may be a best answer for that, but is that the best solution for Qt?

For my part, I’m very interested in this discussion.  Thiago’s point that JSON/DBus/etc provide alternatives to QDataStream is correct, but isn’t great for my use case.  As a user (and developer of) Qt Remote Objects[1], communication is between Qt and Qt, so it uses QDataStream.  To be able to also support interaction with non-Qt processes would great, but only if it can re-use the QDataStream.  I’m just not interested in the overhead (work and processing) of other formats when the focus is Qt.

My ideal option (specific to the use-case I care most about) would be a documented QDataStream format that supported one-time passing of custom type information (rather than passing each instance of a type), with minimal overhead on embedded targets and enough information to ignore unknown types.

[1] https://codereview.qt-project.org/p/playground/qtremoteobjects.git