Class for asynchronous publishing of events. More...

#include <PublishQueuePosixRK.h>

Public Member Functions
PublishQueuePosix &	withRamQueueSize (size_t size)
	Sets the RAM based queue size (default is 2)

size_t	getRamQueueSize () const
	Gets the size of the RAM queue.

PublishQueuePosix &	withFileQueueSize (size_t size)
	Sets the file-based queue size (default is 100)

size_t	getFileQueueSize () const
	Gets the file queue size.

PublishQueuePosix &	withDirPath (const char *dirPath)
	Sets the directory to use as the queue directory. This is required!

const char *	getDirPath () const
	Gets the directory path set using withDirPath()

PublishQueuePosix &	withPublishCompleteUserCallback (std::function< void(bool succeeded, const char eventName, const char eventData)> cb)
	Adds a callback function to call with publish is complete.

void	setup ()
	You must call this from setup() to initialize this library.

void	loop ()
	You must call the loop method from the global loop() function!

bool	publish (const char *eventName, PublishFlags flags1, PublishFlags flags2=PublishFlags())
	Overload for publishing an event.

bool	publish (const char eventName, const char data, PublishFlags flags1, PublishFlags flags2=PublishFlags())
	Overload for publishing an event.

bool	publish (const char eventName, const char data, int ttl, PublishFlags flags1, PublishFlags flags2=PublishFlags())
	Overload for publishing an event.

virtual bool	publishCommon (const char eventName, const char data, int ttl, PublishFlags flags1, PublishFlags flags2=PublishFlags())
	Common publish function. All other overloads lead here. This is a pure virtual function, implemented in subclasses.

void	writeQueueToFiles ()
	If there are events in the RAM queue, write them to files in the flash file system.

void	clearQueues ()
	Empty both the RAM and file based queues. Any queued events are discarded.

void	setPausePublishing (bool value)
	Pause or resume publishing events.

bool	getPausePublishing () const
	Gets the state of the pause publishing flag.

bool	getCanSleep () const
	Determine if it's a good time to go to sleep.

size_t	getNumEvents ()
	Gets the total number of events queued.

void	checkQueueLimits ()
	Check the queue limit, discarding events as necessary.

void	lock ()
	Lock the queue protection mutex.

bool	tryLock ()
	Attempt the queue protection mutex.

void	unlock ()
	Unlock the queue protection mutex.

Static Public Member Functions
static PublishQueuePosix &	instance ()
	Gets the singleton instance of this class.

Static Public Attributes
static const uint32_t	FILE_MAGIC = 0x31b67663
	Magic bytes store at the beginning of event files for validity checking.

static const uint8_t	FILE_VERSION = 1
	Version of the file header for events.

Protected Member Functions
	PublishQueuePosix ()
	Constructor.

virtual	~PublishQueuePosix ()
	Destructor.

	PublishQueuePosix (const PublishQueuePosix &)=delete
	This class is not copyable.

PublishQueuePosix &	operator= (const PublishQueuePosix &)=delete
	This class is not copyable.

PublishQueueEvent *	newRamEvent (const char eventName, const char eventData, PublishFlags flags)
	Allocate a new event structure in RAM.

PublishQueueEvent *	readQueueFile (int fileNum)
	Read an event from a sequentially numbered file.

void	publishCompleteCallback (bool succeeded, const char eventName, const char eventData)
	Callback for BackgroundPublishRK library.

void	stateConnectWait ()
	State handler for waiting to connect to the Particle cloud.

void	stateWait ()
	State handler for waiting to publish.

void	statePublishWait ()
	State handler for waiting for publish to complete.

Static Protected Member Functions
static void	systemEventHandler (system_event_t event, int param)
	system event handler, used to detect reset events

Protected Attributes
SequentialFile	fileQueue
	SequentialFileRK library object for maintaining the queue of files on the POSIX file system.

size_t	ramQueueSize = 2
	size of the queue in RAM

size_t	fileQueueSize = 100
	size of the queue on the flash file system

os_mutex_recursive_t	mutex
	mutex for protecting the queue

std::deque< PublishQueueEvent * >	ramQueue
	Queue in RAM.

PublishQueueEvent *	curEvent = 0
	Current event being published.

int	curFileNum = 0
	Current file number being published (0 if from RAM queue)

unsigned long	stateTime = 0
	millis() value when entering the state, used for stateWait

unsigned long	durationMs = 0
	how long to wait before publishing in milliseconds, used in stateWait

bool	publishComplete = false
	true if the publish has completed (successfully or not)

bool	publishSuccess = false
	true if the publish succeeded

bool	pausePublishing = false
	flag to pause publishing (used from automated test)

bool	canSleep = false
	returns true if this is a good time to go to sleep

unsigned long	waitAfterConnect = 2000
	time to wait after Particle.connected() before publishing

unsigned long	waitBetweenPublish = 1000
	how long to wait in milliseconds between publishes

unsigned long	waitAfterFailure = 30000
	how long to wait after failing to publish before trying again

std::function< void(bool succeeded, const char eventName, const char eventData)>	publishCompleteUserCallback = 0
	User callback for publish complete.

std::function< void(PublishQueuePosix &)>	stateHandler = 0
	state handler (stateConnectWait, stateWait, etc).

Static Protected Attributes
static PublishQueuePosix *	_instance
	singleton instance of this class

Detailed Description

Class for asynchronous publishing of events.

Constructor & Destructor Documentation

◆ PublishQueuePosix()

PublishQueuePosix::PublishQueuePosix ( )

protected

Constructor.

This class is a singleton; you never create one of these directly. Use PublishQueuePosix::instance() to get the singleton instance.

◆ ~PublishQueuePosix()

PublishQueuePosix::~PublishQueuePosix ( )

protectedvirtual

Destructor.

This class is never deleted; once the singleton is created it cannot be destroyed.

Member Function Documentation

◆ checkQueueLimits()

void PublishQueuePosix::checkQueueLimits ( )

Check the queue limit, discarding events as necessary.

When the RAM queue exceeds the limit, all events are moved into files.

◆ getCanSleep()

bool PublishQueuePosix::getCanSleep ( ) const

inline

Determine if it's a good time to go to sleep.

If a publish is not in progress and the queue is empty, returns true.

If pausePublishing is true, then return true if either the current publish has completed, or not cloud connected.

◆ getDirPath()

const char * PublishQueuePosix::getDirPath ( ) const

inline

Gets the directory path set using withDirPath()

The returned path will not end with a slash.

◆ getNumEvents()

size_t PublishQueuePosix::getNumEvents ( )

Gets the total number of events queued.

This is the number of events in the RAM-based queue and the file-based queue. This operation is fast; the file queue length is stored in RAM, so this command does not need to access the file system.

If an event is currently being sent, the result includes this event.

◆ instance()

PublishQueuePosix & PublishQueuePosix::instance ( )

static

Gets the singleton instance of this class.

You cannot construct a PublishQueuePosix object as a global variable, stack variable, or with new. You can only request the singleton instance.

◆ lock()

void PublishQueuePosix::lock ( )

inline

Lock the queue protection mutex.

This is done internally; you probably won't need to call this yourself. It needs to be public for the WITH_LOCK() macro to work properly.

◆ newRamEvent()

PublishQueueEvent * PublishQueuePosix::newRamEvent	(	const char *	eventName,
		const char *	eventData,
		PublishFlags	flags
	)

protected

Allocate a new event structure in RAM.

The PublishEventQueue structure contains a header and is variably sized for the eventData.

May return NULL if eventName or eventData are invalid (too long) or out of memory.

You must delete the result from this method when you are done using it.

◆ publish() [1/3]

bool PublishQueuePosix::publish	(	const char *	eventName,
		const char *	data,
		int	ttl,
		PublishFlags	flags1,
		PublishFlags	flags2 = `PublishFlags()`
	)

inline

Overload for publishing an event.

Parameters

eventName	The name of the event (63 character maximum).
data	The event data (255 bytes maximum, 622 bytes in system firmware 0.8.0-rc.4 and later).
ttl	The time-to-live value. If not specified in one of the other overloads, the value 60 is used. However, the ttl is ignored by the cloud, so it doesn't matter what you set it to. Essentially all events are discarded immediately if not subscribed to so they essentially have a ttl of 0.
flags1	Normally PRIVATE. You can also use PUBLIC, but one or the other must be specified.
flags2	(optional) You can use NO_ACK or WITH_ACK if desired.

Returns: true if the event was queued or false if it was not.

This function almost always returns true. If you queue more events than fit in the buffer the oldest (sometimes second oldest) is discarded.

◆ publish() [2/3]

bool PublishQueuePosix::publish	(	const char *	eventName,
		const char *	data,
		PublishFlags	flags1,
		PublishFlags	flags2 = `PublishFlags()`
	)

inline

Overload for publishing an event.

Parameters

eventName	The name of the event (63 character maximum).
data	The event data (255 bytes maximum, 622 bytes in system firmware 0.8.0-rc.4 and later).
flags1	Normally PRIVATE. You can also use PUBLIC, but one or the other must be specified.
flags2	(optional) You can use NO_ACK or WITH_ACK if desired.

Returns: true if the event was queued or false if it was not.

This function almost always returns true. If you queue more events than fit in the buffer the oldest (sometimes second oldest) is discarded.

◆ publish() [3/3]

bool PublishQueuePosix::publish	(	const char *	eventName,
		PublishFlags	flags1,
		PublishFlags	flags2 = `PublishFlags()`
	)

inline

Overload for publishing an event.

Parameters

eventName	The name of the event (63 character maximum).
flags1	Normally PRIVATE. You can also use PUBLIC, but one or the other must be specified.
flags2	(optional) You can use NO_ACK or WITH_ACK if desired.

Returns: true if the event was queued or false if it was not.

This function almost always returns true. If you queue more events than fit in the buffer the oldest (sometimes second oldest) is discarded.

◆ publishCommon()

bool PublishQueuePosix::publishCommon	(	const char *	eventName,
		const char *	data,
		int	ttl,
		PublishFlags	flags1,
		PublishFlags	flags2 = `PublishFlags()`
	)

virtual

Common publish function. All other overloads lead here. This is a pure virtual function, implemented in subclasses.

Parameters

eventName	The name of the event (63 character maximum).
data	The event data (255 bytes maximum, 622 bytes in system firmware 0.8.0-rc.4 and later).
ttl	The time-to-live value. If not specified in one of the other overloads, the value 60 is used. However, the ttl is ignored by the cloud, so it doesn't matter what you set it to. Essentially all events are discarded immediately if not subscribed to so they essentially have a ttl of 0.
flags1	Normally PRIVATE. You can also use PUBLIC, but one or the other must be specified.
flags2	(optional) You can use NO_ACK or WITH_ACK if desired.

Returns: true if the event was queued or false if it was not.

This function almost always returns true. If you queue more events than fit in the buffer the oldest (sometimes second oldest) is discarded.

◆ readQueueFile()

PublishQueueEvent * PublishQueuePosix::readQueueFile ( int fileNum )

protected

Read an event from a sequentially numbered file.

Parameters

fileNum The file number to read

May return NULL if file does not exist, or out of memory.

You must delete the result from this method when you are done using it.

◆ setPausePublishing()

void PublishQueuePosix::setPausePublishing ( bool value )

Pause or resume publishing events.

Parameters

value The value to set, true = pause, false = normal operation

If called while a publish is in progress, that publish will still proceed, but the next event (if any) will not be attempted.

This is used by the automated test tool; you probably won't need to manually manage this under normal circumstances.

◆ stateConnectWait()

void PublishQueuePosix::stateConnectWait ( )

protected

State handler for waiting to connect to the Particle cloud.

Next state: stateWait

◆ statePublishWait()

void PublishQueuePosix::statePublishWait ( )

protected

State handler for waiting for publish to complete.

Next state: stateWait

◆ stateWait()

void PublishQueuePosix::stateWait ( )

protected

State handler for waiting to publish.

stateTime and durationMs determine whether to stay in this state waiting, or whether to publish and go into statePublishWait.

Next state: statePublishWait or stateConnectWait

◆ withDirPath()

PublishQueuePosix & PublishQueuePosix::withDirPath ( const char * dirPath )

inline

Sets the directory to use as the queue directory. This is required!

Parameters

dirPath the pathname, Unix-style with / as the directory separator.

Typically you create your queue either at the top level ("/myqueue") or in /usr ("/usr/myqueue"). The directory will be created if necessary, however only one level of directory will be created. The parent must already exist.

The dirPath can end with a slash or not, but if you include it, it will be removed.

You must call this as you cannot use the root directory as a queue!

◆ withFileQueueSize()

PublishQueuePosix & PublishQueuePosix::withFileQueueSize ( size_t size )

Sets the file-based queue size (default is 100)

Parameters

size	The maximum number of files to store (one event per file)

If you exceed this number of events, the oldest event is discarded.

◆ withPublishCompleteUserCallback()

PublishQueuePosix & PublishQueuePosix::withPublishCompleteUserCallback ( std::function< void(bool succeeded, const char *eventName, const char *eventData)> cb )

inline

Adds a callback function to call with publish is complete.

Parameters

cb	Callback function or C++ lambda.

Returns: PublishQueuePosix&

The callback has this prototype and can be a function or a C++11 lambda, which allows the callback to be a class method.

void callback(bool succeeded, const char *eventName, const char *eventData)

The parameters are:

succeeded: true if the publish succeeded or false if faled
eventName: The original event name that was published (a copy of it, not the original pointer)
eventData: The original event data

Note that this callback will be called from the background thread used for publishing. You should not perform any lengthy operations and you should avoid using large amounts of stack space during this callback.

◆ withRamQueueSize()

PublishQueuePosix & PublishQueuePosix::withRamQueueSize ( size_t size )

Sets the RAM based queue size (default is 2)

Parameters

size	The size to set (can be 0, default is 2)

You can set this to 0 and the events will be stored on the flash file system immediately. This is the best option if the events must not be lost in the event of a sudden reboot.

It's more efficient to have a small RAM-based queue and it eliminates flash wear. Make sure you set the size larger than the maximum number of events you plan to send out in bursts, as if you exceed the RAM queue size, all outstanding events will be moved to files.

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

src/PublishQueuePosixRK.h
src/PublishQueuePosixRK.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PublishQueuePosix()

◆ ~PublishQueuePosix()

Member Function Documentation

◆ checkQueueLimits()

◆ getCanSleep()

◆ getDirPath()

◆ getNumEvents()

◆ instance()

◆ lock()

◆ newRamEvent()

◆ publish() [1/3]

◆ publish() [2/3]

◆ publish() [3/3]

◆ publishCommon()

◆ readQueueFile()

◆ setPausePublishing()

◆ stateConnectWait()

◆ statePublishWait()

◆ stateWait()

◆ withDirPath()

◆ withFileQueueSize()

◆ withPublishCompleteUserCallback()

◆ withRamQueueSize()