Serial flush documentation and Arduino 1.0

Community Website and Forum
1

Hi
On a non Arduino forum (david) somebody got stuck on the functional change of serial .flush(). After I explained the change the problem was solved.

The forum moderator (Sven) made following remark: "Also thanks for info about flush. It is a big problem that flush now serves a completely different purpose... especially since it's not documented yet in the Arduino Reference."
I just checked and noticed that the description does not explain the difference in behavior between pre and post 1.0.

My question
What is the planning on behalf of updating the web site documentation?

Best regards
Jantje

2

The bottom of the Serial.flush page does point to the Stream.flush page, which does describe the new flush() capability. It does not, however, make it clear that Serial.flush() no longer operates as described, since Serial derives from Stream.

3

Paul
I just read the Stream.flush documentation and I have some remarks.

flush() clears the buffer once all outgoing characters have been sent.
The stream documentation states :Stream defines the reading functions in Arduino.
The stream flush states: flush() clears the buffer once all outgoing characters have been sent.
I would expect that to be incoming characters have been read as it is a reading functionality.

flush() clears the buffer once all outgoing characters have been sent.
There is no explanation what exactly is involved in clearing a buffer once the characters have been sent/read.

From my understanding I would describe the function
Reads the input from the input device and puts that information in a memory buffer. The information received from the external device is now available to the sketch from the memory buffer.

Returns boolean
The declaration of the method is virtual void flush(void);
I know in C/C++ void actually is the same as int and boolean but this is confusing.
The actual implementation in hardware serial doesn't return anything.

I think that now I understand why this method is called flush. It flushes the data from the SPI port to memory (like you flush from the toilet to the cesspool). From a end user perspective the name is at the least weird because as an end user you do not want to know about the cesspool.

I feel the documentation of this method needs a good look.

Please see my proposition below
Best regards
Jantje

My proposition:
flush()
Description

Reads the input from the external input device and puts that information in a memory buffer. The information received from the external input device is now available to the sketch from the memory buffer.

This method is part of the Stream class, and is a pure virtual method (which means there is no code attached to this method in the Stream class) as such it can only be called by a class that inherits from the Stream class and implements this method (in other words the class inheriting from Stream adds code to the method flush).
Inherited classes are : Wire, Serial, ....
See the Stream class main page for more information.

Syntax

stream.flush()
Parameters

stream : an instance of a class that inherits from Stream and implemented flush.
Returns

void
See also

4

flush() clears the buffer once all outgoing characters have been sent.
The stream documentation states :Stream defines the reading functions in Arduino.
The stream flush states: flush() clears the buffer once all outgoing characters have been sent.
I would expect that to be incoming characters have been read as it is a reading functionality.

No I don't think that is correct at all. flush only effects the receive buffer in that it just manipulates the two receiver buffer pointers (head and tail) to be equal, thus emptying the receiver buffer of any existing characters to be read regardless if there were valid characters in the buffer waiting to be read before executing the flush command. The fact that the flush command waits until the transmit buffer is empty before flushing the receiver buffer is what is new. Not sure why they added that new twist, possibly because they also added the transmit buffer and transmit interrupts at the same time? Transmitting serial characters use to be a 'blocking' command but now is not with the new transmit interrupts and buffer creation. So keep in mind that there are two buffers that are independent, receive and transmit and the flush command only manipulates the receive buffer.

My big problem with flush is that I see it used most often where it should not be used at all. There are very few valid use cases for a receive flush command in my opinion and I have yet to see a good usage in any of the sketches posted so far, but perhaps I have missed some?

5

retrolefty
I understand your remark as "indeed the documentation of Stream.flush needs some changes"
Best regards
Jantje

6

Jantje:
retrolefty
I understand your remark as "indeed the documentation of Stream.flush needs some changes"
Best regards
Jantje

Could be, I am kind of ignoring Arduino 1.0 until it becomes more mainstream with the majority of users and library developers. My programming skills are limited enough as is and don't want to have to suffer all the possible conversion headaches until some later date. :wink: