Audacity  2.2.0
BlockFile Class Referenceabstract

A BlockFile is a chunk of immutable audio data. More...

#include <BlockFile.h>

Inheritance diagram for BlockFile:
AliasBlockFile LegacyBlockFile SilentBlockFile SimpleBlockFile PCMAliasBlockFile ODDecodeBlockFile LegacyAliasBlockFile ODPCMAliasBlockFile

Classes

struct  GetFileNameResult
 
struct  MinMaxRMS
 
class  ReadLock
 
struct  ReadLocker
 
struct  ReadUnlocker
 

Public Types

using DiskByteCount = unsigned long long
 

Public Member Functions

 BlockFile (wxFileNameWrapper &&fileName, size_t samples)
 Construct a BlockFile. More...
 
virtual ~BlockFile ()
 
virtual size_t ReadData (samplePtr data, sampleFormat format, size_t start, size_t len, bool mayThrow=true) const =0
 
virtual bool GetNeedWriteCacheToDisk ()
 
virtual void WriteCacheToDisk ()
 
virtual bool GetNeedFillCache ()
 
virtual void FillCache ()
 
virtual void SaveXML (XMLWriter &xmlFile)=0
 Stores a representation of this file in XML. More...
 
virtual GetFileNameResult GetFileName () const
 
virtual void SetFileName (wxFileNameWrapper &&name)
 sets the file name the summary info will be saved in. threadsafe. More...
 
size_t GetLength () const
 
void SetLength (size_t newLen)
 
virtual void Lock ()
 Locks this BlockFile, to prevent it from being moved. More...
 
virtual void Unlock ()
 Unlock this BlockFile, allowing it to be moved. More...
 
virtual bool IsLocked ()
 Returns TRUE if this BlockFile is locked. More...
 
virtual MinMaxRMS GetMinMaxRMS (size_t start, size_t len, bool mayThrow=true) const
 Gets extreme values for the specified region. More...
 
virtual MinMaxRMS GetMinMaxRMS (bool mayThrow=true) const
 Gets extreme values for the entire block. More...
 
virtual bool Read256 (float *buffer, size_t start, size_t len)
 Returns the 256 byte summary data block. More...
 
virtual bool Read64K (float *buffer, size_t start, size_t len)
 Returns the 64K summary data block. More...
 
virtual bool IsAlias () const
 Returns TRUE if this block references another disk file. More...
 
virtual bool IsSummaryAvailable () const
 Returns TRUE if this block's complete summary has been computed and is ready (for OD) More...
 
virtual bool IsDataAvailable () const
 Returns TRUE if this block's complete data is ready to be accessed by Read() More...
 
virtual bool IsSummaryBeingComputed ()
 Returns TRUE if the summary has not yet been written, but is actively being computed and written to disk. More...
 
virtual BlockFilePtr Copy (wxFileNameWrapper &&newFileName)=0
 Create a NEW BlockFile identical to this, using the given filename. More...
 
virtual DiskByteCount GetSpaceUsage () const =0
 
virtual void Recover ()=0
 if the on-disk state disappeared, either recover it (if it was More...
 
void SilenceLog () const
 if we've detected an on-disk problem, the user opted to More...
 
virtual void CloseLock ()
 
ReadLock LockForRead () const
 

Static Public Attributes

static unsigned long gBlockFileDestructionCount { 0 }
 

Protected Types

using ReadLockBase = movable_ptr_with_deleter< const BlockFile, ReadUnlocker >
 

Protected Member Functions

virtual void LockRead () const
 Prevents a read on other threads. The basic blockfile runs on only one thread, so does nothing. More...
 
virtual void UnlockRead () const
 Allows reading on other threads. More...
 
virtual void * CalcSummary (samplePtr buffer, size_t len, sampleFormat format, ArrayOf< char > &cleanup)
 
void CalcSummaryFromBuffer (const float *fbuffer, size_t len, float *summary256, float *summary64K)
 
virtual bool ReadSummary (ArrayOf< char > &data)=0
 Read the summary section of the file. Derived classes implement. More...
 
virtual void FixSummary (void *data)
 

Static Protected Member Functions

static size_t CommonReadData (bool mayThrow, const wxFileName &fileName, bool &mSilentLog, const AliasBlockFile *pAliasFile, sampleCount origin, unsigned channel, samplePtr data, sampleFormat format, size_t start, size_t len, const sampleFormat *pLegacyFormat=nullptr, size_t legacyLen=0)
 

Protected Attributes

wxFileNameWrapper mFileName
 
size_t mLen
 
SummaryInfo mSummaryInfo
 
float mMin
 
float mMax
 
float mRMS
 
bool mSilentLog
 

Private Attributes

int mLockCount
 

Static Private Attributes

static ArrayOf< char > fullSummary
 

Detailed Description

A BlockFile is a chunk of immutable audio data.

A BlockFile represents a chunk of audio data. These chunks are assembled into sequences by the class Sequence. These classes are at the heart of how Audacity stores audio data.

BlockFile is an abstract base class that can be implemented in many different ways. However it does have a fairly large amount of shared code that deals with the physical file and manipulating the summary data.

BlockFile should be thought of as an immutable class. After it is constructed, it is essentially never changed (though there are a few exceptions). Most notably, the audio data and summary data are never altered once it is constructed. This is important to some of the derived classes that are actually aliases to audio data stored in existing files.

BlockFiles are managed by std::shared_ptr, so they are reference-counted.

Member Typedef Documentation

using BlockFile::DiskByteCount = unsigned long long

Constructor & Destructor Documentation

BlockFile::BlockFile ( wxFileNameWrapper &&  fileName,
size_t  samples 
)

Construct a BlockFile.

Initializes the base BlockFile data. The block is initially unlocked and its reference count is 1.

Parameters
fileNameThe name of the disk file associated with this BlockFile. Not all BlockFiles will store their sample data here (for example, AliasBlockFiles read their data from elsewhere), but all BlockFiles will store at least the summary data here.
samplesThe number of samples this BlockFile contains.

References mSilentLog.

BlockFile::~BlockFile ( )
virtual

Member Function Documentation

void * BlockFile::CalcSummary ( samplePtr  buffer,
size_t  len,
sampleFormat  format,
ArrayOf< char > &  cleanup 
)
protectedvirtual

Calculate summary data for the given sample data Overrides have differing details of memory management

Get a buffer containing a summary block describing this sample data. This must be called by derived classes when they are constructed, to allow them to construct their summary data, after which they should write that data to their disk file.

This method also has the side effect of setting the mMin, mMax, and mRMS members of this class.

You must not DELETE the returned buffer; it is static to this method.

Parameters
bufferA buffer containing the sample data to be analyzed
lenThe length of the sample data
formatThe format of the sample data.

Reimplemented in ODDecodeBlockFile, and ODPCMAliasBlockFile.

References CalcSummaryFromBuffer(), CopySamples(), fullSummary, headerTag, headerTagLen, mSummaryInfo, SummaryInfo::offset256, SummaryInfo::offset64K, ArrayOf< X >::reinit(), and SummaryInfo::totalSummaryBytes.

Referenced by SimpleBlockFile::SimpleBlockFile(), SimpleBlockFile::WriteSimpleBlockFile(), and AliasBlockFile::WriteSummary().

void BlockFile::CalcSummaryFromBuffer ( const float *  fbuffer,
size_t  len,
float *  summary256,
float *  summary64K 
)
protected
virtual void BlockFile::CloseLock ( )
inlinevirtual

when the project closes, it locks the blockfiles. Override this in case it needs special treatment.

Reimplemented in ODPCMAliasBlockFile.

size_t BlockFile::CommonReadData ( bool  mayThrow,
const wxFileName &  fileName,
bool &  mSilentLog,
const AliasBlockFile pAliasFile,
sampleCount  origin,
unsigned  channel,
samplePtr  data,
sampleFormat  format,
size_t  start,
size_t  len,
const sampleFormat *  pLegacyFormat = nullptr,
size_t  legacyLen = 0 
)
staticprotected
virtual BlockFilePtr BlockFile::Copy ( wxFileNameWrapper &&  newFileName)
pure virtual

Create a NEW BlockFile identical to this, using the given filename.

Implemented in ODDecodeBlockFile, ODPCMAliasBlockFile, SimpleBlockFile, LegacyBlockFile, PCMAliasBlockFile, SilentBlockFile, and LegacyAliasBlockFile.

virtual void BlockFile::FillCache ( )
inlinevirtual

Reimplemented in SimpleBlockFile.

void BlockFile::FixSummary ( void *  data)
protectedvirtual
auto BlockFile::GetFileName ( ) const
virtual

Returns the file name of the disk file associated with this BlockFile. Not all BlockFiles store their sample data here, but most BlockFiles have at least their summary data here. (some, i.e. SilentBlockFiles, do not correspond to a file on disk and have empty file names)

Reimplemented in ODDecodeBlockFile, and ODPCMAliasBlockFile.

References mFileName.

Referenced by DirManager::ContainsBlockFile(), DirManager::CopyToNewProjectDirectory(), and SimpleBlockFile::SimpleBlockFile().

size_t BlockFile::GetLength ( ) const
inline
auto BlockFile::GetMinMaxRMS ( size_t  start,
size_t  len,
bool  mayThrow = true 
) const
virtual

Gets extreme values for the specified region.

Retrieves the minimum, maximum, and maximum RMS of the specified sample data in this block.

Parameters
startThe offset in this block where the region should begin
lenThe number of samples to include in the region

Reimplemented in ODPCMAliasBlockFile, and ODDecodeBlockFile.

References min(), and SampleBuffer::ptr().

Referenced by ODDecodeBlockFile::GetMinMaxRMS(), and ODPCMAliasBlockFile::GetMinMaxRMS().

auto BlockFile::GetMinMaxRMS ( bool  mayThrow = true) const
virtual

Gets extreme values for the entire block.

Retrieves the minimum, maximum, and maximum RMS of this entire block. This is faster than the other GetMinMax function since these values are already computed.

Reimplemented in ODPCMAliasBlockFile, and ODDecodeBlockFile.

References mMax, mMin, and mRMS.

virtual bool BlockFile::GetNeedFillCache ( )
inlinevirtual

Reimplemented in SimpleBlockFile.

virtual bool BlockFile::GetNeedWriteCacheToDisk ( )
inlinevirtual

Reimplemented in SimpleBlockFile.

virtual DiskByteCount BlockFile::GetSpaceUsage ( ) const
pure virtual
virtual bool BlockFile::IsAlias ( ) const
inlinevirtual

Returns TRUE if this block references another disk file.

Reimplemented in AliasBlockFile.

virtual bool BlockFile::IsDataAvailable ( ) const
inlinevirtual

Returns TRUE if this block's complete data is ready to be accessed by Read()

Reimplemented in ODDecodeBlockFile.

bool BlockFile::IsLocked ( )
virtual

Returns TRUE if this BlockFile is locked.

Returns true if the block is locked.

References mLockCount.

Referenced by ODPCMAliasBlockFile::Unlock(), and ~BlockFile().

virtual bool BlockFile::IsSummaryAvailable ( ) const
inlinevirtual

Returns TRUE if this block's complete summary has been computed and is ready (for OD)

Reimplemented in ODPCMAliasBlockFile, and ODDecodeBlockFile.

Referenced by DirManager::CopyToNewProjectDirectory().

virtual bool BlockFile::IsSummaryBeingComputed ( )
inlinevirtual

Returns TRUE if the summary has not yet been written, but is actively being computed and written to disk.

Reimplemented in ODPCMAliasBlockFile, and ODDecodeBlockFile.

Referenced by DirManager::CopyToNewProjectDirectory().

void BlockFile::Lock ( )
virtual

Locks this BlockFile, to prevent it from being moved.

Marks this BlockFile as "locked." A locked BlockFile may not be moved or deleted, only copied. Locking a BlockFile prevents it from disappearing if the project is saved in a different location. When doing a "Save As," Audacity locks all blocks belonging to the already-existing project, to ensure that the existing project remains valid with all the blocks it needs. Audacity also locks the blocks of the last saved version of a project when the project is deleted so that the files aren't deleted when their refcount hits zero.

Reimplemented in ODPCMAliasBlockFile.

References BLOCKFILE_DEBUG_OUTPUT, and mLockCount.

Referenced by ODPCMAliasBlockFile::CloseLock(), and ODPCMAliasBlockFile::Lock().

virtual void BlockFile::LockRead ( ) const
inlineprotectedvirtual

Prevents a read on other threads. The basic blockfile runs on only one thread, so does nothing.

Reimplemented in ODDecodeBlockFile, and ODPCMAliasBlockFile.

Referenced by BlockFile::ReadLocker::operator()().

bool BlockFile::Read256 ( float *  buffer,
size_t  start,
size_t  len 
)
virtual

Returns the 256 byte summary data block.

Retrieves a portion of the 256-byte summary buffer from this BlockFile. This data provides information about the minimum value, the maximum value, and the maximum RMS value for every group of 256 samples in the file. Fill with zeroes and return false if data are unavailable for any reason.

Parameters
*bufferThe area where the summary information will be written. It must be at least len*3 long.
startThe offset in 256-sample increments
lenThe number of 256-sample summary frames to read

Reimplemented in ODPCMAliasBlockFile, and ODDecodeBlockFile.

References SummaryInfo::bytesPerFrame, CopySamples(), SummaryInfo::fields, SummaryInfo::format, SummaryInfo::frames256, min(), mSummaryInfo, SummaryInfo::offset256, and ReadSummary().

Referenced by ODDecodeBlockFile::Read256(), and ODPCMAliasBlockFile::Read256().

bool BlockFile::Read64K ( float *  buffer,
size_t  start,
size_t  len 
)
virtual

Returns the 64K summary data block.

Retrieves a portion of the 64K summary buffer from this BlockFile. This data provides information about the minimum value, the maximum value, and the maximum RMS value for every group of 64K samples in the file. Fill with zeroes and return false if data are unavailable for any reason.

Parameters
*bufferThe area where the summary information will be written. It must be at least len*3 long.
startThe offset in 64K-sample increments
lenThe number of 64K-sample summary frames to read

Reimplemented in ODPCMAliasBlockFile, and ODDecodeBlockFile.

References SummaryInfo::bytesPerFrame, CopySamples(), SummaryInfo::fields, SummaryInfo::format, SummaryInfo::frames64K, min(), mSummaryInfo, SummaryInfo::offset64K, and ReadSummary().

Referenced by ODDecodeBlockFile::Read64K(), and ODPCMAliasBlockFile::Read64K().

virtual size_t BlockFile::ReadData ( samplePtr  data,
sampleFormat  format,
size_t  start,
size_t  len,
bool  mayThrow = true 
) const
pure virtual

Retrieves audio data from this BlockFile Returns the number of samples really read, not more than len If fewer can be read than len, throws an exception if mayThrow is true, otherwise fills the remainder of data with zeroes.

Implemented in ODPCMAliasBlockFile, ODDecodeBlockFile, SimpleBlockFile, LegacyBlockFile, PCMAliasBlockFile, and SilentBlockFile.

Referenced by AliasBlockFile::WriteSummary().

virtual bool BlockFile::ReadSummary ( ArrayOf< char > &  data)
protectedpure virtual

Read the summary section of the file. Derived classes implement.

Implemented in AliasBlockFile, ODPCMAliasBlockFile, ODDecodeBlockFile, SimpleBlockFile, LegacyBlockFile, and SilentBlockFile.

Referenced by Read256(), and Read64K().

virtual void BlockFile::Recover ( )
pure virtual

if the on-disk state disappeared, either recover it (if it was

Implemented in ODDecodeBlockFile, ODPCMAliasBlockFile, SimpleBlockFile, LegacyBlockFile, SilentBlockFile, PCMAliasBlockFile, and LegacyAliasBlockFile.

virtual void BlockFile::SaveXML ( XMLWriter xmlFile)
pure virtual

Stores a representation of this file in XML.

Implemented in ODDecodeBlockFile, ODPCMAliasBlockFile, SimpleBlockFile, LegacyBlockFile, SilentBlockFile, PCMAliasBlockFile, and LegacyAliasBlockFile.

void BlockFile::SetFileName ( wxFileNameWrapper &&  name)
virtual

sets the file name the summary info will be saved in. threadsafe.

Reimplemented in ODDecodeBlockFile, and ODPCMAliasBlockFile.

References mFileName, and name.

Referenced by DirManager::CopyToNewProjectDirectory().

void BlockFile::SetLength ( size_t  newLen)
inline
void BlockFile::SilenceLog ( ) const
inline

if we've detected an on-disk problem, the user opted to

void BlockFile::Unlock ( )
virtual

Unlock this BlockFile, allowing it to be moved.

Marks this BlockFile as "unlocked.".

Reimplemented in ODPCMAliasBlockFile.

References BLOCKFILE_DEBUG_OUTPUT, and mLockCount.

Referenced by ODPCMAliasBlockFile::Unlock().

virtual void BlockFile::UnlockRead ( ) const
inlineprotectedvirtual

Allows reading on other threads.

Reimplemented in ODDecodeBlockFile, and ODPCMAliasBlockFile.

Referenced by BlockFile::ReadUnlocker::operator()().

virtual void BlockFile::WriteCacheToDisk ( )
inlinevirtual

Reimplemented in SimpleBlockFile.

Member Data Documentation

ArrayOf< char > BlockFile::fullSummary
staticprivate

Referenced by CalcSummary().

unsigned long BlockFile::gBlockFileDestructionCount { 0 }
static
int BlockFile::mLockCount
private

Referenced by IsLocked(), Lock(), and Unlock().


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