glass output class More...

#include <output.h>

Inheritance diagram for glass3::output::output:

Collaboration diagram for glass3::output::output:

Public Member Functions
	output ()
	output constructor More...

	~output ()
	output destructor More...

bool	setup (std::shared_ptr< const json::Object > config) override
	output configuration function More...

void	clear () override
	output clear function More...

void	sendToOutput (std::shared_ptr< json::Object > message) override
	output message sending function More...

bool	start () override
	work thread start function More...

bool	healthCheck () override
	output heath check function More...

void	setSiteListRequestInterval (int delay)
	Function to set the interval for requesting the site list. More...

int	getSiteListRequestInterval ()
	Function to retrieve the interval for requesting the site list. More...

void	setReportInterval (int interval)
	Function to set the interval to generate informational reports. More...

int	getReportInterval ()
	Function to retrieve the interval to generate informational reports. More...

void	setAssociator (glass3::util::iAssociator *associator)
	Function to set the associator interface pointer. More...

glass3::util::iAssociator *	getAssociator ()
	Function to get the associator interface pointer. More...

void	setPubOnExpiration (bool pub)
	Function to set the publish on expiration flag. More...

bool	getPubOnExpiration ()
	Function to retrieve the publish on expiration flag. More...

void	setImmediatePubThreshold (double threshold)
	Function to set the immediate publication threshold. More...

double	getImmediatePubThreshold ()
	Function to retrieve the immediate publication threshold. More...

std::vector< int >	getPubTimes ()
	Function to retrieve the publication times. More...

void	addPubTime (int pubTime)
	Function to add a single publication time to the list. More...

void	clearPubTimes ()
	Function to clear the publication times. More...

bool	addTrackingData (std::shared_ptr< json::Object > data)
	add tracking information to the output tracking cache More...

std::shared_ptr< const json::Object >	getTrackingData (std::string id)
	get tracking information from the output tracking cache by id More...

std::shared_ptr< const json::Object >	getNextTrackingData ()
	get tracking information from the output tracking cache More...

bool	haveTrackingData (std::shared_ptr< json::Object > data)
	check if tracking information is in output tracking cache More...

bool	haveTrackingData (std::string ID)
	check if information is in output tracking cache by id More...

bool	removeTrackingData (std::shared_ptr< const json::Object > data)
	remove tracking information from the output tracking cache More...

bool	removeTrackingData (std::string ID)
	remove tracking information from the output tracking cache by id More...

void	clearTrackingData ()
	clear output tracking cache More...

bool	isDataReady (std::shared_ptr< const json::Object > data)
	check to see if tracking information is ready for output More...

bool	isDataChanged (std::shared_ptr< const json::Object > data)
	check to see if detection data has changed More...

bool	isDataPublished (std::shared_ptr< const json::Object > data, bool ignoreVersion=true)
	check to see if tracking information has been published More...

bool	isDataFinished (std::shared_ptr< const json::Object > data)
	check to see if tracking information is finished More...

void	writeOutput (std::shared_ptr< json::Object > data)
	output writing function More...

glass3::util::WorkState	work () override
	output background work function More...

Public Member Functions inherited from glass3::util::ThreadBaseClass
	ThreadBaseClass ()
	ThreadBaseClass constructor. More...

	ThreadBaseClass (std::string threadName, int sleepTimeMS=100, int numThreads=1, int checkInterval=300)
	An advanced constructor that sets up the ThreadBaseClass with a provided thread name, sleep between work time duration, number of threads, and statsus check interval. More...

	~ThreadBaseClass ()
	ThreadBaseClass destructor. More...

virtual bool	stop ()
	work thread stop function More...

int	getNumThreads ()
	Retrieves the number of work threads. More...

void	setNumThreads (int numThreads)
	Sets the number of work threads. More...

void	setThreadHealth (bool health=true)
	Function to set thread health. More...

void	setSleepTime (int sleepTimeMS)
	Sets the time to sleep between work() calls. More...

