Audacity  2.2.0
BlockFile.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  BlockFile.h
6 
7  Joshua Haberman
8  Dominic Mazzoni
9 
10 **********************************************************************/
11 
12 #ifndef __AUDACITY_BLOCKFILE__
13 #define __AUDACITY_BLOCKFILE__
14 
15 #include "MemoryX.h"
16 #include <wx/string.h>
17 #include <wx/ffile.h>
18 #include <wx/filename.h>
19 
20 #include "xml/XMLTagHandler.h"
21 #include "xml/XMLWriter.h"
22 
23 #include "SampleFormat.h"
24 
25 #include "wxFileNameWrapper.h"
26 
27 #include "ondemand/ODTaskThread.h"
28 
29 
30 class SummaryInfo {
31  public:
32  SummaryInfo(size_t samples);
33 
34  int fields; /* Usually 3 for Min, Max, RMS */
35  sampleFormat format;
37  size_t frames64K;
38  int offset64K;
39  size_t frames256;
40  int offset256;
42 };
43 
44 
45 
46 class BlockFile;
47 class AliasBlockFile;
48 using BlockFilePtr = std::shared_ptr<BlockFile>;
49 
50 template< typename Result, typename... Args >
51 inline std::shared_ptr< Result > make_blockfile (Args && ... args)
52 {
53  return std::make_shared< Result > ( std::forward< Args > ( args )... );
54 }
55 
56 class PROFILE_DLL_API BlockFile /* not final, abstract */ {
57  public:
58 
59  // Constructor / Destructor
60 
62  BlockFile(wxFileNameWrapper &&fileName, size_t samples);
63  virtual ~BlockFile();
64 
65  static unsigned long gBlockFileDestructionCount;
66 
67  // Reading
68 
73  virtual size_t ReadData(samplePtr data, sampleFormat format,
74  size_t start, size_t len, bool mayThrow = true)
75  const = 0;
76 
77  // Other Properties
78 
79  // Write cache to disk, if it has any
80  virtual bool GetNeedWriteCacheToDisk() { return false; }
81  virtual void WriteCacheToDisk() { /* no cache by default */ }
82 
83  // Fill read cache of block file, if it has any
84  virtual bool GetNeedFillCache() { return false; }
85 
86  virtual void FillCache() /* noexcept */ { /* no cache by default */ }
87 
89  virtual void SaveXML(XMLWriter &xmlFile) = 0;
90 
99  const wxFileName &name;
101 
102  GetFileNameResult(const wxFileName &name_, ODLocker &&locker = ODLocker{})
103  : name{ name_ }, mLocker{ std::move(locker) } {}
104 
105  GetFileNameResult(const GetFileNameResult&) PROHIBITED;
106  GetFileNameResult &operator= (const GetFileNameResult&) PROHIBITED;
107 
109  : name{ that.name }, mLocker{ std::move(that.mLocker) } {}
110  };
111  virtual GetFileNameResult GetFileName() const;
112  virtual void SetFileName(wxFileNameWrapper &&name);
113 
114  size_t GetLength() const { return mLen; }
115  void SetLength(size_t newLen) { mLen = newLen; }
116 
118  virtual void Lock();
120  virtual void Unlock();
122  virtual bool IsLocked();
123 
124  struct MinMaxRMS { float min, max, RMS; };
125 
127  virtual MinMaxRMS GetMinMaxRMS(size_t start, size_t len,
128  bool mayThrow = true) const;
130  virtual MinMaxRMS GetMinMaxRMS(bool mayThrow = true) const;
132  virtual bool Read256(float *buffer, size_t start, size_t len);
134  virtual bool Read64K(float *buffer, size_t start, size_t len);
135 
137  virtual bool IsAlias() const { return false; }
138 
140  virtual bool IsSummaryAvailable() const {return true;}
141 
143  virtual bool IsDataAvailable() const {return true;}
144 
146  virtual bool IsSummaryBeingComputed(){return false;}
147 
149  virtual BlockFilePtr Copy(wxFileNameWrapper &&newFileName) = 0;
150 
151  // Report disk space usage.
152  using DiskByteCount = unsigned long long;
153  virtual DiskByteCount GetSpaceUsage() const = 0;
154 
156  //summary only), write out a placeholder of silence data (missing
157  //.au) or mark the blockfile to deal some other way without spewing
158  //errors.
159  // May throw exceptions for i/o errors.
160  virtual void Recover() = 0;
162  //continue and the error persists, don't keep reporting it. The
163  //Object implements this functionality internally, but we want to
164  //be able to tell the logging to shut up from outside too.
165  void SilenceLog() const { mSilentLog = TRUE; }
166 
169  // not balanced by unlocking calls.
170  virtual void CloseLock(){Lock();}
171 
172  protected:
174  virtual void LockRead() const {}
176  virtual void UnlockRead() const {}
177 
178  struct ReadLocker { void operator () ( const BlockFile *p ) const {
179  if (p) p->LockRead(); } };
180  struct ReadUnlocker { void operator () ( const BlockFile *p ) const {
181  if (p) p->UnlockRead(); } };
182  using ReadLockBase =
184 
185  public:
186  class ReadLock : public ReadLockBase
187  {
188  friend BlockFile;
190  : ReadLockBase { p, u } {}
191  public:
192 #ifdef __AUDACITY_OLD_STD__
193  ReadLock (const ReadLock &that) : ReadLockBase( that ) {}
194  ReadLock &operator= (const ReadLock &that)
195  {
196  *((ReadLockBase*)this) = that;
197  return *this;
198  }
199 #endif
200  ReadLock(ReadLock&&that) : ReadLockBase{ std::move(that) } {}
201  using Suspension = std::unique_ptr< const BlockFile, ReadLocker >;
203  { if (get()) get()->UnlockRead();
204  return Suspension{ get(), ReadLocker{} }; }
205  };
206 
207  // RAII wrapper about the read locking functions
208  ReadLock LockForRead() const { LockRead(); return { this, ReadUnlocker{} }; }
209 
210  private:
211 
212  protected:
215  virtual void *CalcSummary(samplePtr buffer, size_t len,
216  sampleFormat format,
217  // This gets filled, if the caller needs to deallocate. Else it is null.
218  ArrayOf<char> &cleanup);
219  // Common, nonvirtual calculation routine for the use of the above
220  void CalcSummaryFromBuffer(const float *fbuffer, size_t len,
221  float *summary256, float *summary64K);
222 
224  virtual bool ReadSummary(ArrayOf<char> &data) = 0;
225 
228  virtual void FixSummary(void *data);
229 
230  static size_t CommonReadData(
231  bool mayThrow,
232  const wxFileName &fileName, bool &mSilentLog,
233  const AliasBlockFile *pAliasFile, sampleCount origin, unsigned channel,
234  samplePtr data, sampleFormat format, size_t start, size_t len,
235  const sampleFormat *pLegacyFormat = nullptr, size_t legacyLen = 0);
236 
237  private:
239 
241 
242  protected:
244  size_t mLen;
246  float mMin, mMax, mRMS;
247  mutable bool mSilentLog;
248 };
249 
251 
259 class AliasBlockFile /* not final */ : public BlockFile
260 {
261  public:
262 
263  // Constructor / Destructor
264 
266  AliasBlockFile(wxFileNameWrapper &&baseFileName,
267  wxFileNameWrapper &&aliasedFileName, sampleCount aliasStart,
268  size_t aliasLen, int aliasChannel);
269  AliasBlockFile(wxFileNameWrapper &&existingSummaryFileName,
270  wxFileNameWrapper &&aliasedFileName, sampleCount aliasStart,
271  size_t aliasLen, int aliasChannel,
272  float min, float max, float RMS);
273  virtual ~AliasBlockFile();
274 
275  // Reading
276 
277  DiskByteCount GetSpaceUsage() const override;
278 
280  // applying to Alias file access
281  void SilenceAliasLog() const { mSilentAliasLog = TRUE; }
282 
283  //
284  // These methods are for advanced use only!
285  //
286  const wxFileName &GetAliasedFileName() const { return mAliasedFileName; }
287  void ChangeAliasedFileName(wxFileNameWrapper &&newAliasedFile);
288  bool IsAlias() const override { return true; }
289 
290  protected:
291  // Introduce a NEW virtual.
293  virtual void WriteSummary();
295  bool ReadSummary(ArrayOf<char> &data) override;
296 
298  sampleCount mAliasStart;
299  const int mAliasChannel;
300  mutable bool mSilentAliasLog;
301 };
302 
303 #endif
304 
virtual bool IsDataAvailable() const
Returns TRUE if this block's complete data is ready to be accessed by Read()
Definition: BlockFile.h:143
int bytesPerFrame
Definition: BlockFile.h:36
ReadLock LockForRead() const
Definition: BlockFile.h:208
sampleFormat format
Definition: BlockFile.h:35
virtual void UnlockRead() const
Allows reading on other threads.
Definition: BlockFile.h:176
virtual bool GetNeedWriteCacheToDisk()
Definition: BlockFile.h:80
std::unique_ptr< const BlockFile, ReadLocker > Suspension
Definition: BlockFile.h:201
const int mAliasChannel
Definition: BlockFile.h:299
#define PROHIBITED
Definition: Audacity.h:224
A BlockFile is a chunk of immutable audio data.
Definition: BlockFile.h:56
static unsigned long gBlockFileDestructionCount
Definition: BlockFile.h:65
wxFileNameWrapper mFileName
Definition: BlockFile.h:243
ReadLock(ReadLock &&that)
Definition: BlockFile.h:200
size_t frames256
Definition: BlockFile.h:39
int offset64K
Definition: BlockFile.h:38
virtual void LockRead() const
Prevents a read on other threads. The basic blockfile runs on only one thread, so does nothing...
Definition: BlockFile.h:174
Definition: MemoryX.h:699
void SilenceLog() const
if we've detected an on-disk problem, the user opted to
Definition: BlockFile.h:165
virtual bool IsAlias() const
Returns TRUE if this block references another disk file.
Definition: BlockFile.h:137
bool mSilentLog
Definition: BlockFile.h:247
bool ReadSummary(ArrayOf< char > &data) override
Read the summary into a buffer.
Definition: BlockFile.cpp:719
virtual bool IsSummaryBeingComputed()
Returns TRUE if the summary has not yet been written, but is actively being computed and written to d...
Definition: BlockFile.h:146
SummaryInfo mSummaryInfo
Definition: BlockFile.h:245
void SetLength(size_t newLen)
Definition: BlockFile.h:115
wxFileNameWrapper mAliasedFileName
Definition: BlockFile.h:297
virtual void WriteCacheToDisk()
Definition: BlockFile.h:81
virtual void FillCache()
Definition: BlockFile.h:86
Suspension Suspend() const
Definition: BlockFile.h:202
Definition: wxFileNameWrapper.h:16
ODLocker mLocker
Definition: BlockFile.h:100
AliasBlockFile(wxFileNameWrapper &&baseFileName, wxFileNameWrapper &&aliasedFileName, sampleCount aliasStart, size_t aliasLen, int aliasChannel)
Constructs an AliasBlockFile.
Definition: BlockFile.cpp:642
unsigned long long DiskByteCount
Definition: BlockFile.h:152
std::shared_ptr< BlockFile > BlockFilePtr
Definition: BlockFile.h:48
bool IsAlias() const override
Returns TRUE if this block references another disk file.
Definition: BlockFile.h:288
float RMS
Definition: BlockFile.h:124
size_t GetLength() const
Definition: BlockFile.h:114
const wxFileName & GetAliasedFileName() const
Definition: BlockFile.h:286
int format
Definition: ExportPCM.cpp:56
void ChangeAliasedFileName(wxFileNameWrapper &&newAliasedFile)
Definition: BlockFile.cpp:759
friend BlockFile
Definition: BlockFile.h:188
SummaryInfo(size_t samples)
Definition: BlockFile.cpp:73
Definition: BlockFile.h:186
Definition: BlockFile.h:98
Definition: ODTaskThread.h:182
float mRMS
Definition: BlockFile.h:246
Definition: BlockFile.h:178
Works with BlockFile to hold info about max and min and RMS over multiple samples, which in turn allows rapid drawing when zoomed out.
Definition: BlockFile.h:30
size_t totalSummaryBytes
Definition: BlockFile.h:41
GetFileNameResult(const wxFileName &name_, ODLocker &&locker=ODLocker{})
Definition: BlockFile.h:102
int min(int a, int b)
Definition: CompareAudioCommand.cpp:80
#define PROFILE_DLL_API
Definition: Audacity.h:146
bool mSilentAliasLog
Definition: BlockFile.h:300
sampleCount mAliasStart
Definition: BlockFile.h:298
size_t mLen
Definition: BlockFile.h:244
std::shared_ptr< Result > make_blockfile(Args &&...args)
Definition: BlockFile.h:51
int fields
Definition: BlockFile.h:34
size_t frames64K
Definition: BlockFile.h:37
virtual ~AliasBlockFile()
Definition: BlockFile.cpp:709
DiskByteCount GetSpaceUsage() const override
Definition: BlockFile.cpp:764
static ArrayOf< char > fullSummary
Definition: BlockFile.h:240
const wxChar * name
Definition: Distortion.cpp:93
A BlockFile that refers to data in an existing file.
Definition: BlockFile.h:259
virtual void CloseLock()
Definition: BlockFile.h:170
const wxFileName & name
Definition: BlockFile.h:99
int mLockCount
Definition: BlockFile.h:238
Definition: BlockFile.h:180
virtual void WriteSummary()
Write the summary to disk, using the derived ReadData() to get the data.
Definition: BlockFile.cpp:677
int offset256
Definition: BlockFile.h:40
Base class for XMLFileWriter and XMLStringWriter that provides the general functionality for creating...
Definition: XMLWriter.h:22
Definition: BlockFile.h:124
virtual bool GetNeedFillCache()
Definition: BlockFile.h:84
ReadLock(const BlockFile *p, const BlockFile::ReadUnlocker &u)
Definition: BlockFile.h:189
virtual bool IsSummaryAvailable() const
Returns TRUE if this block's complete summary has been computed and is ready (for OD) ...
Definition: BlockFile.h:140
void SilenceAliasLog() const
as SilentLog (which would affect Summary data access), but
Definition: BlockFile.h:281