Interface for a Thread for buffering samples. More...

#include <SampleThread.h>

Inheritance diagram for nidas::core::SampleThread:

Public Types
enum	runStatus { RUN_CANCELED = -1, RUN_OK = 0, NOT_RUNNING = 1, RUN_EXCEPTION = 2 }
	Values that can be returned by run method. More...

enum	SchedPolicy { NU_THREAD_OTHER =SCHED_OTHER, NU_THREAD_FIFO =SCHED_FIFO, NU_THREAD_RR =SCHED_RR }

Public Member Functions
	SampleThread (const std::string &name)

virtual	~SampleThread ()

virtual void	flush ()=0 throw ()
	Both SampleClient and SampleSource have a flush() method. More...

virtual void	setKeepStats (bool val)=0

virtual bool	getKeepStats () const =0

virtual size_t	size () const =0
	Number of samples that have not be distributed. More...

virtual void	setLengthSecs (float val)=0

virtual float	getLengthSecs () const =0

virtual void	setHeapMax (size_t val)=0
	Set the maximum amount of heap memory to use for sorting samples. More...

virtual size_t	getHeapMax () const =0

virtual size_t	getHeapSize () const =0
	Get the current amount of heap being used for sorting. More...

virtual void	setHeapBlock (bool val)=0

virtual bool	getHeapBlock () const =0

virtual size_t	getNumDiscardedSamples () const =0
	Number of samples discarded because of _heapSize > _heapMax and heapBlock == true. More...

virtual size_t	getNumFutureSamples () const =0
	Number of samples discarded because their timetags were in the future. More...

virtual void	setRealTime (bool val)=0
	Is this thread running in real-time, meaning is it handling recently sampled data? If so then we can screen for bad sample time-tags by checking against the system clock, which is trusted. More...

virtual bool	getRealTime () const =0

virtual void	setLateSampleCacheSize (unsigned int val)=0

virtual unsigned int	getLateSampleCacheSize () const =0

virtual void	start () throw (Exception)
	Start the thread running, meaning execute the run method in a separate thread. More...

virtual int	join () throw (Exception)
	The calling thread joins this thread, waiting until the thread finishes, which means either that the run() method returned, the thread called pthread_exit() or the thread was cancelled. More...

virtual void	kill (int sig) throw (Exception)
	Send a signal to this thread. More...

virtual void	cancel () throw (Exception)
	Cancel this thread. More...

virtual void	interrupt ()
	Interrupt this thread. More...

virtual bool	isInterrupted () const
	Return true when this thread has been interrupted. More...

virtual bool	isRunning () const
	Is this thread running? More...

virtual bool	isJoined () const
	Has this thread been joined? More...

virtual bool	isDetached () const
	Is this a detached thread. More...

bool	isCancelEnabled () const
	Return true if the cancel state of this thread is PTHREAD_CANCEL_ENABLE. More...

bool	isCancelDeferred () const
	Return true if the cancel type of this thread is PTHREAD_CANCEL_DEFERRED. More...

const std::string &	getName () const throw ()
	Return the name of this thread. More...

const std::string &	getFullName () throw ()
	Return a name with a bunch of descriptive fields, specifying whether it is detached, the real-time priority, etc. More...

bool	setRealTimeRoundRobinPriority (int val) throw (Exception)

bool	setRealTimeFIFOPriority (int val) throw (Exception)

bool	setNonRealTimePriority () throw (Exception)

void	setThreadScheduler (enum SchedPolicy policy, int priority) throw (Exception)

void	blockSignal (int)
	Block a signal in this thread. More...

void	unblockSignal (int)
	Install a signal handler and unblock the signal. More...

virtual int	run ()=0 throw (Exception)
	The method which will run in its own thread. More...

virtual bool	receive (const Sample *s)=0 throw ()
	Method called to pass a sample to this client. More...

virtual SampleSource *	getRawSampleSource ()=0
	Several objects in NIDAS can be both a SampleSource of raw Samples and processed Samples. More...

virtual SampleSource *	getProcessedSampleSource ()=0
	Several objects in NIDAS can be both a SampleSource of raw Samples and processed Samples. More...

virtual void	addSampleTag (const SampleTag *)=0 throw (nidas::util::InvalidParameterException)
	Add a SampleTag to this SampleSource. More...

virtual void	removeSampleTag (const SampleTag *)=0 throw ()

virtual std::list< const SampleTag * >	getSampleTags () const =0
	What SampleTags am I a SampleSource for? More...

virtual SampleTagIterator	getSampleTagIterator () const =0

virtual void	addSampleClient (SampleClient *c)=0 throw ()
	Add a SampleClient of all Samples to this SampleSource. More...

virtual void	removeSampleClient (SampleClient *c)=0 throw ()
	Remove a SampleClient from this SampleSource. More...

virtual void	addSampleClientForTag (SampleClient c, const SampleTag )=0 throw ()
	Add a SampleClient to this SampleSource. More...

virtual void	removeSampleClientForTag (SampleClient c, const SampleTag )=0 throw ()
	Remove a SampleClient for a given SampleTag from this SampleSource. More...

virtual int	getClientCount () const =0 throw ()
	How many SampleClients are currently in my list. More...

virtual const SampleStats &	getSampleStats () const =0