int	getSleepTime ()
	Retrieves the time to sleep between work() calls. More...

glass3::util::ThreadState	getWorkThreadsState ()
	Function to get the work threads state. More...

void	setHealthCheckInterval (int interval)
	Function to set work threads health check interval. More...

int	getHealthCheckInterval ()
	Function to retrieve the work threads health check interval. More...

bool	getTerminate ()
	Function to retrieve whether the thread should terminate. More...

const std::string &	getThreadName ()
	Function to retrieve the name of the work threads. More...

std::time_t	getAllLastHealthy (size_t *pThreadId)
	Function to retrieve the oldest time any of the work threads last updated their health status as healthy. More...

Public Member Functions inherited from glass3::util::BaseClass
	BaseClass ()
	BaseClass constructor. More...

virtual	~BaseClass ()
	BaseClass destructor. More...

const std::shared_ptr< const json::Object >	getConfig ()

bool	getSetup ()
	Retrieves the class member boolean flag indicating whether the class has been setup, set to true if setup was successful. More...

const std::string &	getDefaultAgencyId ()
	Function to retrieve the name of the default agency id. More...

void	setDefaultAgencyId (const std::string &id)
	Function to set the name of the default agency id. More...

const std::string &	getDefaultAuthor ()
	Function to retrieve the name of the default author. More...

void	setDefaultAuthor (const std::string &author)
	Function to set the name of the default author. More...

Static Public Attributes
static constexpr int	k_iMinimumPublicationTime = 10
	The minimum time in seconds to publish an event. More...

Protected Member Functions
void	checkEventsLoop ()
	output tracking data background work function More...

virtual void	sendOutput (const std::string &type, const std::string &id, const std::string &message)=0
	Send output data. More...

virtual void	sendHeartbeat ()
	Send heartbeats. More...

Protected Member Functions inherited from glass3::util::ThreadBaseClass
void	setWorkThreadsState (glass3::util::ThreadState state)
	Function to set threads state. More...

void	workLoop ()
	ThreadBaseClass work loop function. More...

void	setLastHealthy (std::time_t now)
	Function to set the last time the work thread was healthy. More...

Additional Inherited Members
Protected Attributes inherited from glass3::util::ThreadBaseClass
std::vector< std::thread >	m_WorkThreads
	the std::vector that contains the work std::thread objects More...

std::map< std::thread::id, std::atomic< int > >	m_ThreadHealthMap
	A std::map containing the epoch times as std::atomic<double>> that each work thread was last marked as healthy, identified by the thread id. More...

Protected Attributes inherited from glass3::util::BaseClass
std::shared_ptr< const json::Object >	m_Config
	A shared pointer to the json::Object that holds the configuration. More...

std::atomic< bool >	m_bIsSetup
	the boolean flag indicating whether the class has been setup, set to true if setup was successful. More...

std::string	m_DefaultAgencyID
	A std::string containing the default agency id to use in parsing if one is not provided. More...

std::string	m_DefaultAuthor
	A std::string containing the default author to use in parsing if one is not provided. More...

Detailed Description

glass output class

The glass3 output class is a class that performs the publication tracking and translation tasks for neic-glass3.

The Output class utilizes the internal glasscore Event, Cancel, and Expire messages as defined at https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/Event.md // NOLINT https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/Cancel.md // NOLINT https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/Expire.md // NOLINT for publication tracking. The class uses a configurable set of fixed publication times to determine when to publish. These messages are passed to Output via the sendToOutput function from the iOutput interface

The output class generates the internal formats ReqHypo and ReqSiteList messages defined at https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/ReqHypo.md // NOLINT https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/ReqSiteList.md // NOLINT to request detailed event detection and site list information from glasscore via the m_Associator pointer.

The output class translates the internal glasscore Hypo, SiteList and SiteLookup messages as messages as defined at https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/Hypo.md // NOLINT https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/SiteList.md // NOLINT https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/SiteLookup.md // NOLINT detection formats messages, as defined at https://github.com/usgs/earthquake-detection-formats/tree/master/format-docs

The Output class is designed to be extended in order to define application specific output mechanisms (i.e. file output).

output inherits from the glass3::util::ThreadBaseClass class. output implements the glass3::util::iOutput interface.

Constructor & Destructor Documentation

glass3::output::output::output ( )

output constructor

The constructor for the output class. Initializes members to default values.

glass3::output::output::~output ( )

output destructor

The destructor for the output class. Stops the work thread

Member Function Documentation

void glass3::output::output::addPubTime ( int pubTime )

Function to add a single publication time to the list.

This function adds a single publication time in seconds to the list used to determine when to generate detection messages for events. An event will not generate a message if it has not changed, and will not generate a message if all publication times have passed (unless m_bPubOnExpiration is set to true)

Parameters

pubTime = An integer containing a times in seconds since initial report that events should generate detection messages

bool glass3::output::output::addTrackingData ( std::shared_ptr< json::Object > data )

add tracking information to the output tracking cache

Add the glasscore event message (used for tracking) as defined at https://github.com/usg/neic-glass3/blob/code-review/doc/internal-formats/Event.md // NOLINT to the tracking cache as the tracking information

Parameters

data	- A shared_ptr to a json::Object containing the glasscore event message used as the tracking information

Returns: Returns true if successful, false otherwise

void glass3::output::output::checkEventsLoop ( )

protected

output tracking data background work function

This function is used to manage the tracking cache, and to send request data (such as hypocenters) from the associator

void glass3::output::output::clear ( )

overridevirtual

output clear function

The clear function for the output class. Resets members to default values.

Reimplemented from glass3::util::BaseClass.

Reimplemented in glass3::fileOutput, and glass3::brokerOutput.

void glass3::output::output::clearPubTimes ( )

Function to clear the publication times.

This function clears the publication times in seconds used to determine when to generate detection messages for events.

void glass3::output::output::clearTrackingData ( )

clear output tracking cache

Clear all tracking information from the output tracking cache.

glass3::util::iAssociator * glass3::output::output::getAssociator ( )

Function to get the associator interface pointer.

This function gets the associator interface pointer used by output to communicate with the associator via the Associator::sendToAssociator() function

Returns: Returns a pointer to an object that implements the glass3::util::iAssociator interface.

double glass3::output::output::getImmediatePubThreshold ( )

Function to retrieve the immediate publication threshold.

This function retrieves the threshold used to determine whether output should generate a detection message when it receives an event message with a sufficent bayes value from the associator.

Returns: Returns a double value containing the immediate publication threshold

std::shared_ptr< const json::Object > glass3::output::output::getNextTrackingData ( )

get tracking information from the output tracking cache

Get the first ready tracking data from the cache by starting at the beginning of the cache and evaluating each tracking data with isDataReady()

Returns: Returns a shared_ptr to the json object containing the glasscore event message used for storing tracking information if found, NULL if no information found that is ready to publish.

bool glass3::output::output::getPubOnExpiration ( )

Function to retrieve the publish on expiration flag.

This function retrieves the boolean flag that indicates whether output should generate a detection message when it receives an expiration notification from the associator.

Returns: Returns a boolean flag indicating whether to generate a detection message on expiration

std::vector< int > glass3::output::output::getPubTimes ( )

Function to retrieve the publication times.

This function retrieves the publication times in seconds used to determine when to generate detection messages for events. An event will not generate a message if it has not changed, and will not generate a message if all publication times have passed (unless m_bPubOnExpiration is set to true)

Returns: Returns a std::vector of integers containing the times in seconds since initial report that events should generate detection messages

int glass3::output::output::getReportInterval ( )

Function to retrieve the interval to generate informational reports.

This function retrieves the interval in seconds between logging informationalreports on output throughput and performance

