[Development] QDataStream: blackbox or document all versions?

[Thiago Macieira]

On segunda-feira, 26 de setembro de 2016 12:00:46 PDT Stottlemyer, Brett 
(B.S.) wrote:
> 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?

Good questions all of them.

Right now, QDataStream does not catch errors, is not very speedy (big endian 
by default), is more concerned for easy marshalling and demarshalling of Qt 
types rather than compatibility or packet size.
 
> 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.

You're describing how QVariant's operator<< works. Outside of QVariant, 
there's no type index: the data is written as-is, no prefix, no header. You can 
write one quint32 and read two quint16. You can even write one QString and 
read a quint32 (then throw away the data).
 
> 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?

They write their operator<< and operator>>. That's all.
 
> 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.

Ok, this is a good point. Just like Rich mentioned for DCOP, we'd need to 
document at least one QDataStream version for Qt Remote Objects to be usable 
with non-Qt implementations.
 
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center