JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::ThreadedAnalyticsDestination Class Referenceabstract

A base class for dispatching analytics events on a dedicated thread. More...

#include <juce_ThreadedAnalyticsDestination.h>

Inheritance diagram for juce::ThreadedAnalyticsDestination:
Collaboration diagram for juce::ThreadedAnalyticsDestination:

Classes

struct  EventDispatcher
 

Public Member Functions

 ThreadedAnalyticsDestination (const String &threadName="Analytics thread")
 Creates a ThreadedAnalyticsDestination. More...
 
 ~ThreadedAnalyticsDestination () override
 Destructor. More...
 
virtual int getMaximumBatchSize ()=0
 Override this method to provide the maximum batch size you can handle in your subclass. More...
 
virtual bool logBatchedEvents (const Array< AnalyticsEvent > &events)=0
 This method will be called periodically on the analytics thread. More...
 
void logEvent (const AnalyticsEvent &event) override final
 Adds an event to the queue, which will ultimately be submitted to logBatchedEvents. More...
 
void setBatchPeriod (int newSubmissionPeriodMilliseconds)
 Call this to set the period between logBatchedEvents invocations. More...
 
virtual void stopLoggingEvents ()=0
 You must always call stopAnalyticsThread in the destructor of your subclass (or before then) to give the analytics thread time to shut down. More...
 

Protected Member Functions

void startAnalyticsThread (int initialBatchPeriodMilliseconds)
 Starts the analytics thread, with an initial event batching period. More...
 
void stopAnalyticsThread (int timeoutMilliseconds)
 Triggers the shutdown of the analytics thread. More...
 

Private Member Functions

virtual void restoreUnloggedEvents (std::deque< AnalyticsEvent > &restoredEventQueue)=0
 The counterpart to saveUnloggedEvents. More...
 
virtual void saveUnloggedEvents (const std::deque< AnalyticsEvent > &eventsToSave)=0
 This method will be called when the analytics thread is shut down, giving you the chance to save any analytics events that could not be logged. More...
 

Private Attributes

const String destinationName
 
EventDispatcher dispatcher
 

Detailed Description

A base class for dispatching analytics events on a dedicated thread.

This class is particularly useful for sending analytics events to a web server without blocking the message thread. It can also save (and restore) events that were not dispatched so no information is lost when an internet connection is absent or something else prevents successful logging.

Once startAnalyticsThread is called the logBatchedEvents method is periodically invoked on an analytics thread, with the period determined by calls to setBatchPeriod. Here events are grouped together into batches, with the maximum batch size set by the implementation of getMaximumBatchSize.

It's important to call stopAnalyticsThread in the destructor of your subclass (or before then) to give the analytics thread time to shut down. Calling stopAnalyticsThread will, in turn, call stopLoggingEvents, which you should use to terminate the currently running logBatchedEvents call.

See also
Analytics, AnalyticsDestination, AnalyticsDestination::AnalyticsEvent

{Analytics}

Constructor & Destructor Documentation

◆ ThreadedAnalyticsDestination()

juce::ThreadedAnalyticsDestination::ThreadedAnalyticsDestination ( const String threadName = "Analytics thread")

Creates a ThreadedAnalyticsDestination.

Parameters
threadNameused to identify the analytics thread in debug builds

◆ ~ThreadedAnalyticsDestination()

juce::ThreadedAnalyticsDestination::~ThreadedAnalyticsDestination ( )
override

Destructor.

Member Function Documentation

◆ getMaximumBatchSize()

virtual int juce::ThreadedAnalyticsDestination::getMaximumBatchSize ( )
pure virtual

Override this method to provide the maximum batch size you can handle in your subclass.

Calls to logBatchedEvents will contain no more than this number of events.

◆ logBatchedEvents()

virtual bool juce::ThreadedAnalyticsDestination::logBatchedEvents ( const Array< AnalyticsEvent > &  events)
pure virtual

This method will be called periodically on the analytics thread.

If this method returns false then the subsequent call of this function will contain the same events as previous call, plus any new events that have been generated in the period between calls. The order of events will not be changed. This allows you to retry logging events until they are logged successfully.

