Audacity  2.2.2
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 */
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 =
183  std::unique_ptr< const BlockFile, ReadUnlocker >;
184 
185  public:
186  class ReadLock : public ReadLockBase
187  {
188  friend BlockFile;
190  : ReadLockBase { p, u } {}
191  public:
192  ReadLock(ReadLock&&that) : ReadLockBase{ std::move(that) } {}
193  using Suspension = std::unique_ptr< const BlockFile, ReadLocker >;
195  { if (get()) get()->UnlockRead();
196  return Suspension{ get(), ReadLocker{} }; }
197  };
198 
199  // RAII wrapper about the read locking functions
200  ReadLock LockForRead() const { LockRead(); return { this, ReadUnlocker{} }; }
201 
202  private:
203 
204  protected:
207  virtual void *CalcSummary(samplePtr buffer, size_t len,
209  // This gets filled, if the caller needs to deallocate. Else it is null.
210  ArrayOf<char> &cleanup);
211  // Common, nonvirtual calculation routine for the use of the above
212  void CalcSummaryFromBuffer(const float *fbuffer, size_t len,
213  float *summary256, float *summary64K);
214 
216  virtual bool ReadSummary(ArrayOf<char> &data) = 0;
217 
220  virtual void FixSummary(void *data);
221 
222  static size_t CommonReadData(
223  bool mayThrow,
224  const wxFileName &fileName, bool &mSilentLog,
225  const AliasBlockFile *pAliasFile, sampleCount origin, unsigned channel,
226  samplePtr data, sampleFormat format, size_t start, size_t len,
227  const sampleFormat *pLegacyFormat = nullptr, size_t legacyLen = 0);
228 
229  private:
231 
233 
234  protected:
236  size_t mLen;
238  float mMin, mMax, mRMS;
239  mutable bool mSilentLog;
240 };
241 
243 
251 class AliasBlockFile /* not final */ : public BlockFile
252 {
253  public:
254 
255  // Constructor / Destructor
256 
258  AliasBlockFile(wxFileNameWrapper &&baseFileName,
259  wxFileNameWrapper &&aliasedFileName, sampleCount aliasStart,
260  size_t aliasLen, int aliasChannel);
261  AliasBlockFile(wxFileNameWrapper &&existingSummaryFileName,
262  wxFileNameWrapper &&aliasedFileName, sampleCount aliasStart,
263  size_t aliasLen, int aliasChannel,
264  float min, float max, float RMS);
265  virtual ~AliasBlockFile();
266 
267  // Reading
268 
269  DiskByteCount GetSpaceUsage() const override;
270 
272  // applying to Alias file access
273  void SilenceAliasLog() const { mSilentAliasLog = TRUE; }
274 
275  //
276  // These methods are for advanced use only!
277  //
278  const wxFileName &GetAliasedFileName() const { return mAliasedFileName; }
279  void ChangeAliasedFileName(wxFileNameWrapper &&newAliasedFile);
280  bool IsAlias() const override { return true; }
281 
282  protected:
283  // Introduce a NEW virtual.
285  virtual void WriteSummary();
287  bool ReadSummary(ArrayOf<char> &data) override;
288 
291  const int mAliasChannel;
292  mutable bool mSilentAliasLog;
293 };
294 
295 #endif
296 
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:200
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:193
const int mAliasChannel
Definition: BlockFile.h:291
#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:235
ReadLock(ReadLock &&that)
Definition: BlockFile.h:192
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
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:239
bool ReadSummary(ArrayOf< char > &data) override
Read the summary into a buffer.
Definition: BlockFile.cpp:717
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:237
void SetLength(size_t newLen)
Definition: BlockFile.h:115
wxFileNameWrapper mAliasedFileName
Definition: BlockFile.h:289
virtual void WriteCacheToDisk()
Definition: BlockFile.h:81
virtual void FillCache()
Definition: BlockFile.h:86
Suspension Suspend() const
Definition: BlockFile.h:194
AliasBlockFile(wxFileNameWrapper &&baseFileName, wxFileNameWrapper &&aliasedFileName, sampleCount aliasStart, size_t aliasLen, int aliasChannel)
Constructs an AliasBlockFile.
Definition: BlockFile.cpp:640
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:280
size_t GetLength() const
Definition: BlockFile.h:114
const wxFileName & GetAliasedFileName() const
Definition: BlockFile.h:278
int format
Definition: ExportPCM.cpp:56
void ChangeAliasedFileName(wxFileNameWrapper &&newAliasedFile)
Definition: BlockFile.cpp:757
SummaryInfo(size_t samples)
Definition: BlockFile.cpp:73
sampleFormat
Definition: Types.h:188
float mRMS
Definition: BlockFile.h:238
char * samplePtr
Definition: Types.h:203
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)
#define PROFILE_DLL_API
Definition: Audacity.h:176
bool mSilentAliasLog
Definition: BlockFile.h:292
sampleCount mAliasStart
Definition: BlockFile.h:290
size_t mLen
Definition: BlockFile.h:236
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:707
DiskByteCount GetSpaceUsage() const override
Definition: BlockFile.cpp:762
std::unique_ptr< const BlockFile, ReadUnlocker > ReadLockBase
Definition: BlockFile.h:183
static ArrayOf< char > fullSummary
Definition: BlockFile.h:232
const wxChar * name
Definition: Distortion.cpp:94
A BlockFile that refers to data in an existing file.
Definition: BlockFile.h:251
virtual void CloseLock()
Definition: BlockFile.h:170
const wxFileName & name
Definition: BlockFile.h:99
int mLockCount
Definition: BlockFile.h:230
virtual void WriteSummary()
Write the summary to disk, using the derived ReadData() to get the data.
Definition: BlockFile.cpp:675
int offset256
Definition: BlockFile.h:40
Base class for XMLFileWriter and XMLStringWriter that provides the general functionality for creating...
Definition: XMLWriter.h:22
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:273