BufferedOutput Class Reference

To create a BufferedOutput use the macro createBufferedOutput see the detailed description. More...

#include <BufferedOutput.h>

Inherits Stream.

Public Member Functions
	BufferedOutput (size_t _bufferSize, uint8_t *_buf, BufferedOutputMode mode, bool allOrNothing=true)
	use createBufferedOutput(name, size, mode); instead BufferedOutput(size_t _bufferSize, uint8_t *_buf, BufferedOutputMode mode, bool allOrNothing = true); More...
void	connect (HardwareSerial &_serial)
	void connect(HardwareSerial& _serial); // the output to write to, can also read from More...
void	connect (Stream &_stream, const uint32_t baudRate=0)
	void connect(Stream& _stream, const uint32_t baudRate); // the stream to write to and how fast to write output, can also read from More...
void	nextByteOut ()
	void nextByteOut() More...
virtual size_t	write (uint8_t)
	write(uint8_t b) More...
virtual size_t	write (const uint8_t *buf, size_t size)
virtual int	available ()
virtual int	read ()
virtual int	peek ()
virtual void	flush ()
	void flush() More...
virtual int	availableForWrite ()
	int availableForWrite() More...
size_t	getSize ()
	size_t getSize(); More...
int	clearSpace (size_t len)
	int clearSpace(size_t len); More...
void	protect ()
	void protect() More...
void	clear ()
	void clear() More...
size_t	terminateLastLine ()
	size_t terminateLastLine() More...

Detailed Description

To create a BufferedOutput use the macro createBufferedOutput see the detailed description.

NOTE: Any '\0' chars added by write(0) calls, are filtered out of the final output.

The createBufferedOutput macro takes 2, 3 or 4 arguments.

createBufferedOutput(name, size); creates a BufferedOutput called name which can buffer upto size chars without blocking and then will block once the buffer fills up.
This default blocking when the buffer is full is not recommended.

Add a call to
bufferedOutput.nextByteOut();
at the top of the loop() to release the buffered chars. You can add more of these calls through out the loop() code if needed.
Most BufferedOutput methods also release the buffered chars.

createBufferedOutput(name, size, mode ); creates a BufferedOutput called name which can buffer upto size chars without blocking and mode determines what to do when the buffer is full.
mode can be one of BLOCK_IF_FULL, DROP_UNTIL_EMPTY or DROP_IF_FULL
BLOCK_IF_FULL just blocks until some chars can be sent to the output stream, so freeing up space in the buffer to accept more output. This mode is not recommended, but can be used for testing to force ALL output to be sent.
DROP_UNTIL_EMPTY will drop further output until all the output currently in the full buffer is sent to the output stream.
DROP_IF_FULL will drop further output until enough chars have been sent to the output stream to free up space for the output printed to the buffer.

If any chars are dropped then ~~ is added to the output sent so you can see where there is missing output.

This 3 argument version uses the default AllOrNothing == true setting. If the whole print(..) cannot fit in the buffer none of it is sent.

createBufferedOutput(name, size, mode, allOrNothing ); creates a BufferedOutput called name which can buffer upto size chars without blocking and mode determines what to do when the buffer is full and how to handle prints that do not entirely fit in the buffer.
AllOrNothing true will drop the entire print( ) if it will not completely fit in the buffer.
AllOrNothing false will only drop the part of the print( ) that will not fit in the buffer.

See Arduino Serial I/O for the Real World - BufferedOutput for an example of its use.

Definition at line 78 of file BufferedOutput.h.

Constructor & Destructor Documentation

BufferedOutput()

BufferedOutput::BufferedOutput	(	size_t	_bufferSize,
		uint8_t *	_buf,
		BufferedOutputMode	mode,
		bool	allOrNothing = true
	)

use createBufferedOutput(name, size, mode); instead
BufferedOutput(size_t _bufferSize, uint8_t *_buf, BufferedOutputMode mode, bool allOrNothing = true);

Parameters

buf	– the user allocated buffer to store the bytes, must be at least bufferSize long. Defaults to an internal 8 char buffer if buf is omitted or NULL
bufferSize	– number of bytes to buffer,max bufferSize is limited to 32766. Defaults to an internal 8 char buffer if bufferSize is < 8 or is omitted
mode	– BLOCK_IF_FULL, DROP_UNTIL_EMPTY or DROP_IF_FULL BLOCK_IF_FULL, like normal print, but with a buffer. Use this to see ALL the output, but will block the loop() when the output buffer fills DROP_UNTIL_EMPTY, when the output buffer is full, drop any more chars until it completely empties. ~~<CR><NL> is inserted in the output to show chars were dropped. Useful when there too much output. It allow multiple prints to be output consecutively to give meaning full output avaliableForWrite() will return 0 from when the buffer fills until is empties DROP_IF_FULL, when the output buffer is full, drop any more chars until here is space. ~~<CR><NL> is inserted in the output to show chars were dropped.
allOrNothing	– defaults to true, If true AND output buffer not empty then if write(buf,size) will not all fit don't output any of it. Else if false OR output buffer is empty then write(buf,size) will output partial data to fill output buffer. allOrNothing setting is ignored if mode is BLOCK_IF_FULL

Member Function Documentation

available()

virtual int BufferedOutput::available ( )

virtual

availableForWrite()

virtual int BufferedOutput::availableForWrite ( )

virtual

int availableForWrite()

Returns

bytes available to write. Includes the space available in the buffer plus the Serial Tx space available.

clear()

void BufferedOutput::clear

(

)

void clear()

Clears the entire buffer. Serial Tx buffer is NOT changed.

clearSpace()

int BufferedOutput::clearSpace

(

size_t

len

)

int clearSpace(size_t len);

Attempts to make len bytes space available in the buffer plus the Serial TX available space, by removing existing bytes if necessary.

If any bytes are removed a ~~, drop mark, is added. Removal stops at the protect() mark, a '\0' in the buffer.
Serial Tx buffer is NOT changed.

Returns

space available in buffer for write including the Serial Tx available space

Parameters

len	– number of bytes to make available for write.

connect() [1/2]

void BufferedOutput::connect

(

HardwareSerial &

_serial

)

void connect(HardwareSerial& _serial); // the output to write to, can also read from

Parameters

serial

– the HardwareSerial to buffer output to, usually Serial. You must call nextByteOut() each loop() in order to release the buffered chars.

connect() [2/2]

void BufferedOutput::connect	(	Stream &	_stream,
		const uint32_t	baudRate = 0
	)

void connect(Stream& _stream, const uint32_t baudRate); // the stream to write to and how fast to write output, can also read from

Parameters

stream	– the stream to buffer output to
baudRate	– the maximum rate at which the bytes are to be released. Bytes will be relased slower depending on how long your loop() method takes to execute You must call nextByteOut() each loop() in order to release the buffered chars.

flush()

virtual void BufferedOutput::flush ( )

virtual

void flush()

This blocks until the buffer empties

getSize()

size_t BufferedOutput::getSize

(

)

size_t getSize();

Returns

buffer size + any hardwareSerial buffer size found on connect

nextByteOut()

void BufferedOutput::nextByteOut

(

)

void nextByteOut()

This must be called often, at least every loop().
It releases one or more bytes if there is space available in the Serial Tx buffer
OR if a baud rate is set, then at that rate.

peek()

virtual int BufferedOutput::peek ( )

virtual

protect()

void BufferedOutput::protect

(

)

void protect()

Add a '\0' to the buffer to protect previous data from being removed by calls to clearSpace();

Calls to clear() still clear the entire buffer. All '\0' bytes are filtered from the output, including those added by write(0)

read()

virtual int BufferedOutput::read ( )

virtual

terminateLastLine()

size_t BufferedOutput::terminateLastLine

(

)

size_t terminateLastLine()

If the last character in the buffer is not \n add \r\n if space available, else add just \n

Returns

number of bytes written, if any

write() [1/2]

virtual size_t BufferedOutput::write ( const uint8_t *  buf, size_t  size  )

virtual

write() [2/2]

virtual size_t BufferedOutput::write ( uint8_t  )

virtual

write(uint8_t b)

Parameters

b	- byte to be added to the buffer.

NOTE: any '\0' chars are filtered from the final output.
But calling write(0) has the same effect as calling protect()