Returns: Returns an integer value containing the interval in seconds

int glass3::output::output::getSiteListRequestInterval ( )

Function to retrieve the interval for requesting the site list.

This function retrieves the interval in seconds between requesting glass core's current sitelist

Returns: Returns an integer value containing the delay in seconds

std::shared_ptr< const json::Object > glass3::output::output::getTrackingData ( std::string id )

get tracking information from the output tracking cache by id

Get the tracking information from the cache of tracking information pending for output based on a provided id

Parameters

id	- A std::string containing the id of the tracking information to retrieve from the cache

Returns: Returns a shared_ptr to the json object containing the glasscore event message used for storing tracking information if found, null otherwise

bool glass3::output::output::haveTrackingData ( std::shared_ptr< json::Object > data )

check if tracking information is in output tracking cache

Check to see if given tracking information is already in the output tracking cache.

Parameters

data	- A shared_ptr to a json::Object containing the glasscore event message used as the tracking information

Returns: Returns true if the data is in the cache, false otherwise

bool glass3::output::output::haveTrackingData ( std::string ID )

check if information is in output tracking cache by id

Check to see if tracking information is already in the output tracking cache by the given id.

Parameters

ID	- A std::string containing the id of the detection data to check.

Returns: Returns true if the data is in the cache, false otherwise

bool glass3::output::output::healthCheck ( )

overridevirtual

output heath check function

Overrides ThreadBaseClass::healthCheck to add monitoring the thread pool. Uses ThreadBaseClass::healthCheck to monitor worker threads

Returns: returns true if thread pool and worker threads are still running.

Reimplemented from glass3::util::ThreadBaseClass.

bool glass3::output::output::isDataChanged ( std::shared_ptr< const json::Object > data )

check to see if detection data has changed

Check the given dtracking information to see if it has been changed

Parameters

data	- A shared_ptr to a json::Object containing the glasscore event message used as the tracking information to check

Returns: Returns true if the tracking information is has been changed, false if not.

bool glass3::output::output::isDataFinished ( std::shared_ptr< const json::Object > data )

check to see if tracking information is finished

Check the given tracking information to see if is finished (no more publications)

Parameters

data	- A shared_ptr to a json::Object containing the glasscore event message used as the tracking information to check

Returns: Returns true if the tracking information is finished, false if not.

bool glass3::output::output::isDataPublished	(	std::shared_ptr< const json::Object >	data,
		bool	ignoreVersion = `true`
	)

check to see if tracking information has been published

Check the given tracking information to see if it has been previously published. Optionally ignore the current version when doing the check. This is used when determining whether tracking information has ever been published (i.e. when generating a retraction message)

Parameters

data	- A shared_ptr to a json::Object containing the glasscore event message used as the tracking information to check
ignoreVersion	- A boolen flag indicating whether to ignore the tracking current information version

Returns: Returns true if the tracking information is has been published, false if not.

bool glass3::output::output::isDataReady ( std::shared_ptr< const json::Object > data )

check to see if tracking information is ready for output

Check the given tracking information to see if it is ready for output

Parameters

data	- A shared_ptr to a json::Object containing the glasscore event message used as the tracking information to check

Returns: Returns true if the tracking information is ready, false if not.

bool glass3::output::output::removeTrackingData ( std::shared_ptr< const json::Object > data )

remove tracking information from the output tracking cache

Remove the provided tracking information from the output tracking cache.

Parameters

data	- A shared_ptr to a json::Object containing the glasscore event message used as the tracking information to remove

Returns: Returns true if successful, false otherwise

bool glass3::output::output::removeTrackingData ( std::string ID )

remove tracking information from the output tracking cache by id

Remove the tracking information from the output tracking cache using the given id

Parameters

ID	- A std::string containing the id of the detection data to remove.

Returns: Returns true if successful, false otherwise

void glass3::output::output::sendHeartbeat ( )

protectedvirtual

Send heartbeats.

This function is optionally used by an overriding class to implement a specific heartbeat method, i.e. to disk, memory, socket, kafka, etc.

Reimplemented in glass3::brokerOutput.

virtual void glass3::output::output::sendOutput	(	const std::string &	type,
		const std::string &	id,
		const std::string &	message
	)

protectedpure virtual

Send output data.

This pure virtual function is used to send output data. It is expected that the implementing class will override this function to implement a specific output method, i.e. to disk, memory, socket, kafka, etc.

Parameters

type	- A std::string containing the type of the message
id	- A std::string containing the id of the message
message	- A std::string containing the message

Implemented in glass3::fileOutput, and glass3::brokerOutput.

void glass3::output::output::sendToOutput ( std::shared_ptr< json::Object > message )

overridevirtual

output message sending function

The function (from glass3::util::iOutput) used by other libraries to send messages to output.

Parameters

message - A shared_ptr to a json::Object containing the message to send to output.

Implements glass3::util::iOutput.

void glass3::output::output::setAssociator ( glass3::util::iAssociator * associator )

Function to set the associator interface pointer.

This function sets the associator interface pointer used by output to communicate with the associator via the Associator::sendToAssociator() function

Parameters

associator = A pointer to an object that implements the glass3::util::iAssociator interface.

void glass3::output::output::setImmediatePubThreshold ( double threshold )

Function to set the immediate publication threshold.

This function sets the threshold used to determine whether output should generate a detection message when it receives an event message with a sufficent bayes value from the associator.

Parameters

threshold - A double value containing the immediate publication threshold

void glass3::output::output::setPubOnExpiration ( bool pub )

Function to set the publish on expiration flag.

This function sets the boolean flag that indicates whether output should generate a detection message when it receives an expiration notification from the associator.

Parameters

pub	= A boolean flag indicating whether to generate a detection message on expiration

void glass3::output::output::setReportInterval ( int interval )

Function to set the interval to generate informational reports.

This function sets the interval in seconds between logging informational reports on output throughput and performance

Parameters

interval = An integer value containing the interval in seconds

void glass3::output::output::setSiteListRequestInterval ( int delay )

Function to set the interval for requesting the site list.

This function sets the interval in seconds between requesting glass core's current site list. A negative delay indicates that the site list should not be requested

Parameters

delay = An integer value containing the delay in seconds

bool glass3::output::output::setup ( std::shared_ptr< const json::Object > config )

overridevirtual

output configuration function

The function configures the output class.

The setup() function can be called multiple times, in order to reload or update configuration information.

Parameters

config - A pointer to a json::Object containing to the configuration to use

Returns: returns true if successful.

Reimplemented from glass3::util::BaseClass.

Reimplemented in glass3::fileOutput, and glass3::brokerOutput.

bool glass3::output::output::start ( )

overridevirtual

work thread start function

Overrides ThreadBaseClass::start() to create a thread to run the checkEventsLoop() function and add the thread to ThreadBaseClass list of threads, so it can be managed

Returns: returns true if successful, false if ThreadBaseClass::start() failed.

Reimplemented from glass3::util::ThreadBaseClass.

glass3::util::WorkState glass3::output::output::work ( )

overridevirtual

output background work function

The function (from ThreadBaseClass) used to do background work. It is used to process messages from the associator, and to queue messages to be written out

Returns: This function returns glass3::util::WorkState, indicating whether the work was successful, encountered an error, or was idle (no work to perform

Implements glass3::util::ThreadBaseClass.

void glass3::output::output::writeOutput ( std::shared_ptr< json::Object > data )

output writing function

The function used to translate and generate output data

Parameters

data	- A shared_ptr to a json::Object containing the data to be output.

Member Data Documentation

constexpr int glass3::output::output::k_iMinimumPublicationTime = 10

static

The minimum time in seconds to publish an event.

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

output/include/output.h
output/src/output.cpp

Public Member Functions

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation