Geddei::xLConnection Class Reference
[Geddei's core classes.]

Refinement of Connection to a local Sink. More...

#include <xlconnection.h>

List of all members.

Public Member Functions

virtual const uint capacity () const=0
virtual const float filled () const
const BufferData peekSample ()
const BufferData peekSamples (const uint samples=0, const bool allowZero=false)
const BufferData peekSecond ()
const BufferData peekSeconds (const float seconds)
const BufferData readSample ()
const BufferData readSamples (const uint samples=0, const bool allowZero=false)
const BufferData readSecond ()
const BufferData readSeconds (const float seconds)
const uint samplesReady () const
virtual const SignalTypeRef type ()
void waitForSamples (const uint samples=1) const
virtual ~xLConnection ()

Protected Member Functions

virtual const uint elementsReady () const=0
virtual void killReader ()=0
virtual BufferReader * newReader ()=0
virtual const BufferData peekElements (const uint elements)=0
virtual const bool plungeSync (const uint samples) const=0
virtual const BufferData readElements (const uint elements)=0
virtual void reset ()=0
virtual void resurectReader ()=0
virtual void sinkStopped ()=0
virtual void sinkStopping ()=0
virtual void waitForElements (const uint elements) const =0
 xLConnection (Sink *newSink, const uint newSinkIndex)

Protected Attributes

Sink * theSink
 Sink object that anchors thit end of the connection.
uint theSinkIndex
 Index into the Sink object, if any.

Friends

class DomProcessor
class Processor


Detailed Description

Refinement of Connection to a local Sink.

Author:
Gav Wood <gav@cs.york.ac.uk>
This class functions essentially as an abstract interface that contains some utility methods. It is the base class for connection classes that are used by the sink side of the connection.

With proper use of Processor class's Processor::specifyInputSpace() method you should only ever need to use one method; readSamples().

Other methods are included for convenience, such as readSample() and readSecond(). The "peeking" methods are included for more esoteric coding, and advanced coders may find the waitForSamples() and samplesReady() methods quite useful.


Constructor & Destructor Documentation

Geddei::xLConnection::~xLConnection (  )  [virtual]

Simple destructor.


Member Function Documentation

virtual const uint Geddei::xLConnection::capacity (  )  const [pure virtual]

Get the capacity of the buffer. Any reads above this amount will block indefinately.

Returns:
The number of samples that this buffer can hold at once.

virtual const float Geddei::xLConnection::filled (  )  const [inline, virtual]

Get the current filled-ness of the buffer.

Returns:
0 if there is no buffer on this side of the connection. Otherwise return the filledness relative to the size (range 0. to 1.).

const BufferData Geddei::xLConnection::peekSample (  )  [inline]

Read a single sample from the connection. This will block until a sample is ready to be read. The data will not be removed from the connection's stream and further calls to read data from this connection will reread the data.

Returns:
A BufferData object containing the sample read.

const BufferData Geddei::xLConnection::peekSamples ( const uint  samples = 0,
const bool  allowZero = false 
) [inline]

Read a number of samples from the connection. If a non-zero samples is provided, it will block until samples samples are ready on the connection, thus you will only ever have the exact amount you require returned. The data will not be removed from the connection's stream and further calls to read data from this connection will reread the data.

Under default conditions, specifying samples of zero (the default) will return a BufferDatas containing all the samples currently available, once some samples are available. To make it return immediately, even if no samples are available, set allowZero to true. This will, of course, make valid the case of returning a BufferData object of size 0.

Parameters:
samples The number of samples to read. If zero, an arbitrary number of samples will be read, depending upon the current contents of the buffer.
allowZero If true, a BufferData of size zero is allowed to be returned, and the call will never block.
Returns:
A BufferData object containing the samples read. If samples > 0 then this is guaranteed to contain exactly samples samples.

const BufferData Geddei::xLConnection::peekSecond (  )  [inline]

Read a second's worth of signal data from the connection. This will block until a second's worth is ready to be read. The data will not be removed from the connection's stream and further calls to read data from this connection will reread the data.

Returns:
A BufferData object containing the second of data read.

const BufferData Geddei::xLConnection::peekSeconds ( const float  seconds  )  [inline]

Read a number of seconds' worth of signal data from the connection. This will block until enough data is ready to be read. The data will not be removed from the connection's stream and further calls to read data from this connection will reread the data.

Returns:
A BufferData object containing the data read. This is guarenteed to be exactly seconds seconds of signal data.

const BufferData Geddei::xLConnection::readSample (  )  [inline]

Read a single sample from the connection. This will block until a sample is ready to be read.

From the API user's point of view the sample is immediately disguarded from the stream. Technically, if you're interested, it may only actually be disguarded once the BufferData object (and all shared copies of it) is destroyed. This happens automatically thanks to the cleverness of BufferData.

Returns:
A BufferData object containing the sample read.

const BufferData Geddei::xLConnection::readSamples ( const uint  samples = 0,
const bool  allowZero = false 
) [inline]

Read a number of samples from the connection. If a non-zero samples is provided, it will block until samples samples are ready on the connection, thus you will only ever have the exact amount you require returned.

Under default conditions, specifying samples of zero (the default) will return a BufferDatas containing all the samples currently available, once some samples are available. To make it return immediately, even if no samples are available, set allowZero to true. This will, of course, make valid the case of returning a BufferData object of size 0.

From the API user's point of view the data is immediately disguarded from the stream. Technically, if you're interested, it may only actually be disguarded once the BufferData object (and all shared copies of it) is destroyed. This happens automatically thanks to the cleverness of BufferData.

Parameters:
samples The number of samples to read. If zero, an arbitrary number of samples will be read, depending upon the current contents of the buffer.
allowZero If true, a BufferData of size zero is allowed to be returned, and the call will never block.
Returns:
A BufferData object containing the samples read. If samples > 0 then this is guaranteed to contain exactly samples samples.

const BufferData Geddei::xLConnection::readSecond (  )  [inline]

Read a second's worth of signal data from the connection. This will block until a second's worth is ready to be read.

From the API user's point of view the data is immediately disguarded from the stream. Technically, if you're interested, it may only actually be disguarded once the BufferData object (and all shared copies of it) is destroyed. This happens automatically thanks to the cleverness of BufferData.

Returns:
A BufferData object containing the second of data read.

const BufferData Geddei::xLConnection::readSeconds ( const float  seconds  )  [inline]

Read a number of seconds' worth of signal data from the connection. This will block until enough data is ready to be read.

From the API user's point of view the data is immediately disguarded from the stream. Technically, if you're interested, it may only actually be disguarded once the BufferData object (and all shared copies of it) is destroyed. This happens automatically thanks to the cleverness of BufferData.

Returns:
A BufferData object containing the data read. This is guarenteed to be exactly seconds seconds of signal data.

const uint Geddei::xLConnection::samplesReady (  )  const [inline]

Checks how many samples are currently ready to be read. This is correct at some point between calling and returning, though Geddei does not (and cannot) guarantee when exactly.

Generally you will not need to use this method, and be warned, the semantics can be slightly tricky, essentially due to the lack of synchronisation facilities. It's only here for those with a good knowledge of how the code works internally or those willing to experiment to try to optimise their code into oblivion.

Returns:
The number of samples ready. Due to the timing semantics, this may be an underestimate.

virtual const SignalTypeRef Geddei::xLConnection::type (  )  [inline, virtual]

Retrieves the type of signal this connection transfers.

Returns:
A SignalTypeRef of this conection's SignalType.

void Geddei::xLConnection::waitForSamples ( const uint  samples = 1  )  const [inline]

Blocks until at least samples are ready to be read (or peeked) on the connection.

Generally you will not need to use this method. It's only here for those with a good knowledge of how the code works internally or those willing to experiment to try to optimise their code into oblivion.

Parameters:
samples The number of samples this call should no longer block at.


The documentation for this class was generated from the following files:
Generated on Fri Nov 10 21:58:38 2006 for Exscalibar by  doxygen 1.5.1