Static Public Member Functions
static Thread *	currentThread ()
	Return the thread object for the current thread. More...

static pthread_t	currentThreadId ()

static Thread *	lookupThread (pthread_t id)

static const std::string &	currentName ()
	Convenience routine to return the name for the current thread, or a string indicating that the name of the thread is unknown. More...

static std::string	getPolicyString (int policy)
	Convenience function to return a string for the given scheduler policy: "Non-RT", "RT:FIFO", "RT:RR" or "RT:Unknown". More...

static int	test (int argc, char **argv)
	a test method. More...

Protected Member Functions
void	setCancelEnabled (bool val)
	Set the cancel state for this thread - false means cancel requests are ignored. More...

void	setCancelDeferred (bool val)
	Set the cancel type for this thread. More...

pthread_t	getId () const

void	testCancel () const
	Check if we have been cancelled. More...

virtual bool	amInterrupted () const
	Call testCancel, and return true when this thread has been interrupted. More...

Detailed Description

Interface for a Thread for buffering samples.

Samples are received by the SampleClient side of this interface. The SampleSource side runs in a separate thread, sending out samples when they are ready. This interface can be inplemented by a SampleSorter if time-sorting is desired, or by a simple FIFO buffer. Either implementation provides thread separation where the thread using the SampleClient side could run as a high-priority real-time thread, doing time-critical time-tagging and acquisition, and the SampleSource runs as a normal-priority thread, doing less time-critical things like post-processing, or sample archiving.

Member Enumeration Documentation

enum nidas::util::Thread::runStatus

inherited

Values that can be returned by run method.

User can define other values greater than RUN_EXCEPTION. These values are then returned by int join(). Note that PTHREAD_CANCELLED is -1

Enumerator
RUN_CANCELED
RUN_OK
NOT_RUNNING
RUN_EXCEPTION

enum nidas::util::Thread::SchedPolicy

inherited

Enumerator
NU_THREAD_OTHER
NU_THREAD_FIFO
NU_THREAD_RR

Constructor & Destructor Documentation

nidas::core::SampleThread::SampleThread ( const std::string & name )

inline

virtual nidas::core::SampleThread::~SampleThread ( )

inlinevirtual

Member Function Documentation

virtual void nidas::core::SampleSource::addSampleClient	(	SampleClient *	c	)
throw	(
	)

pure virtualinherited

Add a SampleClient of all Samples to this SampleSource.

The pointer to the SampleClient must remain valid, until after it is removed.

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::SampleIOProcessor, nidas::core::NearestResamplerAtRate, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::StatisticsCruncher, nidas::dynld::raf::SyncRecordGenerator, nidas::core::SampleAverager, nidas::core::NearestResampler, and nidas::core::SampleSourceSupport.

Referenced by nidas::dynld::SampleProcessor::connect(), nidas::core::SampleArchiver::connect(), nidas::core::SamplePipeline::connect(), nidas::dynld::SampleProcessor::connectSource(), nidas::core::SampleArchiver::connectSource(), DataDump::run(), and DataStats::run().

virtual void nidas::core::SampleSource::addSampleClientForTag	(	SampleClient *	c,
		const SampleTag *
	)
throw	(
	)

pure virtualinherited

Add a SampleClient to this SampleSource.

The pointer to the SampleClient must remain valid, until after it is removed.

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::SampleIOProcessor, nidas::core::NearestResamplerAtRate, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::StatisticsCruncher, nidas::core::SampleAverager, nidas::core::NearestResampler, nidas::dynld::raf::SyncRecordGenerator, and nidas::core::SampleSourceSupport.

virtual void nidas::core::SampleSource::addSampleTag	(	const SampleTag *	)
throw	(	nidas::util::InvalidParameterException
	)

pure virtualinherited

bool Runnable::amInterrupted ( ) const

protectedvirtualinherited

Call testCancel, and return true when this thread has been interrupted.

This is protected because it should only called within the run method of the thread.

Referenced by nidas::core::SampleOutputRequestThread::run(), nidas::core::Looper::run(), nidas::dynld::isff::GOESOutput::run(), nidas::core::DSMServerStat::run(), and nidas::util::Thread::test().

void Thread::blockSignal ( int sig )

inherited

Block a signal in this thread.

This method is usually called before this Thread has started. If this Thread is currently running, then this method is only effective if called from this Thread, i.e. from its own run() method.

Because SIGINT, SIGTERM and SIGHUP are typically caught in the main thread, they are blocked by default in a Thread. Call unblockSignal(sig) if you want to catch them in a Thread.

References nidas::util::Thread::_blockedSignals, nidas::util::Thread::_unblockedSignals, nidas::util::Thread::currentThread(), nidas::util::Thread::isRunning(), and nidas::util::Thread::thr_add_sig().

Referenced by nidas::dynld::UDPSampleOutput::ConnectionMonitor::ConnectionMonitor(), nidas::core::ServerSocket::ConnectionThread::ConnectionThread(), nidas::core::DerivedDataReader::DerivedDataReader(), nidas::util::McSocketListener::McSocketListener(), nidas::util::McSocketMulticaster< SocketTT >::McSocketMulticaster(), nidas::core::SensorHandler::SensorHandler(), nidas::core::SensorOpener::SensorOpener(), nidas::util::Thread::test(), nidas::dynld::RawSampleService::Worker::Worker(), nidas::core::XmlRpcThread::XmlRpcThread(), and nidas::dynld::UDPSampleOutput::XMLSocketListener::XMLSocketListener().

void Thread::cancel	(		)
throw	(	Exception
	)

virtualinherited

Cancel this thread.

References nidas::util::Thread::_id, nidas::util::Thread::_mutex, nidas::util::Exception::errnoToString(), and nidas::util::Thread::getName().

Referenced by nidas::core::DSMService::cancel(), nidas::dynld::isff::GOESOutput::cancelThread(), nidas::core::DerivedDataReader::deleteInstance(), and nidas::core::DSMEngine::joinDataThreads().

static const std::string& nidas::util::Thread::currentName ( )

inlinestaticinherited

Convenience routine to return the name for the current thread, or a string indicating that the name of the thread is unknown.

References nidas::util::Thread::currentThread(), nidas::util::Thread::getName(), and nidas::util::Thread::unknownName.

Referenced by nidas::util::Logger::msg_locked().

Thread * Thread::currentThread ( )

staticinherited

Return the thread object for the current thread.

Returns null if not found.

Referenced by nidas::util::Thread::blockSignal(), nidas::util::Thread::currentName(), and nidas::util::Thread::unblockSignal().

pthread_t Thread::currentThreadId ( )

staticinherited

Referenced by nidas::core::Looper::removeClient().

virtual void nidas::core::SampleThread::flush	(	)
throw	(
	)

pure virtual

Both SampleClient and SampleSource have a flush() method.

Redeclaring it here as pure virtual removes the ambiguity.

Implements nidas::core::SampleClient.

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::flush().

virtual int nidas::core::SampleSource::getClientCount	(	)	const
throw	(
	)

pure virtualinherited

How many SampleClients are currently in my list.

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::SampleIOProcessor, nidas::core::NearestResamplerAtRate, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::StatisticsCruncher, nidas::core::SampleAverager, nidas::core::NearestResampler, nidas::dynld::raf::SyncRecordGenerator, and nidas::core::SampleSourceSupport.

Referenced by nidas::core::SamplePipeline::getClientCount().

const std::string & Thread::getFullName	(	)
throw	(
	)

inherited

Return a name with a bunch of descriptive fields, specifying whether it is detached, the real-time priority, etc.

References nidas::util::Thread::_fullname.

Referenced by nidas::util::Thread::pRun(), nidas::util::Thread::test(), nidas::util::Thread::thr_cleanup(), and nidas::util::Thread::thr_cleanup_delete().

virtual bool nidas::core::SampleThread::getHeapBlock ( ) const

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

virtual size_t nidas::core::SampleThread::getHeapMax ( ) const

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::getSorterNumProcBytesMax(), nidas::core::SamplePipeline::getSorterNumRawBytesMax(), nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

virtual size_t nidas::core::SampleThread::getHeapSize ( ) const

pure virtual

Get the current amount of heap being used for sorting.

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::getSorterNumProcBytes(), and nidas::core::SamplePipeline::getSorterNumRawBytes().

pthread_t nidas::util::Thread::getId ( ) const

inlineprotectedinherited

References nidas::util::Thread::_id, and nidas::util::Thread::_mutex.

Referenced by nidas::util::Thread::isJoined(), nidas::util::Thread::join(), nidas::util::Thread::pRun(), and nidas::core::Looper::removeClient().

virtual bool nidas::core::SampleThread::getKeepStats ( ) const

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

virtual unsigned int nidas::core::SampleThread::getLateSampleCacheSize ( ) const

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

virtual float nidas::core::SampleThread::getLengthSecs ( ) const

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

const std::string & Thread::getName	(	)	const
throw	(
	)

inherited

Return the name of this thread.

References nidas::util::Thread::_name.

virtual size_t nidas::core::SampleThread::getNumDiscardedSamples ( ) const

pure virtual

Number of samples discarded because of _heapSize > _heapMax and heapBlock == true.

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::getNumDiscardedProcSamples(), and nidas::core::SamplePipeline::getNumDiscardedRawSamples().

virtual size_t nidas::core::SampleThread::getNumFutureSamples ( ) const

pure virtual

Number of samples discarded because their timetags were in the future.

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::getNumFutureProcSamples(), and nidas::core::SamplePipeline::getNumFutureRawSamples().

string Thread::getPolicyString ( int policy )

staticinherited

Convenience function to return a string for the given scheduler policy: "Non-RT", "RT:FIFO", "RT:RR" or "RT:Unknown".

References nidas::util::Thread::NU_THREAD_FIFO, nidas::util::Thread::NU_THREAD_OTHER, and nidas::util::Thread::NU_THREAD_RR.

Referenced by nidas::core::DSMSensor::getLooper(), and nidas::util::Thread::makeFullName().

virtual SampleSource* nidas::core::SampleSource::getProcessedSampleSource ( )

pure virtualinherited

Several objects in NIDAS can be both a SampleSource of raw Samples and processed Samples.

SampleClients use this method to get a pointer to whatever sample source they are interested in. Derived classes can return NULL if they are not a SampleSource of processed samples.

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::NearestResamplerAtRate, nidas::core::SampleIOProcessor, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::dynld::StatisticsCruncher, nidas::core::SampleAverager, nidas::core::SampleBuffer, nidas::core::NearestResampler, and nidas::core::SampleSourceSupport.

Referenced by nidas::dynld::SampleProcessor::connectSource(), nidas::dynld::raf::CVIProcessor::connectSource(), nidas::dynld::StatisticsProcessor::connectSource(), nidas::core::SampleArchiver::connectSource(), and nidas::core::SampleArchiver::disconnectSource().

virtual SampleSource* nidas::core::SampleSource::getRawSampleSource ( )

pure virtualinherited

Several objects in NIDAS can be both a SampleSource of raw Samples and processed Samples.

SampleClients use this method to get a pointer to whatever sample source they are interested in. Derived classes can return NULL if they are not a SampleSource of raw samples.

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::NearestResamplerAtRate, nidas::core::SampleIOProcessor, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::dynld::StatisticsCruncher, nidas::core::SampleAverager, nidas::core::NearestResampler, nidas::core::SampleBuffer, and nidas::core::SampleSourceSupport.

Referenced by nidas::core::SamplePipeline::connect(), nidas::core::SampleArchiver::connectSource(), nidas::core::SamplePipeline::disconnect(), and nidas::core::SampleArchiver::disconnectSource().

virtual bool nidas::core::SampleThread::getRealTime ( ) const

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

virtual const SampleStats& nidas::core::SampleSource::getSampleStats ( ) const

pure virtualinherited

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::NearestResamplerAtRate, nidas::core::SampleIOProcessor, nidas::core::SamplePipeline, nidas::core::SampleSourceSupport, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::StatisticsCruncher, nidas::dynld::raf::SyncRecordGenerator, nidas::core::SampleAverager, and nidas::core::NearestResampler.

Referenced by nidas::core::SamplePipeline::getSampleStats(), nidas::dynld::RawSampleService::printClock(), nidas::dynld::RawSampleService::printStatus(), nidas::core::SampleArchiver::printStatus(), and nidas::dynld::raf::SyncRecordGenerator::printStatus().

virtual SampleTagIterator nidas::core::SampleSource::getSampleTagIterator ( ) const

pure virtualinherited

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::SampleIOProcessor, nidas::core::NearestResamplerAtRate, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::StatisticsCruncher, nidas::dynld::raf::SyncRecordGenerator, nidas::core::SampleAverager, nidas::core::NearestResampler, and nidas::core::SampleSourceSupport.

Referenced by nidas::core::SamplePipeline::connect(), nidas::dynld::raf::CVIProcessor::connectSource(), nidas::core::SamplePipeline::disconnect(), and nidas::core::SamplePipeline::getSampleTagIterator().

virtual std::list<const SampleTag*> nidas::core::SampleSource::getSampleTags ( ) const

pure virtualinherited

What SampleTags am I a SampleSource for?

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::SampleIOProcessor, nidas::core::NearestResamplerAtRate, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::StatisticsCruncher, nidas::core::SampleSourceSupport, nidas::dynld::isff::PacketInputStream, nidas::dynld::psql::PSQLProcessor, nidas::dynld::raf::SyncRecordGenerator, nidas::core::SampleAverager, and nidas::core::NearestResampler.

Referenced by nidas::core::DSMEngine::connectOutputs(), nidas::dynld::SampleProcessor::connectSource(), nidas::dynld::StatisticsProcessor::connectSource(), nidas::core::SampleArchiver::connectSource(), nidas::core::SamplePipeline::getSampleTags(), DataPrep::run(), and nidas::dynld::RawSampleService::schedule().

void Thread::interrupt ( )

virtualinherited

Interrupt this thread.

This sets a boolean which can be tested with isInterrupted(). It is up to the run() implementation to return when interrupted. This is a "soft" request to terminate the thread.

What follows is a discussion of when to use cancel(), kill(), or interrupt() to terminate a thread.

If you can consistently check the state of isInterrupted() in the run method, and return if it is true, at a time interval which is an acceptable amount of time to wait for the thread to terminate, then using interrupt() should work well.

If the run method does I/O, then things are usually a bit more complicated.

If all I/O is guaranteed to finish quickly, which is a rare situation, or is done with a timeout, such as using select/poll with a timeout before every read/write, then one could still use interrupt() as above, and the thread will terminate within the timeout period.

If the thread does blocking I/O operations, and the I/O might block for a period of time longer than you're willing to wait for the thread to terminate, then you need to use kill(sig) or cancel().

If a signal is sent to the thread with kill(sig) while the thread is blocking on an I/O operation, the I/O will immediately return with an errno of EINTR, and one could then return from the run method, after any necessary cleanup.

However there is a possibility that the signal could be missed. In order to make sure you receive a signal, you must block it, so that any received signals are held as pending, and then atomically unblock it with pselect/ppoll/epoll_pwait before performing the I/O operation.

If you do not use I/O timeouts, or kill(sig) with pselect/ppoll/epoll_pwait, or other tricks such as writing to a pipe that is watched with select/poll in the run method, then using cancel() is the only way to guarantee that your thread will terminate in an acceptable amount of time.

All NIDAS Threads support deferred cancelation. Immediate asynchronous cancellation is not fully supported (and is very hard to get right). Deferred cancelation means that cancellation is delayed until the thread next calls a system function that is a cancellation point. At that point the thread run method will simply terminate without any return value from the system function, and then execute any cleanup methods that may have been registered with pthread_cleanup_push.

A list of cancellation points is provided in the pthreads(7) man page. Cancellation points are typically I/O operations, waits or sleeps.

This immediate thread termination can be a problem if there is a possibility that your objects could be left in a bad state, such as with a mutex locked, though it isn't generally a good practice to hold mutexes during a time-consuming I/O operation, wait or sleep.

One should check the run method to see if the state of the objects is OK if execution stops at any of the cancellation points. Note that logging a message, or writing to cerr is a cancellation point. Typically there is error/exception handling associated with an I/O operation. Ensuring the state is OK upon a cancellation is similar to preparation for a fatal I/O error that requires a return of the run method. One can use setCancelEnabled() to defer cancellation.

One can use pthread_cleanup_push and pthread_cleanup_pop to register cleanup routines that are called when a thread is cancelled if special handling is required.

Implements nidas::util::Runnable.

Reimplemented in nidas::util::McSocketMulticaster< SocketTT >, nidas::util::ThreadRunnable, nidas::util::McSocketListener, nidas::core::ServerSocket::ConnectionThread, nidas::core::Socket::ConnectionThread, nidas::dynld::RawSampleService::Worker, nidas::dynld::UDPSampleOutput::XMLSocketListener, nidas::core::SensorHandler, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::UDPSampleOutput::VariableListWorker, nidas::dynld::raf::SyncServer, nidas::core::DerivedDataReader, nidas::core::SensorOpener, nidas::dynld::XMLConfigService::Worker, nidas::core::SampleOutputRequestThread, and nidas::core::XmlRpcThread.

References nidas::util::Thread::_interrupted, and nidas::util::Thread::_mutex.

Referenced by nidas::dynld::UDPSampleOutput::close(), nidas::util::McSocket< SocketT >::close(), nidas::core::SampleOutputRequestThread::interrupt(), nidas::core::SensorOpener::interrupt(), nidas::dynld::raf::SyncServer::interrupt(), nidas::core::DSMService::interrupt(), nidas::core::SampleSorter::interrupt(), nidas::core::SamplePipeline::interrupt(), nidas::core::DSMEngine::interrupt(), nidas::util::McSocketListener::interrupt(), nidas::core::SamplePipeline::join(), nidas::core::Looper::removeClient(), and nidas::dynld::UDPSampleOutput::~UDPSampleOutput().

bool Thread::isCancelDeferred ( ) const

inherited

Return true if the cancel type of this thread is PTHREAD_CANCEL_DEFERRED.

References nidas::util::Thread::_cancel_deferred.

bool Thread::isCancelEnabled ( ) const

inherited

Return true if the cancel state of this thread is PTHREAD_CANCEL_ENABLE.

References nidas::util::Thread::_cancel_enabled.

virtual bool nidas::util::Thread::isDetached ( ) const

inlinevirtualinherited

Is this a detached thread.

References nidas::util::Thread::_detached.

virtual bool nidas::util::Thread::isInterrupted ( ) const

inlinevirtualinherited

Return true when this thread has been interrupted.

Implements nidas::util::Runnable.

References nidas::util::Thread::_interrupted, and nidas::util::Thread::_mutex.

Referenced by nidas::core::SampleSorter::flush(), nidas::core::SampleOutputRequestThread::run(), nidas::core::StatusListener::run(), nidas::core::DerivedDataReader::run(), nidas::core::SensorOpener::run(), Sender::run(), nidas::core::DSMEngineStat::run(), nidas::core::SensorHandler::run(), nidas::core::FsMountWorkerThread::run(), ModemLineSetter::run(), ModemLineMonitor::run(), nidas::core::SampleBuffer::run(), nidas::core::SampleSorter::run(), ServerThread::run(), nidas::util::McSocketListener::run(), and nidas::dynld::raf::SyncServer::stop().

virtual bool nidas::util::Thread::isJoined ( ) const

inlinevirtualinherited

Has this thread been joined?

References nidas::util::Thread::getId().

Referenced by nidas::core::FsMount::cancel(), nidas::core::DerivedDataReader::deleteInstance(), nidas::core::SensorHandler::join(), nidas::dynld::isff::GOESOutput::joinThread(), nidas::util::Thread::test(), nidas::core::SampleBuffer::~SampleBuffer(), nidas::core::SampleSorter::~SampleSorter(), and nidas::util::Thread::~Thread().

virtual bool nidas::util::Thread::isRunning ( ) const

inlinevirtualinherited

Is this thread running?

References nidas::util::Thread::_mutex, and nidas::util::Thread::_running.

Referenced by nidas::util::Thread::blockSignal(), nidas::core::DSMService::cancel(), nidas::core::FsMount::cancel(), nidas::dynld::isff::GOESOutput::cancelThread(), nidas::core::DSMService::checkSubThreads(), nidas::dynld::UDPSampleOutput::XMLSocketListener::checkWorkers(), nidas::dynld::UDPSampleOutput::close(), nidas::util::McSocket< SocketT >::close(), nidas::core::DerivedDataReader::deleteInstance(), nidas::core::DSMService::interrupt(), nidas::core::SamplePipeline::join(), nidas::dynld::isff::GOESOutput::joinThread(), nidas::core::DSMServerApp::killStatusThread(), nidas::dynld::isff::GOESOutput::killThread(), nidas::core::Looper::removeClient(), nidas::core::SensorHandler::run(), nidas::core::Looper::setupClientMaps(), nidas::util::Thread::test(), nidas::util::Thread::unblockSignal(), nidas::core::SampleBuffer::~SampleBuffer(), nidas::core::SampleSorter::~SampleSorter(), nidas::util::Thread::~Thread(), and nidas::dynld::UDPSampleOutput::~UDPSampleOutput().

int Thread::join	(		)
throw	(	Exception
	)

virtualinherited

The calling thread joins this thread, waiting until the thread finishes, which means either that the run() method returned, the thread called pthread_exit() or the thread was cancelled.

The return value is the int return value of the run method, or PTHREAD_CANCELED (-1). If the run method threw an Exception, it will be caught and then re-thrown by join.

Reimplemented in nidas::core::SensorHandler.

References nidas::util::Thread::_exception, nidas::util::Thread::_id, nidas::util::Thread::_mutex, nidas::util::Exception::errnoToString(), nidas::util::Thread::getId(), nidas::util::Thread::getName(), nidas::util::Thread::RUN_EXCEPTION, and nidas::util::Thread::RUN_OK.

Referenced by nidas::core::DSMService::checkSubThreads(), nidas::dynld::UDPSampleOutput::XMLSocketListener::checkWorkers(), nidas::dynld::UDPSampleOutput::close(), nidas::util::McSocketListener::close(), nidas::core::DerivedDataReader::deleteInstance(), nidas::dynld::UDPSampleOutput::XMLSocketListener::fireWorkers(), nidas::core::DSMService::join(), nidas::core::SensorHandler::join(), nidas::core::SamplePipeline::join(), nidas::core::DSMEngine::joinDataThreads(), nidas::dynld::isff::GOESOutput::joinThread(), nidas::core::DSMServerApp::killStatusThread(), nidas::core::DSMServerApp::killXmlRpcThread(), nidas::core::DSMEngine::killXmlRpcThread(), main(), nidas::core::Looper::removeClient(), nidas::util::ThreadJoiner::run(), nidas::core::SampleBuffer::~SampleBuffer(), nidas::core::SampleSorter::~SampleSorter(), nidas::core::ServerSocket::~ServerSocket(), and nidas::dynld::UDPSampleOutput::~UDPSampleOutput().

void Thread::kill	(	int	sig	)
throw	(	Exception
	)

virtualinherited

Send a signal to this thread.

References nidas::util::Exception::errnoToString().

Referenced by nidas::core::FsMount::cancel(), nidas::core::XmlRpcThread::interrupt(), nidas::core::SensorOpener::interrupt(), nidas::core::DerivedDataReader::interrupt(), nidas::core::SensorHandler::interrupt(), nidas::util::McSocketListener::interrupt(), nidas::core::DSMServerApp::killStatusThread(), nidas::dynld::isff::GOESOutput::killThread(), main(), nidas::core::SensorHandler::scheduleAdd(), nidas::core::SensorHandler::scheduleClose(), nidas::core::SensorHandler::scheduleReopen(), and nidas::core::SensorHandler::sensorIsOpen().

Thread * Thread::lookupThread ( pthread_t id )

staticinherited

Referenced by nidas::util::LogContext::threadName().

virtual bool nidas::core::SampleClient::receive	(	const Sample *	s	)
throw	(
	)

pure virtualinherited

Method called to pass a sample to this client.

This method is typically called by a SampleSource for each of its SampleClients when it has a sample ready. Returns true: success false: sample rejected. This is meant to signal a warning-type situation - like a socket not being available temporarily. True errors will be thrown as an IOException.

Implemented in SampleDispatcher, DataStats, nidas::core::DSMSensor, nidas::dynld::raf::SyncRecordSource, nidas::core::NearestResamplerAtRate, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::raf::SyncRecordReader, TestClient, nidas::core::SampleAverager, nidas::core::NearestResampler, nidas::dynld::StatisticsCruncher, nidas::dynld::isff::GOESOutput, nidas::dynld::raf::CVIProcessor, DumpClient, DumpClient, nidas::dynld::psql::PSQLSampleOutput, nidas::core::RemoteSerialConnection, nidas::dynld::AsciiOutput, nidas::dynld::SampleOutputStream, nidas::dynld::UDPSampleOutput, and nidas::dynld::raf::CVIOutput.

virtual void nidas::core::SampleSource::removeSampleClient	(	SampleClient *	c	)
throw	(
	)

pure virtualinherited

Remove a SampleClient from this SampleSource.

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::SampleIOProcessor, nidas::core::NearestResamplerAtRate, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::StatisticsCruncher, nidas::core::SampleAverager, nidas::core::NearestResampler, nidas::dynld::raf::SyncRecordGenerator, and nidas::core::SampleSourceSupport.

Referenced by nidas::core::RemoteSerialConnection::close(), nidas::core::DSMEngine::closeOutputs(), nidas::dynld::SampleProcessor::disconnect(), nidas::core::SampleArchiver::disconnect(), nidas::core::SamplePipeline::disconnect(), DataDump::run(), DataStats::run(), nidas::core::SampleArchiver::~SampleArchiver(), and nidas::dynld::SampleProcessor::~SampleProcessor().

virtual void nidas::core::SampleSource::removeSampleClientForTag	(	SampleClient *	c,
		const SampleTag *
	)
throw	(
	)

pure virtualinherited

Remove a SampleClient for a given SampleTag from this SampleSource.

The pointer to the SampleClient must remain valid, until after it is removed.

Implemented in nidas::core::DSMSensor, nidas::dynld::SampleInputStream, nidas::dynld::raf::SyncRecordSource, nidas::core::SampleIOProcessor, nidas::core::NearestResamplerAtRate, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::dynld::StatisticsCruncher, nidas::core::SampleAverager, nidas::core::NearestResampler, nidas::dynld::raf::SyncRecordGenerator, and nidas::core::SampleSourceSupport.

virtual void nidas::core::SampleSource::removeSampleTag	(	const SampleTag *	)
throw	(
	)

pure virtualinherited

Implemented in nidas::core::DSMSensor, nidas::dynld::raf::SyncRecordSource, nidas::dynld::SampleInputStream, nidas::dynld::StatisticsCruncher, nidas::core::NearestResamplerAtRate, nidas::core::NearestResampler, nidas::core::SampleAverager, nidas::core::SampleIOProcessor, nidas::core::SamplePipeline, nidas::core::SampleSorter, nidas::core::SampleBuffer, and nidas::core::SampleSourceSupport.

Referenced by nidas::core::SamplePipeline::removeSampleTag().

virtual int nidas::util::Runnable::run	(		)
throw	(	Exception
	)

pure virtualinherited

The method which will run in its own thread.

This method must be supplied by the Runnable or Thread subclass.

Implemented in nidas::util::ThreadJoiner, nidas::util::McSocketMulticaster< SocketTT >, nidas::util::ThreadRunnable, nidas::util::McSocketListener, ServerThread, nidas::core::ServerSocket::ConnectionThread, WriterThread, nidas::core::SampleSorter, nidas::core::SampleBuffer, nidas::core::Socket::ConnectionThread, ModemLineMonitor, ModemLineSetter, nidas::dynld::RawSampleService::Worker, nidas::dynld::UDPSampleOutput::XMLSocketListener, nidas::core::DSMServerStat, nidas::core::FsMountWorkerThread, nidas::core::SensorHandler, nidas::dynld::UDPSampleOutput::ConnectionMonitor, nidas::dynld::isff::GOESOutput, nidas::dynld::UDPSampleOutput::VariableListWorker, nidas::core::DSMEngineStat, TestSource, PSI, Sender, nidas::dynld::raf::SyncServer, nidas::core::Looper, nidas::core::SensorOpener, nidas::dynld::XMLConfigService::Worker, nidas::core::DSMServerIntf, nidas::core::DerivedDataReader, DataWriter, nidas::core::SampleOutputRequestThread, nidas::core::StatusListener, and nidas::core::DSMEngineIntf.

Referenced by nidas::util::Thread::pRun(), nidas::util::ThreadRunnable::run(), and nidas::util::Thread::test().

void Thread::setCancelDeferred ( bool val )

protectedinherited

Set the cancel type for this thread.

true means cancel requests are deferred until the next cancellation point. false means they occur instantly. This is protected, it should be called only from a thread's own run method. See the pthreads(7) man page for a list of the cancellation points.

Note: non-deferred canceling is difficult to get right. It has not been tested with this class, and is not recommended.

References nidas::util::Thread::_cancel_deferred.

void Thread::setCancelEnabled ( bool val )

protectedinherited

Set the cancel state for this thread - false means cancel requests are ignored.

See pthread_setcancelstate. This is protected, it should be called only from a thread's own run method.

References nidas::util::Thread::_cancel_enabled.

virtual void nidas::core::SampleThread::setHeapBlock ( bool val )

pure virtual

Parameters

val	If true, and heapSize exceeds heapMax, then wait for heapSize to be less then heapMax, which will block any SampleSources that are inserting samples into this sorter. If false, then discard any samples that are received while heapSize exceeds heapMax.

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

virtual void nidas::core::SampleThread::setHeapMax ( size_t val )

pure virtual

Set the maximum amount of heap memory to use for sorting samples.

Parameters

val	Maximum size of heap in bytes.

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

virtual void nidas::core::SampleThread::setKeepStats ( bool val )

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

virtual void nidas::core::SampleThread::setLateSampleCacheSize ( unsigned int val )

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

virtual void nidas::core::SampleThread::setLengthSecs ( float val )

pure virtual

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

bool Thread::setNonRealTimePriority	(		)
throw	(	Exception
	)

inherited

References nidas::util::Thread::NU_THREAD_OTHER, and nidas::util::Thread::setThreadScheduler().

virtual void nidas::core::SampleThread::setRealTime ( bool val )

pure virtual

Is this thread running in real-time, meaning is it handling recently sampled data? If so then we can screen for bad sample time-tags by checking against the system clock, which is trusted.