Parameters
eventsa list of events to be logged
Returns
if the events were successfully logged

◆ logEvent()

void juce::ThreadedAnalyticsDestination::logEvent ( const AnalyticsEvent event)
finaloverridevirtual

Adds an event to the queue, which will ultimately be submitted to logBatchedEvents.

This method is thread safe.

Parameters
eventthe analytics event to add to the queue

Implements juce::AnalyticsDestination.

◆ restoreUnloggedEvents()

virtual void juce::ThreadedAnalyticsDestination::restoreUnloggedEvents ( std::deque< AnalyticsEvent > &  restoredEventQueue)
privatepure virtual

The counterpart to saveUnloggedEvents.

Events added to the event queue provided by this method will be the first events supplied to logBatchedEvents calls. Use this method to restore any unlogged events previously stored in a call to saveUnloggedEvents.

This method is called on the analytics thread.

Parameters
restoredEventQueueplace restored events into this queue
See also
saveUnloggedEvents

◆ saveUnloggedEvents()

virtual void juce::ThreadedAnalyticsDestination::saveUnloggedEvents ( const std::deque< AnalyticsEvent > &  eventsToSave)
privatepure virtual

This method will be called when the analytics thread is shut down, giving you the chance to save any analytics events that could not be logged.

Once saved these events can be put back into the queue of events when the ThreadedAnalyticsDestination is recreated via restoreUnloggedEvents.

This method should return as quickly as possible, as both stopLoggingEvents and this method need to complete inside the timeout set in stopAnalyticsThread.

Parameters
eventsToSavethe events that could not be logged
See also
stopAnalyticsThread, stopLoggingEvents, restoreUnloggedEvents

◆ setBatchPeriod()

void juce::ThreadedAnalyticsDestination::setBatchPeriod ( int  newSubmissionPeriodMilliseconds)

Call this to set the period between logBatchedEvents invocations.

This method is thread safe and can be used to implements things like exponential backoff in logBatchedEvents calls.

Parameters
newSubmissionPeriodMillisecondsthe new submission period to use in milliseconds

◆ startAnalyticsThread()

void juce::ThreadedAnalyticsDestination::startAnalyticsThread ( int  initialBatchPeriodMilliseconds)
protected

Starts the analytics thread, with an initial event batching period.

Parameters
initialBatchPeriodMillisecondsthe initial event batching period in milliseconds

◆ stopAnalyticsThread()

void juce::ThreadedAnalyticsDestination::stopAnalyticsThread ( int  timeoutMilliseconds)
protected

Triggers the shutdown of the analytics thread.

You must call this method in the destructor of your subclass (or before then) to give the analytics thread time to shut down.

This method invokes stopLoggingEvents and you should ensure that both the analytics thread and a call to saveUnloggedEvents are able to finish before the supplied timeout. This timeout is important because on platforms like iOS an app is killed if it takes too long to shut down.

Parameters
timeoutMillisecondsthe number of milliseconds before the analytics thread is forcibly terminated

◆ stopLoggingEvents()

virtual void juce::ThreadedAnalyticsDestination::stopLoggingEvents ( )
pure virtual

You must always call stopAnalyticsThread in the destructor of your subclass (or before then) to give the analytics thread time to shut down.

Calling stopAnalyticsThread triggers a call to this method. At this point you are guaranteed that logBatchedEvents has been called for the last time and you should make sure that the current call to logBatchedEvents finishes as quickly as possible. This method and a subsequent call to saveUnloggedEvents must both complete before the timeout supplied to stopAnalyticsThread.

In a normal use case stopLoggingEvents will be called on the message thread from the destructor of your ThreadedAnalyticsDestination subclass, and must stop the logBatchedEvents method which is running on the analytics thread.

See also
stopAnalyticsThread

Member Data Documentation

◆ destinationName

const String juce::ThreadedAnalyticsDestination::destinationName
private

◆ dispatcher

EventDispatcher juce::ThreadedAnalyticsDestination::dispatcher
private

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