dsp::FoldManager Class Reference

Manage multiple Fold operations. More...

#include <FoldManager.h>

Inheritance diagram for dsp::FoldManager:

Public Member Functions
	FoldManager ()
	Default constructor.
void	manage (Fold *)
	Add Fold instance to managed array
void	prepare ()
	Prepare to fold the input TimeSeries.
void	prepare (const Observation *observation)
	Prepare to fold the given Observation.
void	combine (const Operation *)
	If Operation is a FoldManager, integrate its Fold instances.
void	reset ()
	Reset the PhaseSeries.
void	finish ()
	Perform any final operations.
void	set_cerr (std::ostream &os) const
	Set verbosity ostream.
Public Member Functions inherited from dsp::Operation
	Operation (const char *name)
	All sub-classes must specify a unique name. More...
	Operation (const Operation &)
	Copy constructor.
virtual	~Operation ()
	Virtual destructor.
virtual bool	operate ()
	Call this method to operate on data Returns false on failure. More...
virtual void	reserve ()
	Reserve the maximum amount of memory required. More...
virtual void	add_extensions (Extensions *)
	Add any extensions.
virtual void	report () const
	Report operation statistics.
std::string	get_name () const
	Return the unique name of this operation.
double	get_total_time () const
	Return the total time spent on this Operation in seconds.
double	get_elapsed_time () const
	Get the time spent in the last invocation of operate()
virtual uint64_t	get_total_weights () const
	Return the total number of timesample weights encountered. More...
virtual uint64_t	get_discarded_weights () const
	Return the number of invalid timesample weights encountered.
int	get_id ()
	Inquire the unique instantiation id.
virtual Function	get_function () const
	Get the function classification of this operation.
virtual double	get_delay_time () const
	Get the time delay of this operation, if any, in seconds.
virtual void	set_scratch (Scratch *)
	Set the scratch space.
bool	scratch_was_set () const
virtual uint64_t	bytes_storage () const
	The number of bytes of additional storage used by the operation.
virtual uint64_t	bytes_scratch () const
	The number of bytes of scratch space used by the operation. More...
Public Member Functions inherited from OwnStream
	OwnStream (const OwnStream &)
const OwnStream &	operator= (const OwnStream &)
virtual void	set_cout (std::ostream &) const
Public Member Functions inherited from Reference::Able
	Able (const Able &)
Able &	operator= (const Able &)
unsigned	get_reference_count () const
Public Member Functions inherited from Reference::HeapTracked
	HeapTracked (const HeapTracked &)
HeapTracked &	operator= (const HeapTracked &)
bool	__is_on_heap () const

Protected Member Functions
virtual void	operation ()
	Simply executes all of the Fold operations in order.
Protected Member Functions inherited from dsp::Operation
virtual bool	can_operate ()
	Return false if the operation doesn't have enough data to proceed.
virtual void	set_name (const std::string &_name)
	Set the name!
int	timers_index (const std::string &op_name)
	Returns the index in the 'timers' array of a particular timer.
Protected Member Functions inherited from Reference::Able
Handle *	__reference (bool active) const
void	__dereference (bool auto_delete=true) const

Protected Attributes
std::vector< Reference::To< Fold > >	fold
	The set of fold operations.
Protected Attributes inherited from dsp::Operation
Scratch *	scratch
	Shared scratch space, if needed.
bool	set_scratch_called
std::string	name
	Operation name.
uint64_t	discarded_weights
	Number of time sample weights encountered that are flagged invalid.
uint64_t	total_weights
	Total number of time sample weights encountered.
RealTimer	optime
	Stop watch records the amount of time spent performing this operation.
int	id
	Unique instantiation id.
bool	prepared
	Set true when preparation optimizations are completed.

Additional Inherited Members
Public Types inherited from dsp::Operation
enum	Function { Producer, Procedural, Structural }
	The function of the operator. More...
Static Public Member Functions inherited from Reference::Able
static size_t	get_instance_count ()
Static Public Member Functions inherited from Reference::HeapTracked
static void *	operator new (size_t size, void *ptr=0)
static void	operator delete (void *location, void *ptr)
static void	operator delete (void *location)
static size_t	get_heap_queue_size ()
Static Public Attributes inherited from dsp::Operation
static bool	record_time = false
	Global flag enables stopwatch to record the time spent operating. More...
static bool	report_time = true
	Global flag enables report of time spent in operation on descruction. More...
static bool	verbose = false
	Global verbosity flag.
static int	operation_status = 0
	Operations can set this to non-zero in operation() if they fail.
static bool	check_state = true
	Operations should perform internal consistency checks.
static int	instantiation_count = 0
	Counts how many Operation instantiations there have been Used for setting the unique instantiation ID. More...

Detailed Description

Manage multiple Fold operations.

The original intent for this class was to implement a solution to a thread deadlock issue. However, in the end, 1) this class currently has a bug in it (see https://sourceforge.net/p/dspsr/bugs/93/); and 2) the thread deadlock issue was solved in a different way.

When a thread reaches the end of a sub-integration, there are two possibilities:

a. the sub-integration is complete and can be written to disk; or

b. the sub-integration is incomplete because one or more threads still have data to fold into it (and have yet to do so).

In case b, there are a couple of options:

1. Clone the data and put it in a place where the other threads will find it when they get to the end of the same sub-integration on the same pulsar; each thread can add to it and, when it is complete, write it to disk. The clone is necessary so that the original thread can resume where it left off in the time series and start folding the next sub-integration into a different array.
2. Put the data in a place where the other threads will find it when they get to the end of the same sub-integration on the same pulsar, then go to sleep. The other threads add to the data and wake up the original thread after they have done so; when the sub-integration is complete, the original thread writes it to disk

Option 1 is not very friendly on RAM, especially if sub-integration data are somewhat large (e.g. many channels) and there are many pulsars to fold. Therefore, dspsr implements option 2. However, when there are multiple folds happening in parallel, different threads can go to sleep waiting for sub-integrations to be completed on different pulsars, and in the case of two threads it is possible for thread A to be waiting on pulsar X and thread B to be waiting on pulsar Y (deadlock).

It is simplest to use option 1, but this could lead to large numbers of cloned sub-integrations waiting around to be completed. I guess that there would be at most nthread cloned sub-integrations, and perhaps this is not terrible in most cases.

Another approach is to stick to option 2 but link the different Fold transformations with pointers to each other, such that a thread will go and finish other Fold operations (and wake up any other sleeping threads) before going to sleep on its current Fold.

I like option 2 best and started working on this class to manage the links. In the end, I went with option 1. Before option 2 can be attempted using this class, the bug in this class must be fixed.

---

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

• FoldManager.h
• FoldManager.C