FastArduino  v1.8
C++ library to build fast but small Arduino/AVR projects
eeprom::QueuedWriter Class Reference

API that allows asynchronous writing to EEPROM; this can be useful when you have large amount of data to write but cannot afford to wait until all bytes have been written. More...

#include <fastarduino/eeprom.h>

Inheritance diagram for eeprom::QueuedWriter:
Collaboration diagram for eeprom::QueuedWriter:

Public Member Functions

 QueuedWriter (const QueuedWriter &)=delete
 
QueuedWriteroperator= (const QueuedWriter &)=delete
 
template<uint16_t SIZE>
 QueuedWriter (uint8_t(&buffer)[SIZE])
 Construct a QueuedWriter from a given buffer array. More...
 
template<typename T >
bool write (const T *address, const T &value)
 Write the content of value of type T to the EEPROM at address. More...
 
template<typename T >
bool write (uint16_t address, const T &value)
 Write the content of value of type T to the EEPROM at address. More...
 
template<typename T >
bool write (const T *address, const T *value, uint16_t count)
 Write value, an array of count values of type T to the EEPROM at address. More...
 
template<typename T >
bool write (uint16_t address, const T *value, uint16_t count)
 Write value, an array of count values of type T to the EEPROM at address. More...
 
bool write (const uint8_t *address, uint8_t value)
 Write one byte to the EEPROM at address. More...
 
bool write (uint16_t address, uint8_t value)
 Write one byte to the EEPROM at address. More...
 
void erase ()
 Erase the full EEPROM content. More...
 
void wait_until_done () const
 Block until all pending operations (queued in the ring buffer) are complete. More...
 
bool is_done () const
 Tell if there is no queued, nor on-going write operation.
 

Friends

struct isr_handler
 

Detailed Description

API that allows asynchronous writing to EEPROM; this can be useful when you have large amount of data to write but cannot afford to wait until all bytes have been written.

The class uses a ring buffer which array must be provided at construction time.

In order for QueueWriter to function properly, you must register a proper ISR. FastArduino provides 3 possible ISR registrations:

  • REGISTER_EEPROM_ISR() basic ISR, ensures that all queued writes get written asynchronously
  • REGISTER_EEPROM_ISR_METHOD() enhanced ISR, first ensures that all queued writes get handled and when the last byte is written, calls a back a method of a handler class
  • REGISTER_EEPROM_ISR_FUNCTION() enhanced ISR, first ensures that all queued writes get handled and when the last byte is written, calls a back a function

Basically it has the same write() and erase() methods as EEPROM class, except:

  • its methods are not static
  • methods return immediately without waiting for the operation to be finished
  • methods may return false if the operation overflows the ring buffer

Definition at line 530 of file eeprom.h.

Constructor & Destructor Documentation

◆ QueuedWriter()

template<uint16_t SIZE>
eeprom::QueuedWriter::QueuedWriter ( uint8_t(&)  buffer[SIZE])
inlineexplicit

Construct a QueuedWriter from a given buffer array.

Template Parameters
SIZEthe size of buffer; this size limits the amount of writes that can be queued and the content size of each write
Parameters
bufferthe buffer that will be used by this QueuedWriter

Definition at line 544 of file eeprom.h.

Member Function Documentation

◆ write() [1/6]

template<typename T >
bool eeprom::QueuedWriter::write ( const T *  address,
const T &  value 
)
inline

Write the content of value of type T to the EEPROM at address.

Note
Whatever T type, this method never calls its assignment operator but simply copies, byte per byte, content from local variable content to EEPROM, no T code gets executed.
Template Parameters
Tthe type of content to be written (determines the number of bytes to write)
Parameters
addressthe location to be written in EEPROM; address is typically obtained as &variable where variable is a global variable that was declared with EEMEM attribute.
valuea reference to the variable which content will be copied to EEPROM
Return values
trueif write was successful
falseif write failed, i.e. if address is outside EEPROM bounds or if the ring buffer would overflow
See also
write(uint16_t, const T&)

Definition at line 566 of file eeprom.h.

◆ write() [2/6]

template<typename T >
bool eeprom::QueuedWriter::write ( uint16_t  address,
const T &  value 
)
inline

Write the content of value of type T to the EEPROM at address.

Note
NOTE: whatever T type, this method never calls its assignment operator but simply copies, byte per byte, content from local variable content to EEPROM, no T code gets executed.
Template Parameters
Tthe type of content to be written (determines the number of bytes to write)
Parameters
addressthe location to be written in EEPROM; address is provided as an absolute location, from 0 to the maximum EEPROM size
valuea reference to the variable which content will be copied to EEPROM
Return values
trueif write was successful
falseif write failed, i.e. if address is outside EEPROM bounds or if the ring buffer would overflow
See also
write(const T*, const T&)

Definition at line 587 of file eeprom.h.

◆ write() [3/6]

template<typename T >
bool eeprom::QueuedWriter::write ( const T *  address,
const T *  value,
uint16_t  count 
)
inline

Write value, an array of count values of type T to the EEPROM at address.

Note
NOTE: whatever T type, this method never calls its assignment operator but simply copies, byte per byte, content from local variable content to EEPROM, no T code gets executed.
Template Parameters
Tthe type of content to be written (determines the number of bytes to write)
Parameters
addressthe location to be written in EEPROM; address is typically obtained as variable where variable is a global variable array that was declared with EEMEM attribute.
valuea pointer to the variable array which content will be copied to EEPROM
countthe number of items of type T to be written
Return values
trueif write was successful
falseif write failed, i.e. if address is outside EEPROM bounds or if the ring buffer would overflow
See also
write(uint16_t, const T*, uint16_t) or if the ring buffer would overflow

Definition at line 611 of file eeprom.h.

◆ write() [4/6]

template<typename T >
bool eeprom::QueuedWriter::write ( uint16_t  address,
const T *  value,
uint16_t  count 
)
inline

Write value, an array of count values of type T to the EEPROM at address.

Note
NOTE: whatever T type, this method never calls its assignment operator but simply copies, byte per byte, content from local variable content to EEPROM, no T code gets executed.
Template Parameters
Tthe type of content to be written (determines the number of bytes to write)
Parameters
addressthe location to be written in EEPROM; address is provided as an absolute location, from 0 to the maximum EEPROM size
valuea pointer to the variable array which content will be copied to EEPROM
countthe number of items of type T to be written
Return values
trueif write was successful
falseif write failed, i.e. if address is outside EEPROM bounds or if the ring buffer would overflow
See also
write(const T*, const T*, uint16_t)

Definition at line 633 of file eeprom.h.

◆ write() [5/6]

bool eeprom::QueuedWriter::write ( const uint8_t *  address,
uint8_t  value 
)
inline

Write one byte to the EEPROM at address.

Parameters
addressthe location to be written in EEPROM; address is typically obtained as &variable where variable is a global variable that was declared with EEMEM attribute.
valuethe byte value that will be written to EEPROM
Return values
trueif write was successful
falseif write failed, i.e. if address is outside EEPROM bounds or if the ring buffer would overflow
See also
write(uint16_t, uint8_t)

Definition at line 651 of file eeprom.h.

◆ write() [6/6]

bool eeprom::QueuedWriter::write ( uint16_t  address,
uint8_t  value 
)
inline

Write one byte to the EEPROM at address.

Parameters
addressthe location to be written in EEPROM; address is provided as an absolute location, from 0 to the maximum EEPROM size
valuethe byte value that will be written to EEPROM
Return values
trueif write was successful
falseif write failed, i.e. if address is outside EEPROM bounds or if the ring buffer would overflow
See also
write(const uint8_t*, uint8_t)

Definition at line 667 of file eeprom.h.

◆ erase()

void eeprom::QueuedWriter::erase ( )
inline

Erase the full EEPROM content.

Note that "erasing" means setting all EEPROM cells to 0xFF. The method will first remove any pending writes from the ring buffer, wait for any currently on-going 1-byte write operation to completem, then it will start asynchronous erase operation.

Definition at line 680 of file eeprom.h.

◆ wait_until_done()

void eeprom::QueuedWriter::wait_until_done ( ) const
inline

Block until all pending operations (queued in the ring buffer) are complete.

This can be useful if your program is about to exit but you want to first ensure that any EEPROM write operations are finished before exit (otherwise, the EEPROM content may not be as expected).

Definition at line 709 of file eeprom.h.


The documentation for this class was generated from the following file: