Add room() function to Serial Class to see free TXbuffer space (HWS & SWS)

[RobTillaart]

Sometimes one wants to know the amount of free places in the transmit buffer

The function to check this is straightforward.

int room()
{
  return (SERIAL_BUFFER_SIZE + tx_buffer.head - tx_buffer.tail) %  SERIAL_BUFFER_SIZE;
}
// % can be optimized with an if ()

this makes it possible to check and fill up the ring buffer to the max (esp when using low baud rates) without overflow.

• http://arduino.cc/forum/index.php/topic,165574.msg1235362.html#msg1235362

The name room() is not as ambiguous as space which already has a meaning in serial communication. Available() is already used for receive.

[pwbecker]

int room()
{
return (SERIAL_BUFFER_SIZE + _tx_buffer->head - _tx_buffer->tail - 1) % SERIAL_BUFFER_SIZE + 1;
}

[RobTillaart]

There allready exists the following function in hardwareSerial. Think it is
pretty much what you propose, just another name.

int HardwareSerial::available(void)
{
return (unsigned int)(SERIAL_BUFFER_SIZE + _rx_buffer->head -
_rx_buffer->tail) % SERIAL_BUFFER_SIZE;
}

On Sat, Sep 21, 2013 at 3:11 AM, pwbecker notifications@github.com wrote:

int room()
{
return (SERIAL_BUFFER_SIZE + _tx_buffer->head - _tx_buffer->tail - 1) %
SERIAL_BUFFER_SIZE + 1;
}

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1408#issuecomment-24853333
.

[RobTillaart]

Sorry, your proposal is on the transmittting site. Posted too quick. :)

Have you checked - https://code.google.com/p/arduino/issues/list - if a
similar proposal is made as it sounds familiar..

On Sat, Sep 21, 2013 at 3:13 PM, Rob Tillaart rob.tillaart@gmail.comwrote:

There allready exists the following function in hardwareSerial. Think it
is pretty much what you propose, just another name.

int HardwareSerial::available(void)
{
return (unsigned int)(SERIAL_BUFFER_SIZE + _rx_buffer->head -
_rx_buffer->tail) % SERIAL_BUFFER_SIZE;
}

On Sat, Sep 21, 2013 at 3:11 AM, pwbecker notifications@github.comwrote:

int room()
{
return (SERIAL_BUFFER_SIZE + _tx_buffer->head - _tx_buffer->tail - 1) %
SERIAL_BUFFER_SIZE + 1;
}

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1408#issuecomment-24853333
.

[PaulStoffregen]

Just a quick mention, on the Arduino Developers Mailing List, this feature was discussed. Cristian decided this function would be named writeBufferFree(), if it's ever implemented in Arduino.

Here's the mail list conversation, for reference.

https://groups.google.com/a/arduino.cc/forum/#!msg/developers/ls3hkviFYM4/XWT2LbfzNcgJ

[RobTillaart]

Seen (parts of) the discussion, think it is convergating in the right direction.
Thanks for the notification.

[bperrybap]

In my view this should be handled up in the stream class just like available() rather than down in HardwareSerial.
Having it is stream ensures that it is handled the same way for all libraries that use the stream class libraries vs being just a capability that is proprietary to HardwareSerial.

[matthijskooijman]

Better have it in Print rather than Stream, but otherwise agreed. Moving it upwards does complicate backward compatibility for implementations of Print that do not have this new function implemented yet, but discussion about this is already happening in the same thread linked above.

[bperrybap]

Print currently doesn't inherit from Stream so I don't see the issue of backward compatibility for Print if the function was added to Stream. The potential issue is for all of those that inherit from Stream, but if there was a default function in Stream, then even those would be able to still link.

[jantje]

Funny
Lots of the discussion Paul linked to is what I went through in issue #1930
I opted for -1 as the default implementation as it gives a way (at programming time) to see that the default has not been overloaded.
I do think having the method in stream is vital (at least it is for me) and only hardware Serial is really bad (and no solution to me) because replacing the serial to a software serial is going to break the code (and not only the logic)

[matthijskooijman]

@bperrybap, but I'm proposing to put the function in Print, not in Stream (since the former is about outputting things, just like the new writeBufferFree() function).

@jantje, the downside of returning -1 (as opposed to 1 or a large positive value) to signal "not implemented" is that callers are forced to check the return value - there is no automatic, graceful fallback. In the regard, using an unsigned return value and then returning -1 (== MAX_INT as unsigned) might be better as it allows automatic fallback at least in some cases, as well as not requiring a signed return value (which doesn't make any sense for available buffer space).

As for the naming of the functions - I think we discussed that on the mailing list and a decision was made, so I'm not going into that. I agree that we should put this method in Print (which is a superclass of Stream, so it ends up in Stream as well) and not just in HardwareSerial and other implementations.

[PaulStoffregen]

Jan, could you elaborate on "I do think having the method in stream is vital (at least it is for me) and only hardware Serial is really bad (and no solution to me) because replacing the serial to a software serial is going to break the code"?

Sometimes explaining just one important real application can be much more persuasive that simply claiming you need a feature. When you say "is going to break the code", if you explain what code this is, how it will break, and why that's important, the use of a specific case can really add weight to your argument.

Just to be clear, I'm not trying to argue either for or against this idea. I'm only trying to help you make a stronger case for it. So I guess in an indirect way, that means I'm for it?

I agree with Matthijs about the name. Cristian already said he made a final decision. Only Cristian can change the decision on the name.