[Development] [QIODevice]How to correctly treat/understand of the documentation?
Carlos Duclos
carlosduclosv at yahoo.com
Thu Apr 17 22:18:30 CEST 2014
Hi,
I'm not sure I understand your question so I'll reply according to what I understood.
QIODevice is a generic interface and as such has to provide an interface that works well with different ways of doing things. What seems to confuse you is the possibility of doing buffered communications and non-buffered communications.
There is no simple answer to what is correct when it comes to buffered versus non-buffered. There are too many variables involved in making such a decision and therefore QIODevice is flexible enough to work with both approaches. For some type of devices a buffered approach is preferred for some applications while a non-buffered approach might work best in other situations.
For example, if your application requires sending chunks of data once a day (let's think of a control device hanging somewhere in a building) and the data is computed before sending it, then a buffered approach might be the right solution. You do your calculation, print what you need to print and once you are done with that the device might empty the buffer and continue. This is a common situation in embedded devices that are connected over slow communication lines, such as RS232 or RS485 (or even 422). If the device is instead connected to a fast communication line and it requires to send data often, then writing it directly might be the right choice.
There is no unique way to answer the problem without knowing exactly what you are trying to do. What QIODevice allows you is to implement your own device that works as you need it. If buffering is the right solution to your problem then you use buffering, if not you don't use it. If it is difficult to decide which approach, implement both and let the open method tell you which one to use. The key point is that you can specialize your device as much as you want and the interface will allow it.
In the case of a serial port, then there are already several layers of buffering starting at the hardware level all the way to the OS. This allows to write a lot of data but at the cost of introducing delays that might be difficult to control.
Regarding your final question about how many bytes you will receive, it is difficult to answer without knowing more details such as what kind of device you were using.
If I missed the point and I did not understand your questions, please accept my apologies and ask the question in another way.
Cheers!
>Hi all.
>
>I have the question concerning correct treatment of documentation and
>implementation of I/O methods, e.g. for QtSerialPort.
>
>== write ==
>
>For example, regarding to the QIODevice::write() method. Investigating of
>Qt5 source codes I see two approaches in classes derived from >QIODevice (I
>talk about the buffered mode):
>
>1) "Deferred writing"
>
>When QIODevice::write () only adds a next portion of data to the internal
>write buffer. But real data transmission is carried out later, on an next
>step: on a signal from an notifier (for example from the Tx FIFO event,
>that signalise about FIFO is empty and can be sent next portion of data
>from the internal buffer).
>
>This behavior is implemented, for example in the QAbstractSocket for a
>buffered mode.
>
>2) "Directly writing"
>
>This approach when the QIODevice::write() transfers data at once to the
>device, directly.
>
>I.e. in my head there is a confusion. How it is necessary to do for the
>buffered mode more correctly?
>For me, more pleasant that is the first method...
>
>But, if I am not right (i.e. when need to use "directly" writing to
>minimize time between packets), then what reasons in TCP socket the >first
>"deferred" method is used?
>
>== flush ==
>
>What expected behavior for the QIODevice::flush() method and for the
>bytesWritten(qint64) signal?
>
>For example two scenarios:
>
>1) Without flush()
>
>MyClass::foo()
>{
> p.write('a');
> p.write('b');
>}
>MyClass::bar()
>{
> p.write('c');
> p.write('d');
>}
>
>when, the bar() method were called after foo() (with some delay), but >when
>not all data ("a" and "b") was written (e.g. was in time written only "a").
>
>then I expected to receive two: bytesWrittenSignal(2 byte) +
>bytesWrittenSignal(2 byte)
>
>
>2) With flush()
>
>MyClass::foo()
>{
> p.write('a');
> p.write('b');
>}
>
>MyClass::bar()
>{
> p.write('c');
> p.write('d');
> p.flush();
>}
>
>when, the bar() method were called after foo() (with some delay), but >when
>not all data ("a" and "b") was written (e.g. was in time written only "a").
>
>then I expected to receive one bytesWrittenSignal(4 byte)
>
>Whether correctly I understand?nd for expected behavior?
>
>
>Best regards,
>Denis
El Jueves, 17 de abril, 2014 5:15 P.M., "development-request at qt-project.org" <development-request at qt-project.org> escribió:
Send Development mailing list submissions to
development at qt-project.org
To subscribe or unsubscribe via the World Wide Web, visit
http://lists.qt-project.org/mailman/listinfo/development
or, via email, send a message with subject or body 'help' to
development-request at qt-project.org
You can reach the person managing the list at
development-owner at qt-project.org
When replying, please edit your Subject line so it is more specific
than "Re: Contents of Development digest..."
Today's Topics:
1. Documenting JavaScript with QDoc (Milian Wolff)
2. Re: Documenting JavaScript with QDoc (Aleix Pol)
3. Qt5.3 change files (Heikkinen Jani)
4. Re: Qt5.3 change files (Peter Hartmann)
5. [QIODevice]How to correctly treat/understand of the
documentation? (Denis Shienkov)
6. Re: Qt5.3 change files (Thiago Macieira)
7. QScreen API (Aleix Pol)
----------------------------------------------------------------------
Message: 1
Date: Thu, 17 Apr 2014 12:38:36 +0200
From: Milian Wolff <milian.wolff at kdab.com>
Subject: [Development] Documenting JavaScript with QDoc
To: "development at qt-project.org" <development at qt-project.org>
Message-ID: <1698764.mHPlDnUIp0 at milian-kdab2>
Content-Type: text/plain; charset="us-ascii"
Hello!
I'm trying to add documentation to the JavaScript API of QWebChannel. It is a
fundamental part of this module and as such, I think proper documentation is
crucial.
So far, I have not found a way to get qdoc to generate a page for my .js file
for me. Can it? Or do I have to create a separate .qdoc file, and - if so -
what commands to I need to use in that file?
I tried something like this:
/*!
\title Qt WebChannel JavaScript API
\page javascript.html
To communicate with a QWebChannel or WebChannel, any HTML client must use
and setup the
JavaScript API provided by \c qwebchannel.js.
*/
/*!
\qmltype foo
asdfsadf
*/
/*!
\qmlmethod bool foo::test();
foo bar
*/
On the javascript.html page, I then cannot see anything about foo nor
foo::test... Is there maybe a module out there which documents "pure" .js
files? In QtDeclarative, I only found documentation for .cpp/.qml functions
so far. Even things like qsTr are actually documentation for a .cpp method
which gets renamed using \qmlmethod...
Hope anyone can help me here. The only potential workaround I could think of
so far would be adding a dummy .cpp file for the documentation of the .js API
of the QWebChannel.
Thanks
--
Qt Developer Days 2014 - October 6 - 8 at BCC, Berlin
Milian Wolff | milian.wolff at kdab.com | Software Engineer
KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
Tel. Germany +49-30-521325470, Sweden (HQ) +46-563-540090
KDAB - Qt Experts - Platform-independent software solutions
------------------------------
Message: 2
Date: Thu, 17 Apr 2014 13:07:12 +0200
From: Aleix Pol <aleixpol at kde.org>
Subject: Re: [Development] Documenting JavaScript with QDoc
To: Milian Wolff <milian.wolff at kdab.com>
Cc: "development at qt-project.org" <development at qt-project.org>
Message-ID:
<CACcA1RqjxjE1RfQsnrpuDUwKS2S64h6QhK8ZjYj=SzEk0jckeA at mail.gmail.com>
Content-Type: text/plain; charset="utf-8"
On Thu, Apr 17, 2014 at 12:38 PM, Milian Wolff <milian.wolff at kdab.com>wrote:
> Hello!
>
> I'm trying to add documentation to the JavaScript API of QWebChannel. It
> is a
> fundamental part of this module and as such, I think proper documentation
> is
> crucial.
>
> So far, I have not found a way to get qdoc to generate a page for my .js
> file
> for me. Can it? Or do I have to create a separate .qdoc file, and - if so -
> what commands to I need to use in that file?
>
> I tried something like this:
>
> /*!
> \title Qt WebChannel JavaScript API
> \page javascript.html
>
> To communicate with a QWebChannel or WebChannel, any HTML client must
> use
> and setup the
> JavaScript API provided by \c qwebchannel.js.
> */
>
> /*!
> \qmltype foo
>
> asdfsadf
> */
>
> /*!
> \qmlmethod bool foo::test();
>
> foo bar
> */
>
> On the javascript.html page, I then cannot see anything about foo nor
> foo::test... Is there maybe a module out there which documents "pure" .js
> files? In QtDeclarative, I only found documentation for .cpp/.qml
> functions
> so far. Even things like qsTr are actually documentation for a .cpp method
> which gets renamed using \qmlmethod...
>
> Hope anyone can help me here. The only potential workaround I could think
> of
> so far would be adding a dummy .cpp file for the documentation of the .js
> API
> of the QWebChannel.
>
> Thanks
>
> --
> Qt Developer Days 2014 - October 6 - 8 at BCC, Berlin
>
> Milian Wolff | milian.wolff at kdab.com | Software Engineer
> KDAB (Deutschland) GmbH&Co KG, a KDAB Group company
> Tel. Germany +49-30-521325470, Sweden (HQ) +46-563-540090
> KDAB - Qt Experts - Platform-independent software solutions
>
> _______________________________________________
> Development mailing list
> Development at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development
>
FWIW, I think we already did something similar for Doxygen, you definitely
want to be able to document it.
Aleix
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.qt-project.org/pipermail/development/attachments/20140417/01b0fa0e/attachment-0001.html
------------------------------
Message: 3
Date: Thu, 17 Apr 2014 11:38:05 +0000
From: Heikkinen Jani <Jani.Heikkinen at digia.com>
Subject: [Development] Qt5.3 change files
To: "development at qt-project.org" <development at qt-project.org>
Message-ID:
<F2D121D33ACDD34DB72834D8E8B2378D30E9CC at IT-EXMB01-HKI.it.local>
Content-Type: text/plain; charset="us-ascii"
Hi all (maintainers)!
It seem some change files are still missing :( It would be good to have at least initial versions before RC...
All maintainers: If your component doesn't have 5.3 changes file yet, please add it as soon as possible!
Br,
Jani
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.qt-project.org/pipermail/development/attachments/20140417/86d0aee8/attachment-0001.html
------------------------------
Message: 4
Date: Thu, 17 Apr 2014 14:23:09 +0200
From: Peter Hartmann <phartmann at blackberry.com>
Subject: Re: [Development] Qt5.3 change files
To: Heikkinen Jani <Jani.Heikkinen at digia.com>,
"development at qt-project.org" <development at qt-project.org>
Message-ID: <534FC7AD.7070309 at blackberry.com>
Content-Type: text/plain; charset="UTF-8"; format=flowed
On 04/17/2014 01:38 PM, Heikkinen Jani wrote:
> It seem some change files are still missing ? It would be good to have
> at least initial versions before RC?
>
> All maintainers: If your component doesn?t have 5.3 changes file yet,
> please add it as soon as possible!
I was under the impression that the changes file is generated from the
[ChangeLog] entries in the git commit messages; or is this not the case?
Peter
------------------------------
Message: 5
Date: Thu, 17 Apr 2014 18:13:39 +0400
From: Denis Shienkov <denis.shienkov at gmail.com>
Subject: [Development] [QIODevice]How to correctly treat/understand of
the documentation?
To: "development at qt-project.org" <development at qt-project.org>, Thiago
Macieira <thiago.macieira at intel.com>
Message-ID:
<CAHtcb0z0eNhPrm4bqVd6d3eomRioFqydek6McratjU85Rfxqfw at mail.gmail.com>
Content-Type: text/plain; charset="utf-8"
Hi all.
I have the question concerning correct treatment of documentation and
implementation of I/O methods, e.g. for QtSerialPort.
== write ==
For example, regarding to the QIODevice::write() method. Investigating of
Qt5 source codes I see two approaches in classes derived from QIODevice (I
talk about the buffered mode):
1) "Deferred writing"
When QIODevice::write () only adds a next portion of data to the internal
write buffer. But real data transmission is carried out later, on an next
step: on a signal from an notifier (for example from the Tx FIFO event,
that signalise about FIFO is empty and can be sent next portion of data
from the internal buffer).
This behavior is implemented, for example in the QAbstractSocket for a
buffered mode.
2) "Directly writing"
This approach when the QIODevice::write() transfers data at once to the
device, directly.
I.e. in my head there is a confusion. How it is necessary to do for the
buffered mode more correctly?
For me, more pleasant that is the first method...
But, if I am not right (i.e. when need to use "directly" writing to
minimize time between packets), then what reasons in TCP socket the first
"deferred" method is used?
== flush ==
What expected behavior for the QIODevice::flush() method and for the
bytesWritten(qint64) signal?
For example two scenarios:
1) Without flush()
MyClass::foo()
{
p.write('a');
p.write('b');
}
MyClass::bar()
{
p.write('c');
p.write('d');
}
when, the bar() method were called after foo() (with some delay), but when
not all data ("a" and "b") was written (e.g. was in time written only "a").
then I expected to receive two: bytesWrittenSignal(2 byte) +
bytesWrittenSignal(2 byte)
2) With flush()
MyClass::foo()
{
p.write('a');
p.write('b');
}
MyClass::bar()
{
p.write('c');
p.write('d');
p.flush();
}
when, the bar() method were called after foo() (with some delay), but when
not all data ("a" and "b") was written (e.g. was in time written only "a").
then I expected to receive one bytesWrittenSignal(4 byte)
Whether correctly I understand?nd for expected behavior?
Best regards,
Denis
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.qt-project.org/pipermail/development/attachments/20140417/73bf7252/attachment-0001.html
------------------------------
Message: 6
Date: Thu, 17 Apr 2014 07:36:50 -0700
From: Thiago Macieira <thiago.macieira at intel.com>
Subject: Re: [Development] Qt5.3 change files
To: development at qt-project.org
Message-ID: <5801574.VXhH5xrcqh at tjmaciei-mobl4>
Content-Type: text/plain; charset="utf-8"
Em qui 17 abr 2014, ?s 14:23:09, Peter Hartmann escreveu:
> On 04/17/2014 01:38 PM, Heikkinen Jani wrote:
> > It seem some change files are still missing ? It would be good to have
> > at least initial versions before RC?
> >
> > All maintainers: If your component doesn?t have 5.3 changes file yet,
> > please add it as soon as possible!
>
> I was under the impression that the changes file is generated from the
> [ChangeLog] entries in the git commit messages; or is this not the case?
They are. I will run the script for the changelog and the header diff
RealSoonNow?.
--
Thiago Macieira - thiago.macieira (AT) intel.com
Software Architect - Intel Open Source Technology Center
------------------------------
Message: 7
Date: Thu, 17 Apr 2014 16:54:39 +0200
From: Aleix Pol <aleixpol at kde.org>
Subject: [Development] QScreen API
To: development <development at qt-project.org>
Message-ID:
<CACcA1Rrj5YXd1fv48m5xtjEF3DHN5a-v1UEV0POhXUDJ6QmrDA at mail.gmail.com>
Content-Type: text/plain; charset="utf-8"
Hi,
Yesterday I was trying to figure out a problem I've been having on some
code that keeps track of screen management changes on my system. After some
investigation I came to the conclusion that my problem was in Qt [1].
I'm sending this e-mail to know what's the status on the subject, if this
is something we'd like to fix or we have to adopt a solution specific for
the project (actually we already have a libkscreen, that would work). Still
the current state doesn't look good and we probably want to have it fixed
in Qt.
Furthermore, we realized that there's some API we're lacking as well, at
least we'd need to have a QGuiApplication::primaryScreenChanged signal and
probably a QGuiApplication::screenRemoved signal as well (this way we
wouldn't have to connect to QObject::destroyed on the screens).
TL;DR, what do the maintainers think of the screen management API we have?
Is anybody working on it? Is it documented anywhere why it was designed
this way? Am I missing something?
Thanks!
Aleix
[1] https://bugreports.qt-project.org/browse/QTBUG-38404
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.qt-project.org/pipermail/development/attachments/20140417/8903585f/attachment.html
------------------------------
_______________________________________________
Development mailing list
Development at qt-project.org
http://lists.qt-project.org/mailman/listinfo/development
End of Development Digest, Vol 31, Issue 41
*******************************************
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20140417/50d81d63/attachment.html>
More information about the Development
mailing list