Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

DataSource Class Reference

#include <DataSource.h>

Inheritance diagram for DataSource:

List of all members.


Detailed Description

abstract base class for simulator data sources

Each subclass will implement loading data from some piece of hardware or network protocol. This class is expected to be tied to a LoadDataThread (or subclass) which holds configuration settings which might be shared by multiple data sources, in particular LoadDataThread::src.

Ideally, getData() should return the most recent unprocessed data -- meaning that if you are pulling from a realtime source like a network stream, if multiple frames have arrived since the last call to getData(), you should return the most recent frame of the bunch.

If your data source provides sensor data including current output values, you should call providingOutput() for those outputs when you start being used by a LoadDataThread (e.g. setDataSourceThread() is called), and ignoringOutput() when you are no longer active (e.g. setDataSourceThread() is called with NULL). This prevents the Motion process from clobbering your readings with its own feedback.

Definition at line 35 of file DataSource.h.


Public Member Functions

 DataSource ()
 constructor
 DataSource (const DataSource &ds)
 copy constructor, just in case your subclass wants it
DataSourceoperator= (const DataSource &)
 assignment operator, just in case your subclass wants it
virtual ~DataSource ()
 destructor
virtual unsigned int nextTimestamp ()=0
 returns the simulator time of the next data segment
virtual const std::string & nextName ()=0
 returns a descriptive name of the next data segment for user feedback
virtual unsigned int getData (const char *&payload, unsigned int &payloadSize, unsigned int &timestamp, std::string &name)=0
 called to retrieve the most recent data segment, or blocking until new data is available
virtual void setFrozen (bool fr)
 called by simulator when the data source's activity changes; calls doFreeze() or doUnfreeze() as appropriate
virtual bool getFrozen () const
 returns frozen status
virtual void reset ()
 if called, indicates a request to restart/reinitialize the data source
virtual void setDataSourceThread (LoadDataThread *th)
 called by the LoadDataThread subclass, allows you to register for properties which your subclass may care about
virtual LoadDataThreadgetDataSourceThread () const
 returns the LoadDataThread using this data source
virtual void setDataSourceFramerate (float fr)
 called by LoadDataThread whenever the expected framerate changes (LoadDataThread::framerate)
virtual void setDataSourceVerbose (int v)
 called by LoadDataThread whenever the requested verbosity level changes (LoadDataThread::verbosity)

Static Public Member Functions

static void setOutputTracker (unsigned int outputs[])
 Called by simulator during initialization to tell DataSources where the array of output reference counts are stored (see providedOutputs).
static void setNeedsSensor (bool waiting)
 will be called by initialization code prior to first getData() if client code is going to block on getting the first sensor reading

Protected Member Functions

virtual void doFreeze ()
 user hook for when frozen is set to true
virtual void doUnfreeze ()
 user hook for when frozen is set to false

Static Protected Member Functions

static void providingOutput (unsigned int i)
 subclasses should call this if they provide sensor updates which will contain a measurement of the current position of output i.
static void ignoringOutput (unsigned int i)
 subclasses should call this if they used to, but will no longer, provide sensor updates containing the current position of output i.

Protected Attributes

bool frozen
 indicates that data is going to be requested "sparsely"; logged data sources should not increment with time
float framerate
int verbose
LoadDataThreadthread
 stores last call to setParent()

Static Protected Attributes

static bool requiresFirstSensor = false
 if true, indicates that client code is going to wait for sensor readings returned by getData before executing

Static Private Attributes

static unsigned int * providedOutputs = NULL
 The counts of which outputs are being provided are used so the motion process can tell if it needs to provide feedback.

Constructor & Destructor Documentation

DataSource (  )  [inline]

constructor

Definition at line 37 of file DataSource.h.

DataSource ( const DataSource ds  )  [inline]

copy constructor, just in case your subclass wants it

Definition at line 38 of file DataSource.h.

virtual ~DataSource (  )  [inline, virtual]

destructor

Definition at line 40 of file DataSource.h.


Member Function Documentation

DataSource& operator= ( const DataSource  )  [inline]

assignment operator, just in case your subclass wants it

Definition at line 39 of file DataSource.h.

virtual unsigned int nextTimestamp (  )  [pure virtual]

returns the simulator time of the next data segment

should be in the future if nothing new since last data segment, otherwise should be the timestamp of the most recent data segment (older segments are skipped), return -1U if there is no more data

See also:
timestamp argument of getData()

Implemented in CameraSource, FileSystemDataSource, CameraDriver, CreateDriver, ImageStreamDriver, and SSC32Driver.

Referenced by LoadDataThread::advanceFrame(), LoadDataThread::nextTimestamp(), LoadDataThread::runloop(), and LoadDataThread::sendHeartbeat().

virtual const std::string& nextName (  )  [pure virtual]

returns a descriptive name of the next data segment for user feedback

See also:
name argument of getData()

Implemented in CameraSource, FileSystemDataSource, CameraDriver, CreateDriver, ImageStreamDriver, and SSC32Driver.

Referenced by LoadDataThread::nextName().

virtual unsigned int getData ( const char *&  payload,
unsigned int &  payloadSize,
unsigned int &  timestamp,
std::string &  name 
) [pure virtual]

called to retrieve the most recent data segment, or blocking until new data is available

Parameters:
[out] payload on return, should point to beginning of data segment, or NULL if none available
[out] payloadSize on return, should indicate size in bytes of data segment as payload
[in] timestamp the suggested return time; if multiple samples may be taken in the interval, they should be skipped until this time
[out] timestamp on return, should contain the time at which the data arrived (real time stream) or was scheduled to be sent (log on disk)
[out] name on return, a human-readable name for the frame -- e.g. filename for a data file loaded from disk
Returns:
frame serial number, used to tell when frames from the data source have been dropped (indicated by the return value incrementing by more than one)
If no more data is available, set payload to NULL, and return the current frame (i.e. don't increment serial number).

This call should block until data is available. Other functions may be called asynchronously from other threads while in this function, see ThreadNS::Lock to implement mutual exclusion locks if needed.

The input value of timestamp is a suggestion from the user's requested framerate -- try to return the frame closest to it. If it is already past (e.g. 0 on 'advance'), return the current data! If you return a timestamp in the future, the LoadDataThread will sleep until the appropriate time.

Note that this can be called when the source is frozen, which means you should unfreeze, get the current (unread) data or block until the next data, freeze again, and return the data.

Implemented in CameraSource, FileSystemDataSource, CameraDriver, CreateDriver, ImageStreamDriver, and SSC32Driver.

Referenced by LoadDataThread::advanceFrame(), and LoadDataThread::runloop().

virtual void setFrozen ( bool  fr  )  [inline, virtual]

called by simulator when the data source's activity changes; calls doFreeze() or doUnfreeze() as appropriate

You probably don't want to override this function -- that's what doFreeze() doUnfreeze are for!

Definition at line 76 of file DataSource.h.

Referenced by LoadDataThread::plistValueChanged(), and LoadDataThread::setDataSource().

virtual bool getFrozen (  )  const [inline, virtual]

returns frozen status

Definition at line 77 of file DataSource.h.

virtual void reset (  )  [inline, virtual]

if called, indicates a request to restart/reinitialize the data source

For example, a FileSystemDataSource would go back to the beginning of its list, and a network-based source would close and reopen the connection

Definition at line 82 of file DataSource.h.

virtual void setDataSourceThread ( LoadDataThread th  )  [inline, virtual]

called by the LoadDataThread subclass, allows you to register for properties which your subclass may care about

a pointer to the LoadDataThread is passed when this is becoming the current data source; NULL will be passed when the data source is no longer being used

Reimplemented in CameraSource, FileSystemDataSource, CameraDriver, CreateDriver, ImageStreamDriver, and SSC32Driver.

Definition at line 87 of file DataSource.h.

Referenced by LoadDataThread::setDataSource(), SSC32Driver::setDataSourceThread(), ImageStreamDriver::setDataSourceThread(), FileSystemDataSource::setDataSourceThread(), and CreateDriver::setDataSourceThread().

virtual LoadDataThread* getDataSourceThread (  )  const [inline, virtual]

returns the LoadDataThread using this data source

Definition at line 89 of file DataSource.h.

virtual void setDataSourceFramerate ( float  fr  )  [inline, virtual]

called by LoadDataThread whenever the expected framerate changes (LoadDataThread::framerate)

Reimplemented in CameraSource, and FileSystemDataSource.

Definition at line 91 of file DataSource.h.

Referenced by LoadDataThread::plistValueChanged(), LoadDataThread::setDataSource(), and FileSystemDataSource::setDataSourceFramerate().

virtual void setDataSourceVerbose ( int  v  )  [inline, virtual]

called by LoadDataThread whenever the requested verbosity level changes (LoadDataThread::verbosity)

Definition at line 92 of file DataSource.h.

Referenced by LoadDataThread::plistValueChanged(), and LoadDataThread::setDataSource().

static void setOutputTracker ( unsigned int  outputs[]  )  [inline, static]

Called by simulator during initialization to tell DataSources where the array of output reference counts are stored (see providedOutputs).

This would need to point into a shared memory region if using multi-process model, hence we can't just use process-local static allocation.

Definition at line 97 of file DataSource.h.

Referenced by sim::sim().

static void setNeedsSensor ( bool  waiting  )  [inline, static]

will be called by initialization code prior to first getData() if client code is going to block on getting the first sensor reading

Definition at line 100 of file DataSource.h.

Referenced by Simulator::run().

static void providingOutput ( unsigned int  i  )  [inline, static, protected]

subclasses should call this if they provide sensor updates which will contain a measurement of the current position of output i.

Definition at line 108 of file DataSource.h.

Referenced by SSC32Driver::provideOutput(), CreateDriver::provideOutput(), and FileSystemDataSource::updateProvidingOutputs().

static void ignoringOutput ( unsigned int  i  )  [inline, static, protected]

subclasses should call this if they used to, but will no longer, provide sensor updates containing the current position of output i.

You don't need to call this if you didn't previously call providingOutput().

Definition at line 117 of file DataSource.h.

Referenced by SSC32Driver::ignoreOutput(), CreateDriver::ignoreOutput(), and FileSystemDataSource::updateProvidingOutputs().

virtual void doFreeze (  )  [inline, protected, virtual]

user hook for when frozen is set to true

Reimplemented in FileSystemDataSource.

Definition at line 129 of file DataSource.h.

Referenced by setFrozen().

virtual void doUnfreeze (  )  [inline, protected, virtual]

user hook for when frozen is set to false

Reimplemented in FileSystemDataSource.

Definition at line 130 of file DataSource.h.

Referenced by setFrozen().


Member Data Documentation

bool frozen [protected]

indicates that data is going to be requested "sparsely"; logged data sources should not increment with time

Definition at line 132 of file DataSource.h.

Referenced by FileSystemDataSource::getData(), getFrozen(), and setFrozen().

int verbose [protected]

Definition at line 134 of file DataSource.h.

Referenced by FileSystemDataSource::nextFrame(), and setDataSourceVerbose().

bool requiresFirstSensor = false [static, protected]

if true, indicates that client code is going to wait for sensor readings returned by getData before executing

Allocation defined in LoadDataThread.cc

Definition at line 139 of file DataSource.h.

Referenced by SSC32Driver::getData(), and setNeedsSensor().

unsigned int * providedOutputs = NULL [static, private]

The counts of which outputs are being provided are used so the motion process can tell if it needs to provide feedback.

Subclasses should call providingOutput() and ignoringOutput() when they start and stop providing an output. A DataSource should consider itself providing an output if it will be sending some kind of measurement of the current value of an output, and has been assigned to a LoadDataThread (i.e. setDataSourceThread() has been called and thread is non-NULL).

Allocation is found in LoadDataThread.cc to avoid file clutter (no other need for a DataSource.cc)

Definition at line 149 of file DataSource.h.

Referenced by ignoringOutput(), providingOutput(), and setOutputTracker().


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

Tekkotsu Hardware Abstraction Layer 4.0
Generated Thu Nov 22 01:01:19 2007 by Doxygen 1.5.4