Note that real-time here doesn't mean running at real-time priority.

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

bool Thread::setRealTimeFIFOPriority	(	int	val	)
throw	(	Exception
	)

inherited

Referenced by nidas::core::DSMEngine::openSensors(), nidas::core::SamplePipeline::procinit(), and nidas::core::SamplePipeline::rawinit().

bool Thread::setRealTimeRoundRobinPriority	(	int	val	)
throw	(	Exception
	)

inherited

void Thread::setThreadScheduler	(	enum SchedPolicy	policy,
		int	priority
	)
throw	(	Exception
	)

inherited

Referenced by nidas::dynld::RawSampleService::connect(), nidas::core::DSMSensor::getLooper(), and nidas::util::Thread::setNonRealTimePriority().

virtual size_t nidas::core::SampleThread::size ( ) const

pure virtual

Number of samples that have not be distributed.

Implemented in nidas::core::SampleSorter, and nidas::core::SampleBuffer.

Referenced by nidas::core::SamplePipeline::getSorterNumProcSamples(), and nidas::core::SamplePipeline::getSorterNumRawSamples().

void Thread::start	(		)
throw	(	Exception
	)

virtualinherited

Start the thread running, meaning execute the run method in a separate thread.

Referenced by nidas::util::McSocketListener::accept(), nidas::dynld::RawSampleService::connect(), nidas::core::DerivedDataReader::createInstance(), nidas::util::McSocket< SocketT >::joinMulticaster(), main(), nidas::core::DSMEngine::openSensors(), nidas::core::SamplePipeline::procinit(), nidas::core::SamplePipeline::rawinit(), nidas::util::McSocket< SocketT >::request(), nidas::core::DSMServerApp::run(), nidas::core::DSMEngine::run(), PSI::run(), nidas::core::SensorHandler::run(), nidas::core::FsMountWorkerThread::run(), nidas::dynld::UDPSampleOutput::XMLSocketListener::run(), nidas::core::Socket::ConnectionThread::run(), ServerThread::run(), nidas::core::Looper::setupClientMaps(), nidas::core::DSMServerApp::startXmlRpcThread(), and nidas::core::DSMEngine::startXmlRpcThread().

int Thread::test	(	int	argc,
		char **	argv
	)

staticinherited

a test method.

References nidas::util::Runnable::amInterrupted(), nidas::util::Thread::blockSignal(), nidas::util::Thread::getFullName(), nidas::util::Thread::getName(), nidas::util::Thread::isJoined(), nidas::util::Thread::isRunning(), nidas::util::Runnable::run(), nidas::util::Thread::Thread(), and nidas::util::Exception::what().

void nidas::util::Runnable::testCancel ( ) const

inlineprotectedinherited

Check if we have been cancelled.

Calls pthread_testcancel. This is protected since it only checks the current thread - i.e. it must be called within the run method. Since it just calls pthread_testcancel, it is a cancellation point.

void Thread::unblockSignal ( int sig )

inherited

Install a signal handler and unblock the signal.

The signal handler will log a message about the receipt of the signal at severity LOG_INFO using the nidas::util::Logger. Then, if the signal handler is being invoked from a registered Thread, the virtual method signalHandler() for that Thread will be called.

The signal handler is installed with the sigaction() system call, and will be the action for the given signal in all threads, including the main() thread. If other threads do not wish to take action on a given signal, they should call blockSignal(sig). Or they can define their own signalHandler() method.

After installing the signal handler, the signal is added to those that are unblocked for the thread, or if the Thread is not yet running, the signal will be unblocked in the thread once it runs.

As with blockSignal(), this method is typically called on this Thread before it has started. If this Thread has started, then the signal will only be unblocked if the method is called from this Thread, i.e. from its own run() method.

To install a signal handler, and then block the signal so that it is held as pending until it is later unblocked, typically with pselect(), or sigwaitinfo(), do:

void Thread::run() 
{
    // get the existing signal mask
    sigset_t sigmask;
    pthread_sigmask(SIG_BLOCK,NULL,&sigmask);
    // remove SIGUSR1 from the mask passed to pselect
    sigdelset(&sigmask,SIGUSR1);
    
    for (;;) {
        pselect(nfd,&readfds,0,0,0,&sigmask);
        ...
    }
}
...
thread.unblockSignal(SIGUSR1);
thread.blockSignal(SIGUSR1);
thread.start();
...
try {
    if (thread.isRunning()) {
        thread.kill(SIGUSR1);
        thread.join()
    }
}

References nidas::util::Thread::_blockedSignals, nidas::util::Thread::_unblockedSignals, nidas::util::Thread::currentThread(), nidas::util::Thread::isRunning(), and nidas::util::Thread::thr_add_sig().

Referenced by nidas::core::DerivedDataReader::DerivedDataReader(), nidas::core::FsMountWorkerThread::FsMountWorkerThread(), nidas::core::StatusListener::StatusListener(), nidas::core::StatusThread::StatusThread(), nidas::dynld::XMLConfigService::Worker::Worker(), nidas::core::XmlRpcThread::XmlRpcThread(), and nidas::dynld::UDPSampleOutput::XMLSocketListener::XMLSocketListener().

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

nidas/core/SampleThread.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation