OpenCurves  0.9

A curve generation thread. More...

#include <plotgenerator.h>

Inheritance diagram for PlotGenerator:
PlotExpressionGenerator PlotFileLoader RealTimePlot

Public Types

enum  ControlFlag { None = 0, RelativeTime = (1 << 0) }
 Plot generation control flags. Must be set before execution. More...
 

Public Slots

void abortLoad ()
 Request loading abort.
 

Signals

void itemName (const QString &name)
 Signal the current item name. More...
 
void itemProgress (int current)
 Update progress through the current item. More...
 
void overallProgress (int current, int total)
 This signal reports overall progress. More...
 
void beginNewCurves ()
 Begin the addition of new curves via Curves::newCurve() Block notification occurs at a per PlotSource level. More...
 
void endNewCurves ()
 End notification of new curves via Curves::newCurve(). More...
 
void loadComplete (int curveCount)
 Notify completion of curve generation. More...
 

Public Member Functions

 PlotGenerator (Curves *curves)
 Instantiate the generator thread to load data into curves. More...
 
virtual ~PlotGenerator ()
 Destructor. The thread should generally be stopped before destructing.
 
const Curvescurves () const
 Access the curves model to load data into.
 
void setTimeColumn (uint number)
 Set the expected time column for all curves created by this generator. More...
 
uint timeColumn () const
 The time column value in used. More...
 
void setTimeScale (double scale)
 Set the scale factor applied to all curves created by this generator. More...
 
double timeScale () const
 Access the time scale used by this generator. More...
 
void setControlFlags (uint flags)
 Sets ControlFlag values for this generator. More...
 
void setControlFlags (uint flags, bool on)
 Set the state of subset of ControlFlag values without affecting other flags. More...
 
uint controlFlags () const
 Access the current ControlFlag values.
 
void quit ()
 Call to request the generator terminate operation.
 
virtual bool isFileLoad () const
 True if this is a file loader. More...
 

Protected Attributes

Curves_curves
 Curves data model.
 
QMutex * _dataMutex
 Data mutex.
 
uint _controlFlags
 ControlFlag values affecting generation.
 
uint _timeColumn
 Index of the time column, zero for none.
 
double _timeScale
 Time scaling factor.
 
bool _abortFlag
 Abort requested?
 

Detailed Description

A curve generation thread.

This is the base class for threads capable of generating PlotInstance data. For example, generator may loads from file.

Each curve series is added to the Curves model and new data are pushed into the back buffer of the PlotInstance. The main thread must periodically call Curves::migrateLoadingData() to move data to the main buffer and to complete data loading.

A generator should operate under the following guidelines in order to maintain thread safety:

A generator should also effect the following signals so that progress may be correctly monitored and reported on.

  • Signal overallProgress() to report coarse level progress. For example, this may be emitted for each file in a set of files to load. It is best to signal this event as soon as possible with a zero current value in order to report the total number of items to be processed.
  • Signal itemName() if possible to publish the name of the item currently being loaded. For example the file name (short version). This may be displayed in the UI.
  • Signal itemProgress() to report the progress through the current item. For example, this may be repeatedly signalled while processing a file to report how far through the file the generator has progressed. The event should raised judiciously so as to avoid overwhelming the message system.
  • Signal beginNewCurves() just prior to starting to add the PlotInstance objects from a single PlotSource.
  • Signal endNewCurves() once all curves from a PlotSource are added.
  • Signal loadComplete() once the generator has finished.

Note the generator relinquishes ownership of a PlotInstance as soon as it passes the curve to Curves::newCurve(). The PlotSource should be kept wrapped in a PlotSource::Ptr to maintain thread safety.

Note
The terms generator and loader may be used interchangeably as are curve and plot.

Member Enumeration Documentation

Plot generation control flags. Must be set before execution.

Enumerator
RelativeTime 

Use relative time based on the first sample.

Affects the PlotSource objects created by this generator.

Constructor & Destructor Documentation

PlotGenerator::PlotGenerator ( Curves curves)

Instantiate the generator thread to load data into curves.

Parameters
curvesThe data model to load into.

Member Function Documentation

void PlotGenerator::beginNewCurves ( )
signal

Begin the addition of new curves via Curves::newCurve() Block notification occurs at a per PlotSource level.

Todo:
Review the utility of this event as it came about before the Curves class.
void PlotGenerator::endNewCurves ( )
signal

End notification of new curves via Curves::newCurve().

Todo:
Review the utility of this event as it came about before the Curves class.
virtual bool PlotGenerator::isFileLoad ( ) const
inlinevirtual

True if this is a file loader.

Todo:
Make this less specific. Given the Q_OBJECT macro, this has become somewhat redundant in favour of a qobject_cast().

Reimplemented in PlotFileLoader.

void PlotGenerator::itemName ( const QString &  name)
signal

Signal the current item name.

For UI display.

Parameters
nameThe name of the current PlotSource.
void PlotGenerator::itemProgress ( int  current)
signal

Update progress through the current item.

Parameters
currentCurrent progress, ranging from 0 to 1000.
void PlotGenerator::loadComplete ( int  curveCount)
signal

Notify completion of curve generation.

Parameters
curveCountThe number of curves loaded.
void PlotGenerator::overallProgress ( int  current,
int  total 
)
signal

This signal reports overall progress.

Logically, this signal reports progress through the overall number of items to be loaded or processed. For example in the case of loading files, the total reflects the total number of files to load, while the current progress reflects the number of files which have been loaded. The file loader actually reports part progress through each file by setting the total item count to the number of files by 100.

Parameters
currentCurrent item count, with optional part progress.
totalTotal item count.
void PlotGenerator::setControlFlags ( uint  flags)

Sets ControlFlag values for this generator.

Parameters
flagsThe flag to set. Replaces existing flags.
void PlotGenerator::setControlFlags ( uint  flags,
bool  on 
)

Set the state of subset of ControlFlag values without affecting other flags.

Parameters
flagsThe ControlFlag values to modify (may be just one). Values not set are left unmodified.
onTrue to enable flags, false to disable.
void PlotGenerator::setTimeColumn ( uint  number)

Set the expected time column for all curves created by this generator.

This value is written to PlotSource objects created by this generator.

Specific implementations may support alternative time specifications.

Parameters
numberThe index of the time column, or zero for none.
void PlotGenerator::setTimeScale ( double  scale)

Set the scale factor applied to all curves created by this generator.

This value is written to PlotSource objects created by this generator.

Specific implementations may support alternative time specifications.

Parameters
scaleThe time scaling value. Must not be zero.
uint PlotGenerator::timeColumn ( ) const

The time column value in used.

See setTimeColumn().

Returns
The one-based time column index, or zero for none.
double PlotGenerator::timeScale ( ) const

Access the time scale used by this generator.

Returns
The time scale affecting generated curves.

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