/[svn]/libgig/trunk/src/RIFF.cpp

Diff of /libgig/trunk/src/RIFF.cpp

Parent Directory | Revision Log | View Patch Patch

-revision 3053 by schoenebeck,
Wed Dec 14 18:55:08 2016 UTC
+revision 3921 by schoenebeck,
Mon Jun 14 09:28:04 2021 UTC
 Line 2
   *                                                                         *
   *   libgig - C++ cross-platform Gigasampler format file access library    *
   *                                                                         *
-  *   Copyright (C) 2003-2016 by Christian Schoenebeck                      *
+  *   Copyright (C) 2003-2021 by Christian Schoenebeck                      *
   *                              <cuse@users.sourceforge.net>               *
   *                                                                         *
   *   This library is free software; you can redistribute it and/or modify  *
 Line 52 
 namespace RIFF {
          return sPath;
      }
+     inline static bool _isValidHandle(File::Handle handle) {
+         #if defined(WIN32)
+         return handle != INVALID_HANDLE_VALUE;
+         #else
+         return handle;
+         #endif
+     }
+     inline static void _close(File::Handle handle) {
+         if (!_isValidHandle(handle)) return;
+         #if POSIX
+         close(handle);
+         #elif defined(WIN32)
+         CloseHandle(handle);
+         #else
+         fclose(handle);
+         #endif
+     }
  // *************** progress_t ***************
-Line 64 
 namespace RIFF {
+Line 83 
 namespace RIFF {
          __range_max = 1.0f;
      }
+     /**
+      * Divides this progress task into the requested amount of equal weighted
+      * sub-progress tasks and returns a vector with those subprogress tasks.
+      *
+      * @param iSubtasks - total amount sub tasks this task should be subdivided
+      * @returns subtasks
+      */
+     std::vector<progress_t> progress_t::subdivide(int iSubtasks) {
+         std::vector<progress_t> v;
+         for (int i = 0; i < iSubtasks; ++i) {
+             progress_t p;
+             __divide_progress(this, &p, iSubtasks, i);
+             v.push_back(p);
+         }
+         return v;
+     }
+     /**
+      * Divides this progress task into the requested amount of sub-progress
+      * tasks, where each one of those new sub-progress tasks is created with its
+      * requested individual weight / portion, and finally returns a vector
+      * with those new subprogress tasks.
+      *
+      * The amount of subprogresses to be created is determined by this method
+      * by calling @c vSubTaskPortions.size() .
+      *
+      * Example: consider you wanted to create 3 subprogresses where the 1st
+      * subtask should be assigned 10% of the new 3 subprogresses' overall
+      * progress, the 2nd subtask should be assigned 50% of the new 3
+      * subprogresses' overall progress, and the 3rd subtask should be assigned
+      * 40%, then you might call this method like this:
+      * @code
+      * std::vector<progress_t> subprogresses = progress.subdivide({0.1, 0.5, 0.4});
+      * @endcode
+      *
+      * @param vSubTaskPortions - amount and individual weight of subtasks to be
+      *                           created
+      * @returns subtasks
+      */
+     std::vector<progress_t> progress_t::subdivide(std::vector<float> vSubTaskPortions) {
+         float fTotal = 0.f; // usually 1.0, but we sum the portions up below to be sure
+         for (int i = 0; i < vSubTaskPortions.size(); ++i)
+             fTotal += vSubTaskPortions[i];
+         float fLow = 0.f, fHigh = 0.f;
+         std::vector<progress_t> v;
+         for (int i = 0; i < vSubTaskPortions.size(); ++i) {
+             fLow  = fHigh;
+             fHigh = vSubTaskPortions[i];
+             progress_t p;
+             __divide_progress(this, &p, fTotal, fLow, fHigh);
+             v.push_back(p);
+         }
+         return v;
+     }
  // *************** Chunk **************
  // *
      Chunk::Chunk(File* pFile) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::Chunk(File* pFile)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
-         ullPos     = 0;
+         chunkPos.ullPos = 0;
          pParent    = NULL;
          pChunkData = NULL;
          ullCurrentChunkSize = 0;
-Line 84 
 namespace RIFF {
+Line 159 
 namespace RIFF {
      }
      Chunk::Chunk(File* pFile, file_offset_t StartPos, List* Parent) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::Chunk(File*,file_offset_t,List*),StartPos=" << StartPos << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          this->pFile   = pFile;
          ullStartPos   = StartPos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize);
          pParent       = Parent;
-         ullPos        = 0;
+         chunkPos.ullPos = 0;
          pChunkData    = NULL;
          ullCurrentChunkSize = 0;
          ullNewChunkSize = 0;
-Line 102 
 namespace RIFF {
+Line 177 
 namespace RIFF {
          this->pFile      = pFile;
          ullStartPos      = 0; // arbitrary usually, since it will be updated when we write the chunk
          this->pParent    = pParent;
-         ullPos           = 0;
+         chunkPos.ullPos  = 0;
          pChunkData       = NULL;
          ChunkID          = uiChunkID;
          ullChunkDataSize = 0;
-Line 115 
 namespace RIFF {
+Line 190 
 namespace RIFF {
      }
      void Chunk::ReadHeader(file_offset_t filePos) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::Readheader(" << filePos << ") ";
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          ChunkID = 0;
          ullNewChunkSize = ullCurrentChunkSize = 0;
+         const File::Handle hRead = pFile->FileHandle();
          #if POSIX
-         if (lseek(pFile->hFileRead, filePos, SEEK_SET) != -1) {
+         if (lseek(hRead, filePos, SEEK_SET) != -1) {
-             read(pFile->hFileRead, &ChunkID, 4);
+             read(hRead, &ChunkID, 4);
-             read(pFile->hFileRead, &ullCurrentChunkSize, pFile->FileOffsetSize);
+             read(hRead, &ullCurrentChunkSize, pFile->FileOffsetSize);
          #elif defined(WIN32)
          LARGE_INTEGER liFilePos;
          liFilePos.QuadPart = filePos;
-         if (SetFilePointerEx(pFile->hFileRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN)) {
+         if (SetFilePointerEx(hRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN)) {
              DWORD dwBytesRead;
-             ReadFile(pFile->hFileRead, &ChunkID, 4, &dwBytesRead, NULL);
+             ReadFile(hRead, &ChunkID, 4, &dwBytesRead, NULL);
-             ReadFile(pFile->hFileRead, &ullCurrentChunkSize, pFile->FileOffsetSize, &dwBytesRead, NULL);
+             ReadFile(hRead, &ullCurrentChunkSize, pFile->FileOffsetSize, &dwBytesRead, NULL);
          #else
-         if (!fseeko(pFile->hFileRead, filePos, SEEK_SET)) {
+         if (!fseeko(hRead, filePos, SEEK_SET)) {
-             fread(&ChunkID, 4, 1, pFile->hFileRead);
+             fread(&ChunkID, 4, 1, hRead);
-             fread(&ullCurrentChunkSize, pFile->FileOffsetSize, 1, pFile->hFileRead);
+             fread(&ullCurrentChunkSize, pFile->FileOffsetSize, 1, hRead);
          #endif // POSIX
              #if WORDS_BIGENDIAN
              if (ChunkID == CHUNK_ID_RIFF) {
-Line 153 
 namespace RIFF {
+Line 231 
 namespace RIFF {
                  else
                      swapBytes_64(&ullCurrentChunkSize);
              }
-             #if DEBUG
+             #if DEBUG_RIFF
              std::cout << "ckID=" << convertToString(ChunkID) << " ";
              std::cout << "ckSize=" << ullCurrentChunkSize << " ";
              std::cout << "bEndianNative=" << pFile->bEndianNative << std::endl;
-             #endif // DEBUG
+             #endif // DEBUG_RIFF
              ullNewChunkSize = ullCurrentChunkSize;
          }
      }
-Line 180 
 namespace RIFF {
+Line 258 
 namespace RIFF {
                  swapBytes_64(&ullNewChunkSize);
          }
+         const File::Handle hWrite = pFile->FileWriteHandle();
          #if POSIX
-         if (lseek(pFile->hFileWrite, filePos, SEEK_SET) != -1) {
+         if (lseek(hWrite, filePos, SEEK_SET) != -1) {
-             write(pFile->hFileWrite, &uiNewChunkID, 4);
+             write(hWrite, &uiNewChunkID, 4);
-             write(pFile->hFileWrite, &ullNewChunkSize, pFile->FileOffsetSize);
+             write(hWrite, &ullNewChunkSize, pFile->FileOffsetSize);
          }
          #elif defined(WIN32)
          LARGE_INTEGER liFilePos;
          liFilePos.QuadPart = filePos;
-         if (SetFilePointerEx(pFile->hFileWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN)) {
+         if (SetFilePointerEx(hWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN)) {
              DWORD dwBytesWritten;
-             WriteFile(pFile->hFileWrite, &uiNewChunkID, 4, &dwBytesWritten, NULL);
+             WriteFile(hWrite, &uiNewChunkID, 4, &dwBytesWritten, NULL);
-             WriteFile(pFile->hFileWrite, &ullNewChunkSize, pFile->FileOffsetSize, &dwBytesWritten, NULL);
+             WriteFile(hWrite, &ullNewChunkSize, pFile->FileOffsetSize, &dwBytesWritten, NULL);
          }
          #else
-         if (!fseeko(pFile->hFileWrite, filePos, SEEK_SET)) {
+         if (!fseeko(hWrite, filePos, SEEK_SET)) {
-             fwrite(&uiNewChunkID, 4, 1, pFile->hFileWrite);
+             fwrite(&uiNewChunkID, 4, 1, hWrite);
-             fwrite(&ullNewChunkSize, pFile->FileOffsetSize, 1, pFile->hFileWrite);
+             fwrite(&ullNewChunkSize, pFile->FileOffsetSize, 1, hWrite);
          }
          #endif // POSIX
      }
-Line 210 
 namespace RIFF {
+Line 290 
 namespace RIFF {
      }
      /**
+      * This is an internal-only method which must not be used by any application
+      * and might change at any time.
+      *
+      * Returns a reference (memory location) of the chunk's current file
+      * (read/write) position variable which depends on the current value of
+      * File::IsIOPerThread().
+      */
+     file_offset_t& Chunk::GetPosUnsafeRef() {
+         if (!pFile->IsIOPerThread()) return chunkPos.ullPos;
+         const std::thread::id tid = std::this_thread::get_id();
+         return chunkPos.byThread[tid];
+     }
+     /**
+      * Current read/write position within the chunk data body (starting with 0).
+      *
+      * @see File::IsIOPerThread() for multi-threaded streaming
+      */
+     file_offset_t Chunk::GetPos() const {
+         if (!pFile->IsIOPerThread()) return chunkPos.ullPos;
+         const std::thread::id tid = std::this_thread::get_id();
+         std::lock_guard<std::mutex> lock(chunkPos.mutex);
+         return chunkPos.byThread[tid];
+     }
+     /**
+      * Current, actual offset in file of current chunk data body read/write
+      * position.
+      *
+      * @see File::IsIOPerThread() for multi-threaded streaming
+      */
+     file_offset_t Chunk::GetFilePos() const {
+         return ullStartPos + GetPos();
+     }
+     /**
       *  Sets the position within the chunk body, thus within the data portion
       *  of the chunk (in bytes).
       *
-Line 220 
 namespace RIFF {
+Line 336 
 namespace RIFF {
       *  @param Whence - optional: defines to what <i>\a Where</i> relates to,
       *                  if omitted \a Where relates to beginning of the chunk
       *                  data
+      *  @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::SetPos(file_offset_t Where, stream_whence_t Whence) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::SetPos(file_offset_t,stream_whence_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
+         std::lock_guard<std::mutex> lock(chunkPos.mutex);
+         file_offset_t& pos = GetPosUnsafeRef();
          switch (Whence) {
              case stream_curpos:
-                 ullPos += Where;
+                 pos += Where;
                  break;
              case stream_end:
-                 ullPos = ullCurrentChunkSize - 1 - Where;
+                 pos = ullCurrentChunkSize - 1 - Where;
                  break;
              case stream_backward:
-                 ullPos -= Where;
+                 pos -= Where;
                  break;
              case stream_start: default:
-                 ullPos = Where;
+                 pos = Where;
                  break;
          }
-         if (ullPos > ullCurrentChunkSize) ullPos = ullCurrentChunkSize;
+         if (pos > ullCurrentChunkSize) pos = ullCurrentChunkSize;
-         return ullPos;
+         return pos;
      }
      /**
-Line 252 
 namespace RIFF {
+Line 371 
 namespace RIFF {
       *  of the chunk data.
       *
       *  @returns  number of bytes left to read
+      *  @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::RemainingBytes() const {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::Remainingbytes()=" << ullCurrentChunkSize - ullPos << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
-         return (ullCurrentChunkSize > ullPos) ? ullCurrentChunkSize - ullPos : 0;
+         const file_offset_t pos = GetPos();
+         return (ullCurrentChunkSize > pos) ? ullCurrentChunkSize - pos : 0;
      }
      /**
-Line 283 
 namespace RIFF {
+Line 404 
 namespace RIFF {
       *  - RIFF::stream_end_reached :
       *    already reached the end of the chunk data, no more reading
       *    possible without SetPos()
+      *
+      *  @see File::IsIOPerThread() for multi-threaded streaming
       */
      stream_state_t Chunk::GetState() const {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::GetState()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
-         #if POSIX
-         if (pFile->hFileRead == 0) return stream_closed;
+         const File::Handle hRead = pFile->FileHandle();
-         #elif defined (WIN32)
-         if (pFile->hFileRead == INVALID_HANDLE_VALUE)
+         if (!_isValidHandle(hRead))
              return stream_closed;
-         #else
-         if (pFile->hFileRead == NULL) return stream_closed;
+         const file_offset_t pos = GetPos();
-         #endif // POSIX
+         if (pos < ullCurrentChunkSize)    return stream_ready;
-         if (ullPos < ullCurrentChunkSize) return stream_ready;
          else                              return stream_end_reached;
      }
-Line 314 
 namespace RIFF {
+Line 436 
 namespace RIFF {
       *  @param WordSize   size of each data word to read
       *  @returns          number of successfully read data words or 0 if end
       *                    of file reached or error occurred
+      *  @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::Read(void* pData, file_offset_t WordCount, file_offset_t WordSize) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::Read(void*,file_offset_t,file_offset_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          //if (ulStartPos == 0) return 0; // is only 0 if this is a new chunk, so nothing to read (yet)
-         if (ullPos >= ullCurrentChunkSize) return 0;
+         const file_offset_t pos = GetPos();
-         if (ullPos + WordCount * WordSize >= ullCurrentChunkSize) WordCount = (ullCurrentChunkSize - ullPos) / WordSize;
+         if (pos >= ullCurrentChunkSize) return 0;
+         if (pos + WordCount * WordSize >= ullCurrentChunkSize)
+             WordCount = (ullCurrentChunkSize - pos) / WordSize;
+         const File::Handle hRead = pFile->FileHandle();
          #if POSIX
-         if (lseek(pFile->hFileRead, ullStartPos + ullPos, SEEK_SET) < 0) return 0;
+         if (lseek(hRead, ullStartPos + pos, SEEK_SET) < 0) return 0;
-         ssize_t readWords = read(pFile->hFileRead, pData, WordCount * WordSize);
+         ssize_t readWords = read(hRead, pData, WordCount * WordSize);
          if (readWords < 1) {
-             #if DEBUG
+             #if DEBUG_RIFF
              std::cerr << "POSIX read() failed: " << strerror(errno) << std::endl << std::flush;
-             #endif // DEBUG
+             #endif // DEBUG_RIFF
              return 0;
          }
          readWords /= WordSize;
          #elif defined(WIN32)
          LARGE_INTEGER liFilePos;
-         liFilePos.QuadPart = ullStartPos + ullPos;
+         liFilePos.QuadPart = ullStartPos + pos;
-         if (!SetFilePointerEx(pFile->hFileRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN))
+         if (!SetFilePointerEx(hRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN))
              return 0;
          DWORD readWords;
-         ReadFile(pFile->hFileRead, pData, WordCount * WordSize, &readWords, NULL); //FIXME: does not work for reading buffers larger than 2GB (even though this should rarely be the case in practice)
+         ReadFile(hRead, pData, WordCount * WordSize, &readWords, NULL); //FIXME: does not work for reading buffers larger than 2GB (even though this should rarely be the case in practice)
          if (readWords < 1) return 0;
          readWords /= WordSize;
          #else // standard C functions
-         if (fseeko(pFile->hFileRead, ullStartPos + ullPos, SEEK_SET)) return 0;
+         if (fseeko(hRead, ullStartPos + pos, SEEK_SET)) return 0;
-         file_offset_t readWords = fread(pData, WordSize, WordCount, pFile->hFileRead);
+         file_offset_t readWords = fread(pData, WordSize, WordCount, hRead);
          #endif // POSIX
          if (!pFile->bEndianNative && WordSize != 1) {
              switch (WordSize) {
-Line 384 
 namespace RIFF {
+Line 512 
 namespace RIFF {
       *  @throws RIFF::Exception  if write operation would exceed current
       *                           chunk size or any IO error occurred
       *  @see Resize()
+      *  @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::Write(void* pData, file_offset_t WordCount, file_offset_t WordSize) {
-         if (pFile->Mode != stream_mode_read_write)
+         const File::HandlePair io = pFile->FileHandlePair();
+         if (io.Mode != stream_mode_read_write)
              throw Exception("Cannot write data to chunk, file has to be opened in read+write mode first");
-         if (ullPos >= ullCurrentChunkSize || ullPos + WordCount * WordSize > ullCurrentChunkSize)
+         const file_offset_t pos = GetPos();
+         if (pos >= ullCurrentChunkSize || pos + WordCount * WordSize > ullCurrentChunkSize)
              throw Exception("End of chunk reached while trying to write data");
          if (!pFile->bEndianNative && WordSize != 1) {
              switch (WordSize) {
-Line 411 
 namespace RIFF {
+Line 542 
 namespace RIFF {
              }
          }
          #if POSIX
-         if (lseek(pFile->hFileWrite, ullStartPos + ullPos, SEEK_SET) < 0) {
+         if (lseek(io.hWrite, ullStartPos + pos, SEEK_SET) < 0) {
-             throw Exception("Could not seek to position " + ToString(ullPos) +
+             throw Exception("Could not seek to position " + ToString(pos) +
-                             " in chunk (" + ToString(ullStartPos + ullPos) + " in file)");
+                             " in chunk (" + ToString(ullStartPos + pos) + " in file)");
          }
-         ssize_t writtenWords = write(pFile->hFileWrite, pData, WordCount * WordSize);
+         ssize_t writtenWords = write(io.hWrite, pData, WordCount * WordSize);
          if (writtenWords < 1) throw Exception("POSIX IO Error while trying to write chunk data");
          writtenWords /= WordSize;
          #elif defined(WIN32)
          LARGE_INTEGER liFilePos;
-         liFilePos.QuadPart = ullStartPos + ullPos;
+         liFilePos.QuadPart = ullStartPos + pos;
-         if (!SetFilePointerEx(pFile->hFileWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN)) {
+         if (!SetFilePointerEx(io.hWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN)) {
-             throw Exception("Could not seek to position " + ToString(ullPos) +
+             throw Exception("Could not seek to position " + ToString(pos) +
-                             " in chunk (" + ToString(ullStartPos + ullPos) + " in file)");
+                             " in chunk (" + ToString(ullStartPos + pos) + " in file)");
          }
          DWORD writtenWords;
-         WriteFile(pFile->hFileWrite, pData, WordCount * WordSize, &writtenWords, NULL); //FIXME: does not work for writing buffers larger than 2GB (even though this should rarely be the case in practice)
+         WriteFile(io.hWrite, pData, WordCount * WordSize, &writtenWords, NULL); //FIXME: does not work for writing buffers larger than 2GB (even though this should rarely be the case in practice)
          if (writtenWords < 1) throw Exception("Windows IO Error while trying to write chunk data");
          writtenWords /= WordSize;
          #else // standard C functions
-         if (fseeko(pFile->hFileWrite, ullStartPos + ullPos, SEEK_SET)) {
+         if (fseeko(io.hWrite, ullStartPos + pos, SEEK_SET)) {
-             throw Exception("Could not seek to position " + ToString(ullPos) +
+             throw Exception("Could not seek to position " + ToString(pos) +
-                             " in chunk (" + ToString(ullStartPos + ullPos) + " in file)");
+                             " in chunk (" + ToString(ullStartPos + pos) + " in file)");
          }
-         file_offset_t writtenWords = fwrite(pData, WordSize, WordCount, pFile->hFileWrite);
+         file_offset_t writtenWords = fwrite(pData, WordSize, WordCount, io.hWrite);
          #endif // POSIX
          SetPos(writtenWords * WordSize, stream_curpos);
          return writtenWords;
-Line 457 
 namespace RIFF {
+Line 588 
 namespace RIFF {
       * @returns                 number of read integers
       * @throws RIFF::Exception  if an error occurred or less than
       *                          \a WordCount integers could be read!
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::ReadInt8(int8_t* pData, file_offset_t WordCount) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadInt8(int8_t*,file_offset_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          return ReadSceptical(pData, WordCount, 1);
      }
-Line 478 
 namespace RIFF {
+Line 610 
 namespace RIFF {
       * @returns                 number of written integers
       * @throws RIFF::Exception  if an IO error occurred
       * @see Resize()
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::WriteInt8(int8_t* pData, file_offset_t WordCount) {
          return Write(pData, WordCount, 1);
-Line 494 
 namespace RIFF {
+Line 627 
 namespace RIFF {
       * @returns                 number of read integers
       * @throws RIFF::Exception  if an error occurred or less than
       *                          \a WordCount integers could be read!
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::ReadUint8(uint8_t* pData, file_offset_t WordCount) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadUint8(uint8_t*,file_offset_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          return ReadSceptical(pData, WordCount, 1);
      }
-Line 515 
 namespace RIFF {
+Line 649 
 namespace RIFF {
       * @returns                 number of written integers
       * @throws RIFF::Exception  if an IO error occurred
       * @see Resize()
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::WriteUint8(uint8_t* pData, file_offset_t WordCount) {
          return Write(pData, WordCount, 1);
-Line 531 
 namespace RIFF {
+Line 666 
 namespace RIFF {
       * @returns                 number of read integers
       * @throws RIFF::Exception  if an error occurred or less than
       *                          \a WordCount integers could be read!
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::ReadInt16(int16_t* pData, file_offset_t WordCount) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadInt16(int16_t*,file_offset_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          return ReadSceptical(pData, WordCount, 2);
      }
-Line 552 
 namespace RIFF {
+Line 688 
 namespace RIFF {
       * @returns                 number of written integers
       * @throws RIFF::Exception  if an IO error occurred
       * @see Resize()
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::WriteInt16(int16_t* pData, file_offset_t WordCount) {
          return Write(pData, WordCount, 2);
-Line 568 
 namespace RIFF {
+Line 705 
 namespace RIFF {
       * @returns                 number of read integers
       * @throws RIFF::Exception  if an error occurred or less than
       *                          \a WordCount integers could be read!
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::ReadUint16(uint16_t* pData, file_offset_t WordCount) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadUint16(uint16_t*,file_offset_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          return ReadSceptical(pData, WordCount, 2);
      }
-Line 589 
 namespace RIFF {
+Line 727 
 namespace RIFF {
       * @returns                 number of written integers
       * @throws RIFF::Exception  if an IO error occurred
       * @see Resize()
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::WriteUint16(uint16_t* pData, file_offset_t WordCount) {
          return Write(pData, WordCount, 2);
-Line 605 
 namespace RIFF {
+Line 744 
 namespace RIFF {
       * @returns                 number of read integers
       * @throws RIFF::Exception  if an error occurred or less than
       *                          \a WordCount integers could be read!
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::ReadInt32(int32_t* pData, file_offset_t WordCount) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadInt32(int32_t*,file_offset_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          return ReadSceptical(pData, WordCount, 4);
      }
-Line 626 
 namespace RIFF {
+Line 766 
 namespace RIFF {
       * @returns                 number of written integers
       * @throws RIFF::Exception  if an IO error occurred
       * @see Resize()
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::WriteInt32(int32_t* pData, file_offset_t WordCount) {
          return Write(pData, WordCount, 4);
-Line 642 
 namespace RIFF {
+Line 783 
 namespace RIFF {
       * @returns                 number of read integers
       * @throws RIFF::Exception  if an error occurred or less than
       *                          \a WordCount integers could be read!
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::ReadUint32(uint32_t* pData, file_offset_t WordCount) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadUint32(uint32_t*,file_offset_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          return ReadSceptical(pData, WordCount, 4);
      }
-Line 659 
 namespace RIFF {
+Line 801 
 namespace RIFF {
       * @param size              number of characters to read
       * @throws RIFF::Exception  if an error occurred or less than
       *                          \a size characters could be read!
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      void Chunk::ReadString(String& s, int size) {
          char* buf = new char[size];
-Line 680 
 namespace RIFF {
+Line 823 
 namespace RIFF {
       * @returns                 number of written integers
       * @throws RIFF::Exception  if an IO error occurred
       * @see Resize()
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::WriteUint32(uint32_t* pData, file_offset_t WordCount) {
          return Write(pData, WordCount, 4);
-Line 691 
 namespace RIFF {
+Line 835 
 namespace RIFF {
       *
       * @returns                 read integer word
       * @throws RIFF::Exception  if an error occurred
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      int8_t Chunk::ReadInt8() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadInt8()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          int8_t word;
          ReadSceptical(&word,1,1);
          return word;
-Line 707 
 namespace RIFF {
+Line 852 
 namespace RIFF {
       *
       * @returns                 read integer word
       * @throws RIFF::Exception  if an error occurred
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      uint8_t Chunk::ReadUint8() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadUint8()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          uint8_t word;
          ReadSceptical(&word,1,1);
          return word;
-Line 724 
 namespace RIFF {
+Line 870 
 namespace RIFF {
       *
       * @returns                 read integer word
       * @throws RIFF::Exception  if an error occurred
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      int16_t Chunk::ReadInt16() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadInt16()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          int16_t word;
          ReadSceptical(&word,1,2);
          return word;
-Line 741 
 namespace RIFF {
+Line 888 
 namespace RIFF {
       *
       * @returns                 read integer word
       * @throws RIFF::Exception  if an error occurred
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      uint16_t Chunk::ReadUint16() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadUint16()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          uint16_t word;
          ReadSceptical(&word,1,2);
          return word;
-Line 758 
 namespace RIFF {
+Line 906 
 namespace RIFF {
       *
       * @returns                 read integer word
       * @throws RIFF::Exception  if an error occurred
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      int32_t Chunk::ReadInt32() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadInt32()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          int32_t word;
          ReadSceptical(&word,1,4);
          return word;
-Line 775 
 namespace RIFF {
+Line 924 
 namespace RIFF {
       *
       * @returns                 read integer word
       * @throws RIFF::Exception  if an error occurred
+      * @see File::IsIOPerThread() for multi-threaded streamings
       */
      uint32_t Chunk::ReadUint32() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "Chunk::ReadUint32()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          uint32_t word;
          ReadSceptical(&word,1,4);
          return word;
-Line 805 
 namespace RIFF {
+Line 955 
 namespace RIFF {
       * @returns a pointer to the data in RAM on success, NULL otherwise
       * @throws Exception if data buffer could not be enlarged
       * @see ReleaseChunkData()
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      void* Chunk::LoadChunkData() {
          if (!pChunkData && pFile->Filename != "" /*&& ulStartPos != 0*/) {
+             File::Handle hRead = pFile->FileHandle();
              #if POSIX
-             if (lseek(pFile->hFileRead, ullStartPos, SEEK_SET) == -1) return NULL;
+             if (lseek(hRead, ullStartPos, SEEK_SET) == -1) return NULL;
              #elif defined(WIN32)
              LARGE_INTEGER liFilePos;
              liFilePos.QuadPart = ullStartPos;
-             if (!SetFilePointerEx(pFile->hFileRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN)) return NULL;
+             if (!SetFilePointerEx(hRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN)) return NULL;
              #else
-             if (fseeko(pFile->hFileRead, ullStartPos, SEEK_SET)) return NULL;
+             if (fseeko(hRead, ullStartPos, SEEK_SET)) return NULL;
              #endif // POSIX
              file_offset_t ullBufferSize = (ullCurrentChunkSize > ullNewChunkSize) ? ullCurrentChunkSize : ullNewChunkSize;
              pChunkData = new uint8_t[ullBufferSize];
              if (!pChunkData) return NULL;
              memset(pChunkData, 0, ullBufferSize);
              #if POSIX
-             file_offset_t readWords = read(pFile->hFileRead, pChunkData, GetSize());
+             file_offset_t readWords = read(hRead, pChunkData, GetSize());
              #elif defined(WIN32)
              DWORD readWords;
-             ReadFile(pFile->hFileRead, pChunkData, GetSize(), &readWords, NULL); //FIXME: won't load chunks larger than 2GB !
+             ReadFile(hRead, pChunkData, GetSize(), &readWords, NULL); //FIXME: won't load chunks larger than 2GB !
              #else
-             file_offset_t readWords = fread(pChunkData, 1, GetSize(), pFile->hFileRead);
+             file_offset_t readWords = fread(pChunkData, 1, GetSize(), hRead);
              #endif // POSIX
              if (readWords != GetSize()) {
                  delete[] pChunkData;
-Line 838 
 namespace RIFF {
+Line 990 
 namespace RIFF {
              uint8_t* pNewBuffer = new uint8_t[ullNewChunkSize];
              if (!pNewBuffer) throw Exception("Could not enlarge chunk data buffer to " + ToString(ullNewChunkSize) + " bytes");
              memset(pNewBuffer, 0 , ullNewChunkSize);
-             memcpy(pNewBuffer, pChunkData, ullChunkDataSize);
+             if (pChunkData) {
-             delete[] pChunkData;
+                 memcpy(pNewBuffer, pChunkData, ullChunkDataSize);
+                 delete[] pChunkData;
+             }
              pChunkData       = pNewBuffer;
              ullChunkDataSize = ullNewChunkSize;
          }
-Line 898 
 namespace RIFF {
+Line 1052 
 namespace RIFF {
       * @returns new write position in the "physical" file, that is
       *          \a ullWritePos incremented by this chunk's new size
       *          (including its header size of course)
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      file_offset_t Chunk::WriteChunk(file_offset_t ullWritePos, file_offset_t ullCurrentDataOffset, progress_t* pProgress) {
          const file_offset_t ullOriginalPos = ullWritePos;
          ullWritePos += CHUNK_HEADER_SIZE(pFile->FileOffsetSize);
-         if (pFile->Mode != stream_mode_read_write)
+         const File::HandlePair io = pFile->FileHandlePair();
+         if (io.Mode != stream_mode_read_write)
              throw Exception("Cannot write list chunk, file has to be opened in read+write mode");
          // if the whole chunk body was loaded into RAM
-Line 912 
 namespace RIFF {
+Line 1069 
 namespace RIFF {
              LoadChunkData();
              // write chunk data from RAM persistently to the file
              #if POSIX
-             lseek(pFile->hFileWrite, ullWritePos, SEEK_SET);
+             lseek(io.hWrite, ullWritePos, SEEK_SET);
-             if (write(pFile->hFileWrite, pChunkData, ullNewChunkSize) != ullNewChunkSize) {
+             if (write(io.hWrite, pChunkData, ullNewChunkSize) != ullNewChunkSize) {
                  throw Exception("Writing Chunk data (from RAM) failed");
              }
              #elif defined(WIN32)
              LARGE_INTEGER liFilePos;
              liFilePos.QuadPart = ullWritePos;
-             SetFilePointerEx(pFile->hFileWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
+             SetFilePointerEx(io.hWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
              DWORD dwBytesWritten;
-             WriteFile(pFile->hFileWrite, pChunkData, ullNewChunkSize, &dwBytesWritten, NULL); //FIXME: won't save chunks larger than 2GB !
+             WriteFile(io.hWrite, pChunkData, ullNewChunkSize, &dwBytesWritten, NULL); //FIXME: won't save chunks larger than 2GB !
              if (dwBytesWritten != ullNewChunkSize) {
                  throw Exception("Writing Chunk data (from RAM) failed");
              }
              #else
-             fseeko(pFile->hFileWrite, ullWritePos, SEEK_SET);
+             fseeko(io.hWrite, ullWritePos, SEEK_SET);
-             if (fwrite(pChunkData, 1, ullNewChunkSize, pFile->hFileWrite) != ullNewChunkSize) {
+             if (fwrite(pChunkData, 1, ullNewChunkSize, io.hWrite) != ullNewChunkSize) {
                  throw Exception("Writing Chunk data (from RAM) failed");
              }
              #endif // POSIX
-Line 943 
 namespace RIFF {
+Line 1100 
 namespace RIFF {
              for (file_offset_t ullOffset = 0; ullToMove > 0 && iBytesMoved > 0; ullOffset += iBytesMoved, ullToMove -= iBytesMoved) {
                  iBytesMoved = (ullToMove < 4096) ? int(ullToMove) : 4096;
                  #if POSIX
-                 lseek(pFile->hFileRead, ullStartPos + ullCurrentDataOffset + ullOffset, SEEK_SET);
+                 lseek(io.hRead, ullStartPos + ullCurrentDataOffset + ullOffset, SEEK_SET);
-                 iBytesMoved = (int) read(pFile->hFileRead, pCopyBuffer, (size_t) iBytesMoved);
+                 iBytesMoved = (int) read(io.hRead, pCopyBuffer, (size_t) iBytesMoved);
-                 lseek(pFile->hFileWrite, ullWritePos + ullOffset, SEEK_SET);
+                 lseek(io.hWrite, ullWritePos + ullOffset, SEEK_SET);
-                 iBytesMoved = (int) write(pFile->hFileWrite, pCopyBuffer, (size_t) iBytesMoved);
+                 iBytesMoved = (int) write(io.hWrite, pCopyBuffer, (size_t) iBytesMoved);
                  #elif defined(WIN32)
                  LARGE_INTEGER liFilePos;
                  liFilePos.QuadPart = ullStartPos + ullCurrentDataOffset + ullOffset;
-                 SetFilePointerEx(pFile->hFileRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
+                 SetFilePointerEx(io.hRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
-                 ReadFile(pFile->hFileRead, pCopyBuffer, iBytesMoved, &iBytesMoved, NULL);
+                 ReadFile(io.hRead, pCopyBuffer, iBytesMoved, &iBytesMoved, NULL);
                  liFilePos.QuadPart = ullWritePos + ullOffset;
-                 SetFilePointerEx(pFile->hFileWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
+                 SetFilePointerEx(io.hWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
-                 WriteFile(pFile->hFileWrite, pCopyBuffer, iBytesMoved, &iBytesMoved, NULL);
+                 WriteFile(io.hWrite, pCopyBuffer, iBytesMoved, &iBytesMoved, NULL);
                  #else
-                 fseeko(pFile->hFileRead, ullStartPos + ullCurrentDataOffset + ullOffset, SEEK_SET);
+                 fseeko(io.hRead, ullStartPos + ullCurrentDataOffset + ullOffset, SEEK_SET);
-                 iBytesMoved = fread(pCopyBuffer, 1, iBytesMoved, pFile->hFileRead);
+                 iBytesMoved = fread(pCopyBuffer, 1, iBytesMoved, io.hRead);
-                 fseeko(pFile->hFileWrite, ullWritePos + ullOffset, SEEK_SET);
+                 fseeko(io.hWrite, ullWritePos + ullOffset, SEEK_SET);
-                 iBytesMoved = fwrite(pCopyBuffer, 1, iBytesMoved, pFile->hFileWrite);
+                 iBytesMoved = fwrite(pCopyBuffer, 1, iBytesMoved, io.hWrite);
                  #endif
              }
              delete[] pCopyBuffer;
-Line 970 
 namespace RIFF {
+Line 1127 
 namespace RIFF {
          ullCurrentChunkSize = ullNewChunkSize;
          WriteHeader(ullOriginalPos);
-         __notify_progress(pProgress, 1.0); // notify done
+         if (pProgress)
+             __notify_progress(pProgress, 1.0); // notify done
          // update chunk's position pointers
          ullStartPos = ullOriginalPos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize);
-         ullPos      = 0;
+         Chunk::__resetPos();
          // add pad byte if needed
          if ((ullStartPos + ullNewChunkSize) % 2 != 0) {
              const char cPadByte = 0;
              #if POSIX
-             lseek(pFile->hFileWrite, ullStartPos + ullNewChunkSize, SEEK_SET);
+             lseek(io.hWrite, ullStartPos + ullNewChunkSize, SEEK_SET);
-             write(pFile->hFileWrite, &cPadByte, 1);
+             write(io.hWrite, &cPadByte, 1);
              #elif defined(WIN32)
              LARGE_INTEGER liFilePos;
              liFilePos.QuadPart = ullStartPos + ullNewChunkSize;
-             SetFilePointerEx(pFile->hFileWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
+             SetFilePointerEx(io.hWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
              DWORD dwBytesWritten;
-             WriteFile(pFile->hFileWrite, &cPadByte, 1, &dwBytesWritten, NULL);
+             WriteFile(io.hWrite, &cPadByte, 1, &dwBytesWritten, NULL);
              #else
-             fseeko(pFile->hFileWrite, ullStartPos + ullNewChunkSize, SEEK_SET);
+             fseeko(io.hWrite, ullStartPos + ullNewChunkSize, SEEK_SET);
-             fwrite(&cPadByte, 1, 1, pFile->hFileWrite);
+             fwrite(&cPadByte, 1, 1, io.hWrite);
              #endif
              return ullStartPos + ullNewChunkSize + 1;
          }
-Line 999 
 namespace RIFF {
+Line 1157 
 namespace RIFF {
      }
      void Chunk::__resetPos() {
-         ullPos = 0;
+         std::lock_guard<std::mutex> lock(chunkPos.mutex);
+         chunkPos.ullPos = 0;
+         chunkPos.byThread.clear();
      }
-Line 1008 
 namespace RIFF {
+Line 1168 
 namespace RIFF {
  // *
      List::List(File* pFile) : Chunk(pFile) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::List(File* pFile)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          pSubChunks    = NULL;
          pSubChunksMap = NULL;
      }
      List::List(File* pFile, file_offset_t StartPos, List* Parent)
        : Chunk(pFile, StartPos, Parent) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::List(File*,file_offset_t,List*)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          pSubChunks    = NULL;
          pSubChunksMap = NULL;
          ReadHeader(StartPos);
-Line 1034 
 namespace RIFF {
+Line 1194 
 namespace RIFF {
      }
      List::~List() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::~List()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          DeleteChunkList();
      }
-Line 1058 
 namespace RIFF {
+Line 1218 
 namespace RIFF {
      }
      /**
+      *  Returns subchunk at supplied @a pos position within this chunk list.
+      *  If supplied @a pos is out of bounds then @c NULL is returned. The
+      *  returned subchunk can either by an ordinary data chunk or a list chunk.
+      *
+      *  @param pos - position of sought subchunk within this list
+      *  @returns pointer to the subchunk or NULL if supplied position is not
+      *           within the valid range of this list
+      */
+     Chunk* List::GetSubChunkAt(size_t pos) {
+         if (!pSubChunks) LoadSubChunks();
+         if (pos >= pSubChunks->size()) return NULL;
+         return (*pSubChunks)[pos];
+     }
+     /**
       *  Returns subchunk with chunk ID <i>\a ChunkID</i> within this chunk
       *  list. Use this method if you expect only one subchunk of that type in
       *  the list. It there are more than one, it's undetermined which one of
-Line 1069 
 namespace RIFF {
+Line 1244 
 namespace RIFF {
       *                   that ID
       */
      Chunk* List::GetSubChunk(uint32_t ChunkID) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::GetSubChunk(uint32_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          if (!pSubChunksMap) LoadSubChunks();
          return (*pSubChunksMap)[ChunkID];
      }
      /**
+      *  Returns sublist chunk with list type <i>\a ListType</i> at supplied
+      *  @a pos position among all subchunks of type <i>\a ListType</i> within
+      *  this chunk list. If supplied @a pos is out of bounds then @c NULL is
+      *  returned.
+      *
+      *  @param pos - position of sought sublist within this list
+      *  @returns pointer to the sublist or NULL if if supplied position is not
+      *           within valid range
+      */
+     List* List::GetSubListAt(size_t pos) {
+         if (!pSubChunks) LoadSubChunks();
+         if (pos >= pSubChunks->size()) return NULL;
+         for (size_t iCk = 0, iLst = 0; iCk < pSubChunks->size(); ++iCk) {
+             Chunk* pChunk = (*pSubChunks)[iCk];
+             if (pChunk->GetChunkID() != CHUNK_ID_LIST) continue;
+             if (iLst == pos) return (List*) pChunk;
+             ++iLst;
+         }
+         return NULL;
+     }
+     /**
       *  Returns sublist chunk with list type <i>\a ListType</i> within this
       *  chunk list. Use this method if you expect only one sublist chunk of
       *  that type in the list. If there are more than one, it's undetermined
-Line 1088 
 namespace RIFF {
+Line 1285 
 namespace RIFF {
       *                    that type
       */
      List* List::GetSubList(uint32_t ListType) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::GetSubList(uint32_t)" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          if (!pSubChunks) LoadSubChunks();
          ChunkList::iterator iter = pSubChunks->begin();
          ChunkList::iterator end  = pSubChunks->end();
-Line 1112 
 namespace RIFF {
+Line 1309 
 namespace RIFF {
       *
       *  @returns  pointer to the first subchunk within the list, NULL
       *            otherwise
+      *  @deprecated  This method is not reentrant-safe, use GetSubChunkAt()
+      *               instead.
       */
      Chunk* List::GetFirstSubChunk() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::GetFirstSubChunk()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          if (!pSubChunks) LoadSubChunks();
          ChunksIterator = pSubChunks->begin();
          return (ChunksIterator != pSubChunks->end()) ? *ChunksIterator : NULL;
-Line 1129 
 namespace RIFF {
+Line 1328 
 namespace RIFF {
       *
       *  @returns  pointer to the next subchunk within the list or NULL if
       *            end of list is reached
+      *  @deprecated  This method is not reentrant-safe, use GetSubChunkAt()
+      *               instead.
       */
      Chunk* List::GetNextSubChunk() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::GetNextSubChunk()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          if (!pSubChunks) return NULL;
          ChunksIterator++;
          return (ChunksIterator != pSubChunks->end()) ? *ChunksIterator : NULL;
-Line 1147 
 namespace RIFF {
+Line 1348 
 namespace RIFF {
       *
       *  @returns  pointer to the first sublist within the list, NULL
       *            otherwise
+      *  @deprecated  This method is not reentrant-safe, use GetSubListAt()
+      *               instead.
       */
      List* List::GetFirstSubList() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::GetFirstSubList()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          if (!pSubChunks) LoadSubChunks();
          ListIterator            = pSubChunks->begin();
          ChunkList::iterator end = pSubChunks->end();
-Line 1169 
 namespace RIFF {
+Line 1372 
 namespace RIFF {
       *
       *  @returns  pointer to the next sublist within the list, NULL if
       *            end of list is reached
+      *  @deprecated  This method is not reentrant-safe, use GetSubListAt()
+      *               instead.
       */
      List* List::GetNextSubList() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::GetNextSubList()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          if (!pSubChunks) return NULL;
          if (ListIterator == pSubChunks->end()) return NULL;
          ListIterator++;
-Line 1274 
 namespace RIFF {
+Line 1479 
 namespace RIFF {
       */
      void List::MoveSubChunk(Chunk* pSrc, Chunk* pDst) {
          if (!pSubChunks) LoadSubChunks();
-         pSubChunks->remove(pSrc);
+         for (size_t i = 0; i < pSubChunks->size(); ++i) {
-         ChunkList::iterator iter = find(pSubChunks->begin(), pSubChunks->end(), pDst);
+             if ((*pSubChunks)[i] == pSrc) {
-         pSubChunks->insert(iter, pSrc);
+                 pSubChunks->erase(pSubChunks->begin() + i);
+                 ChunkList::iterator iter =
+                     find(pSubChunks->begin(), pSubChunks->end(), pDst);
+                 pSubChunks->insert(iter, pSrc);
+                 return;
+             }
+         }
      }
      /** @brief Moves a sub chunk from this list to another list.
-Line 1291 
 namespace RIFF {
+Line 1502 
 namespace RIFF {
          if (pNewParent == this || !pNewParent) return;
          if (!pSubChunks) LoadSubChunks();
          if (!pNewParent->pSubChunks) pNewParent->LoadSubChunks();
-         pSubChunks->remove(pSrc);
+         ChunkList::iterator iter =
+             find(pSubChunks->begin(), pSubChunks->end(), pSrc);
+         if (iter == pSubChunks->end()) return;
+         pSubChunks->erase(iter);
          pNewParent->pSubChunks->push_back(pSrc);
          // update chunk id map of this List
          if ((*pSubChunksMap)[pSrc->GetChunkID()] == pSrc) {
-Line 1341 
 namespace RIFF {
+Line 1555 
 namespace RIFF {
       */
      void List::DeleteSubChunk(Chunk* pSubChunk) {
          if (!pSubChunks) LoadSubChunks();
-         pSubChunks->remove(pSubChunk);
+         ChunkList::iterator iter =
+             find(pSubChunks->begin(), pSubChunks->end(), pSubChunk);
+         if (iter == pSubChunks->end()) return;
+         pSubChunks->erase(iter);
          if ((*pSubChunksMap)[pSubChunk->GetChunkID()] == pSubChunk) {
              pSubChunksMap->erase(pSubChunk->GetChunkID());
              // try to find another chunk of the same chunk ID
-Line 1375 
 namespace RIFF {
+Line 1592 
 namespace RIFF {
      }
      void List::ReadHeader(file_offset_t filePos) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::Readheader(file_offset_t) ";
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          Chunk::ReadHeader(filePos);
          if (ullCurrentChunkSize < 4) return;
          ullNewChunkSize = ullCurrentChunkSize -= 4;
+         const File::Handle hRead = pFile->FileHandle();
          #if POSIX
-         lseek(pFile->hFileRead, filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize), SEEK_SET);
+         lseek(hRead, filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize), SEEK_SET);
-         read(pFile->hFileRead, &ListType, 4);
+         read(hRead, &ListType, 4);
          #elif defined(WIN32)
          LARGE_INTEGER liFilePos;
          liFilePos.QuadPart = filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize);
-         SetFilePointerEx(pFile->hFileRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
+         SetFilePointerEx(hRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
          DWORD dwBytesRead;
-         ReadFile(pFile->hFileRead, &ListType, 4, &dwBytesRead, NULL);
+         ReadFile(hRead, &ListType, 4, &dwBytesRead, NULL);
          #else
-         fseeko(pFile->hFileRead, filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize), SEEK_SET);
+         fseeko(hRead, filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize), SEEK_SET);
-         fread(&ListType, 4, 1, pFile->hFileRead);
+         fread(&ListType, 4, 1, hRead);
          #endif // POSIX
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "listType=" << convertToString(ListType) << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          if (!pFile->bEndianNative) {
              //swapBytes_32(&ListType);
          }
-Line 1407 
 namespace RIFF {
+Line 1627 
 namespace RIFF {
          ullNewChunkSize += 4;
          Chunk::WriteHeader(filePos);
          ullNewChunkSize -= 4; // just revert the +4 incrementation
+         const File::Handle hWrite = pFile->FileWriteHandle();
          #if POSIX
-         lseek(pFile->hFileWrite, filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize), SEEK_SET);
+         lseek(hWrite, filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize), SEEK_SET);
-         write(pFile->hFileWrite, &ListType, 4);
+         write(hWrite, &ListType, 4);
          #elif defined(WIN32)
          LARGE_INTEGER liFilePos;
          liFilePos.QuadPart = filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize);
-         SetFilePointerEx(pFile->hFileWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
+         SetFilePointerEx(hWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
          DWORD dwBytesWritten;
-         WriteFile(pFile->hFileWrite, &ListType, 4, &dwBytesWritten, NULL);
+         WriteFile(hWrite, &ListType, 4, &dwBytesWritten, NULL);
          #else
-         fseeko(pFile->hFileWrite, filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize), SEEK_SET);
+         fseeko(hWrite, filePos + CHUNK_HEADER_SIZE(pFile->FileOffsetSize), SEEK_SET);
-         fwrite(&ListType, 4, 1, pFile->hFileWrite);
+         fwrite(&ListType, 4, 1, hWrite);
          #endif // POSIX
      }
      void List::LoadSubChunks(progress_t* pProgress) {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "List::LoadSubChunks()";
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          if (!pSubChunks) {
              pSubChunks    = new ChunkList();
              pSubChunksMap = new ChunkMap();
-             #if defined(WIN32)
-             if (pFile->hFileRead == INVALID_HANDLE_VALUE) return;
+             const File::Handle hRead = pFile->FileHandle();
-             #else
+             if (!_isValidHandle(hRead)) return;
-             if (!pFile->hFileRead) return;
-             #endif
+             const file_offset_t ullOriginalPos = GetPos();
-             file_offset_t ullOriginalPos = GetPos();
              SetPos(0); // jump to beginning of list chunk body
              while (RemainingBytes() >= CHUNK_HEADER_SIZE(pFile->FileOffsetSize)) {
                  Chunk* ck;
                  uint32_t ckid;
-                 Read(&ckid, 4, 1);
+                 // return value check is required here to prevent a potential
-                 #if DEBUG
+                 // garbage data use of 'ckid' below in case Read() failed
+                 if (Read(&ckid, 4, 1) != 4)
+                     throw Exception("LoadSubChunks(): Failed reading RIFF chunk ID");
+                 #if DEBUG_RIFF
                  std::cout << " ckid=" << convertToString(ckid) << std::endl;
-                 #endif // DEBUG
+                 #endif // DEBUG_RIFF
+                 const file_offset_t pos = GetPos();
                  if (ckid == CHUNK_ID_LIST) {
-                     ck = new RIFF::List(pFile, ullStartPos + ullPos - 4, this);
+                     ck = new RIFF::List(pFile, ullStartPos + pos - 4, this);
                      SetPos(ck->GetSize() + LIST_HEADER_SIZE(pFile->FileOffsetSize) - 4, RIFF::stream_curpos);
                  }
                  else { // simple chunk
-                     ck = new RIFF::Chunk(pFile, ullStartPos + ullPos - 4, this);
+                     ck = new RIFF::Chunk(pFile, ullStartPos + pos - 4, this);
                      SetPos(ck->GetSize() + CHUNK_HEADER_SIZE(pFile->FileOffsetSize) - 4, RIFF::stream_curpos);
                  }
                  pSubChunks->push_back(ck);
-Line 1457 
 namespace RIFF {
+Line 1683 
 namespace RIFF {
              }
              SetPos(ullOriginalPos); // restore position before this call
          }
-         __notify_progress(pProgress, 1.0); // notify done
+         if (pProgress)
+             __notify_progress(pProgress, 1.0); // notify done
      }
      void List::LoadSubChunksRecursively(progress_t* pProgress) {
          const int n = (int) CountSubLists();
          int i = 0;
-         for (List* pList = GetFirstSubList(); pList; pList = GetNextSubList(), ++i) {
+         for (List* pList = GetSubListAt(i); pList; pList = GetSubListAt(++i)) {
-             // divide local progress into subprogress
+             if (pProgress) {
-             progress_t subprogress;
+                 // divide local progress into subprogress
-             __divide_progress(pProgress, &subprogress, n, i);
+                 progress_t subprogress;
-             // do the actual work
+                 __divide_progress(pProgress, &subprogress, n, i);
-             pList->LoadSubChunksRecursively(&subprogress);
+                 // do the actual work
+                 pList->LoadSubChunksRecursively(&subprogress);
+             } else
+                 pList->LoadSubChunksRecursively(NULL);
          }
-         __notify_progress(pProgress, 1.0); // notify done
+         if (pProgress)
+             __notify_progress(pProgress, 1.0); // notify done
      }
      /** @brief Write list chunk persistently e.g. to disk.
-Line 1492 
 namespace RIFF {
+Line 1723 
 namespace RIFF {
          const file_offset_t ullOriginalPos = ullWritePos;
          ullWritePos += LIST_HEADER_SIZE(pFile->FileOffsetSize);
-         if (pFile->Mode != stream_mode_read_write)
+         if (pFile->GetMode() != stream_mode_read_write)
              throw Exception("Cannot write list chunk, file has to be opened in read+write mode");
          // write all subchunks (including sub list chunks) recursively
-Line 1500 
 namespace RIFF {
+Line 1731 
 namespace RIFF {
              size_t i = 0;
              const size_t n = pSubChunks->size();
              for (ChunkList::iterator iter = pSubChunks->begin(), end = pSubChunks->end(); iter != end; ++iter, ++i) {
-                 // divide local progress into subprogress for loading current Instrument
+                 if (pProgress) {
-                 progress_t subprogress;
+                     // divide local progress into subprogress for loading current Instrument
-                 __divide_progress(pProgress, &subprogress, n, i);
+                     progress_t subprogress;
-                 // do the actual work
+                     __divide_progress(pProgress, &subprogress, n, i);
-                 ullWritePos = (*iter)->WriteChunk(ullWritePos, ullCurrentDataOffset, &subprogress);
+                     // do the actual work
+                     ullWritePos = (*iter)->WriteChunk(ullWritePos, ullCurrentDataOffset, &subprogress);
+                 } else
+                     ullWritePos = (*iter)->WriteChunk(ullWritePos, ullCurrentDataOffset, NULL);
              }
          }
-Line 1515 
 namespace RIFF {
+Line 1749 
 namespace RIFF {
          // offset of this list chunk in new written file may have changed
          ullStartPos = ullOriginalPos + LIST_HEADER_SIZE(pFile->FileOffsetSize);
-          __notify_progress(pProgress, 1.0); // notify done
+         if (pProgress)
+             __notify_progress(pProgress, 1.0); // notify done
          return ullWritePos;
      }
-Line 1559 
 namespace RIFF {
+Line 1794 
 namespace RIFF {
          : List(this), bIsNewFile(true), Layout(layout_standard),
            FileOffsetPreference(offset_size_auto)
      {
+         io.isPerThread = false;
          #if defined(WIN32)
-         hFileRead = hFileWrite = INVALID_HANDLE_VALUE;
+         io.hRead = io.hWrite = INVALID_HANDLE_VALUE;
          #else
-         hFileRead = hFileWrite = 0;
+         io.hRead = io.hWrite = 0;
          #endif
-         Mode = stream_mode_closed;
+         io.Mode = stream_mode_closed;
          bEndianNative = true;
          ListType = FileType;
          FileOffsetSize = 4;
-Line 1583 
 namespace RIFF {
+Line 1819 
 namespace RIFF {
          : List(this), Filename(path), bIsNewFile(false), Layout(layout_standard),
            FileOffsetPreference(offset_size_auto)
      {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "File::File("<<path<<")" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          bEndianNative = true;
          FileOffsetSize = 4;
          try {
-Line 1654 
 namespace RIFF {
+Line 1890 
 namespace RIFF {
       *                         given RIFF file or RIFF-alike file
       */
      void File::__openExistingFile(const String& path, uint32_t* FileType) {
+         io.isPerThread = false;
          #if POSIX
-         hFileRead = hFileWrite = open(path.c_str(), O_RDONLY | O_NONBLOCK);
+         io.hRead = io.hWrite = open(path.c_str(), O_RDONLY | O_NONBLOCK);
-         if (hFileRead == -1) {
+         if (io.hRead == -1) {
-             hFileRead = hFileWrite = 0;
+             io.hRead = io.hWrite = 0;
              String sError = strerror(errno);
              throw RIFF::Exception("Can't open \"" + path + "\": " + sError);
          }
          #elif defined(WIN32)
-         hFileRead = hFileWrite = CreateFile(
+         io.hRead = io.hWrite = CreateFile(
                                       path.c_str(), GENERIC_READ,
                                       FILE_SHARE_READ | FILE_SHARE_WRITE,
                                       NULL, OPEN_EXISTING,
                                       FILE_ATTRIBUTE_NORMAL |
                                       FILE_FLAG_RANDOM_ACCESS, NULL
                                   );
-         if (hFileRead == INVALID_HANDLE_VALUE) {
+         if (io.hRead == INVALID_HANDLE_VALUE) {
-             hFileRead = hFileWrite = INVALID_HANDLE_VALUE;
+             io.hRead = io.hWrite = INVALID_HANDLE_VALUE;
              throw RIFF::Exception("Can't open \"" + path + "\"");
          }
          #else
-         hFileRead = hFileWrite = fopen(path.c_str(), "rb");
+         io.hRead = io.hWrite = fopen(path.c_str(), "rb");
-         if (!hFileRead) throw RIFF::Exception("Can't open \"" + path + "\"");
+         if (!io.hRead) throw RIFF::Exception("Can't open \"" + path + "\"");
          #endif // POSIX
-         Mode = stream_mode_read;
+         io.Mode = stream_mode_read;
          // determine RIFF file offset size to be used (in RIFF chunk headers)
          // according to the current file offset preference
-Line 1716 
 namespace RIFF {
+Line 1953 
 namespace RIFF {
          Filename = path;
      }
+     /**
+      * This is an internal-only method which must not be used by any application
+      * and might change at any time.
+      *
+      * Resolves and returns a reference (memory location) of the RIFF file's
+      * internal and OS dependent file I/O handles which are intended to be used
+      * by the calling thread.
+      */
+     File::HandlePair& File::FileHandlePairUnsafeRef() {
+         if (io.byThread.empty()) return io;
+         const std::thread::id tid = std::this_thread::get_id();
+         const auto it = io.byThread.find(tid);
+         return (it != io.byThread.end()) ?
+             it->second :
+             io.byThread[tid] = {
+                 #if defined(WIN32)
+                 .hRead  = INVALID_HANDLE_VALUE,
+                 .hWrite = INVALID_HANDLE_VALUE,
+                 #else
+                 .hRead  = 0,
+                 .hWrite = 0,
+                 #endif
+                 .Mode = stream_mode_closed
+             };
+     }
+     /**
+      * Returns the OS dependent file I/O read and write handles intended to be
+      * used by the calling thread.
+      *
+      * @see File::IsIOPerThread() for multi-threaded streaming
+      */
+     File::HandlePair File::FileHandlePair() const {
+         std::lock_guard<std::mutex> lock(io.mutex);
+         if (io.byThread.empty()) return io;
+         const std::thread::id tid = std::this_thread::get_id();
+         const auto it = io.byThread.find(tid);
+         return (it != io.byThread.end()) ?
+             it->second :
+             io.byThread[tid] = {
+                 #if defined(WIN32)
+                 .hRead  = INVALID_HANDLE_VALUE,
+                 .hWrite = INVALID_HANDLE_VALUE,
+                 #else
+                 .hRead  = 0,
+                 .hWrite = 0,
+                 #endif
+                 .Mode = stream_mode_closed
+             };
+      }
+     /**
+      * Returns the OS dependent file I/O read handle intended to be used by the
+      * calling thread.
+      *
+      * @see File::IsIOPerThread() for multi-threaded streaming
+      */
+     File::Handle File::FileHandle() const {
+         return FileHandlePair().hRead;
+     }
+     /**
+      * Returns the OS dependent file I/O write handle intended to be used by the
+      * calling thread.
+      *
+      * @see File::IsIOPerThread() for multi-threaded streaming
+      */
+     File::Handle File::FileWriteHandle() const {
+         return FileHandlePair().hWrite;
+     }
+     /**
+      * Returns the file I/O mode currently being available for the calling
+      * thread for this RIFF file (either ro, rw or closed).
+      *
+      * @see File::IsIOPerThread() for multi-threaded streaming
+      */
      stream_mode_t File::GetMode() const {
-         return Mode;
+         return FileHandlePair().Mode;
      }
      layout_t File::GetLayout() const {
-Line 1732 
 namespace RIFF {
+Line 2046 
 namespace RIFF {
       * @param NewMode - new file access mode
       * @returns true if mode was changed, false if current mode already
       *          equals new mode
-      * @throws RIFF::Exception if new file access mode is unknown
+      * @throws RIFF::Exception if file could not be opened in requested file
+      *         access mode or if passed access mode is unknown
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      bool File::SetMode(stream_mode_t NewMode) {
-         if (NewMode != Mode) {
+         bool bResetPos = false;
+         bool res = SetModeInternal(NewMode, &bResetPos);
+         // resetting position must be handled outside above's call to avoid any
+         // potential dead lock, as SetModeInternal() acquires a lock and
+         // __resetPos() acquires a lock by itself (not a theoretical issue!)
+         if (bResetPos)
+             __resetPos(); // reset read/write position of ALL 'Chunk' objects
+         return res;
+     }
+     bool File::SetModeInternal(stream_mode_t NewMode, bool* pResetPos) {
+         std::lock_guard<std::mutex> lock(io.mutex);
+         HandlePair& io = FileHandlePairUnsafeRef();
+         if (NewMode != io.Mode) {
              switch (NewMode) {
                  case stream_mode_read:
+                     if (_isValidHandle(io.hRead)) _close(io.hRead);
                      #if POSIX
-                     if (hFileRead) close(hFileRead);
+                     io.hRead = io.hWrite = open(Filename.c_str(), O_RDONLY | O_NONBLOCK);
-                     hFileRead = hFileWrite = open(Filename.c_str(), O_RDONLY | O_NONBLOCK);
+                     if (io.hRead == -1) {
-                     if (hFileRead == -1) {
+                         io.hRead = io.hWrite = 0;
-                         hFileRead = hFileWrite = 0;
                          String sError = strerror(errno);
                          throw Exception("Could not (re)open file \"" + Filename + "\" in read mode: " + sError);
                      }
                      #elif defined(WIN32)
-                     if (hFileRead != INVALID_HANDLE_VALUE) CloseHandle(hFileRead);
+                     io.hRead = io.hWrite = CreateFile(
-                     hFileRead = hFileWrite = CreateFile(
                                                   Filename.c_str(), GENERIC_READ,
                                                   FILE_SHARE_READ | FILE_SHARE_WRITE,
                                                   NULL, OPEN_EXISTING,
-Line 1756 
 namespace RIFF {
+Line 2084 
 namespace RIFF {
                                                   FILE_FLAG_RANDOM_ACCESS,
                                                   NULL
                                               );
-                     if (hFileRead == INVALID_HANDLE_VALUE) {
+                     if (io.hRead == INVALID_HANDLE_VALUE) {
-                         hFileRead = hFileWrite = INVALID_HANDLE_VALUE;
+                         io.hRead = io.hWrite = INVALID_HANDLE_VALUE;
                          throw Exception("Could not (re)open file \"" + Filename + "\" in read mode");
                      }
                      #else
-                     if (hFileRead) fclose(hFileRead);
+                     io.hRead = io.hWrite = fopen(Filename.c_str(), "rb");
-                     hFileRead = hFileWrite = fopen(Filename.c_str(), "rb");
+                     if (!io.hRead) throw Exception("Could not (re)open file \"" + Filename + "\" in read mode");
-                     if (!hFileRead) throw Exception("Could not (re)open file \"" + Filename + "\" in read mode");
                      #endif
-                     __resetPos(); // reset read/write position of ALL 'Chunk' objects
+                     *pResetPos = true;
                      break;
                  case stream_mode_read_write:
+                     if (_isValidHandle(io.hRead)) _close(io.hRead);
                      #if POSIX
-                     if (hFileRead) close(hFileRead);
+                     io.hRead = io.hWrite = open(Filename.c_str(), O_RDWR | O_NONBLOCK);
-                     hFileRead = hFileWrite = open(Filename.c_str(), O_RDWR | O_NONBLOCK);
+                     if (io.hRead == -1) {
-                     if (hFileRead == -1) {
+                         io.hRead = io.hWrite = open(Filename.c_str(), O_RDONLY | O_NONBLOCK);
-                         hFileRead = hFileWrite = open(Filename.c_str(), O_RDONLY | O_NONBLOCK);
                          String sError = strerror(errno);
                          throw Exception("Could not open file \"" + Filename + "\" in read+write mode: " + sError);
                      }
                      #elif defined(WIN32)
-                     if (hFileRead != INVALID_HANDLE_VALUE) CloseHandle(hFileRead);
+                     io.hRead = io.hWrite = CreateFile(
-                     hFileRead = hFileWrite = CreateFile(
                                                   Filename.c_str(),
                                                   GENERIC_READ | GENERIC_WRITE,
                                                   FILE_SHARE_READ,
-Line 1787 
 namespace RIFF {
+Line 2113 
 namespace RIFF {
                                                   FILE_FLAG_RANDOM_ACCESS,
                                                   NULL
                                               );
-                     if (hFileRead == INVALID_HANDLE_VALUE) {
+                     if (io.hRead == INVALID_HANDLE_VALUE) {
-                         hFileRead = hFileWrite = CreateFile(
+                         io.hRead = io.hWrite = CreateFile(
                                                       Filename.c_str(), GENERIC_READ,
                                                       FILE_SHARE_READ | FILE_SHARE_WRITE,
                                                       NULL, OPEN_EXISTING,
-Line 1799 
 namespace RIFF {
+Line 2125 
 namespace RIFF {
                          throw Exception("Could not (re)open file \"" + Filename + "\" in read+write mode");
                      }
                      #else
-                     if (hFileRead) fclose(hFileRead);
+                     io.hRead = io.hWrite = fopen(Filename.c_str(), "r+b");
-                     hFileRead = hFileWrite = fopen(Filename.c_str(), "r+b");
+                     if (!io.hRead) {
-                     if (!hFileRead) {
+                         io.hRead = io.hWrite = fopen(Filename.c_str(), "rb");
-                         hFileRead = hFileWrite = fopen(Filename.c_str(), "rb");
                          throw Exception("Could not open file \"" + Filename + "\" in read+write mode");
                      }
                      #endif
-                     __resetPos(); // reset read/write position of ALL 'Chunk' objects
+                     *pResetPos = true;
                      break;
                  case stream_mode_closed:
+                     if (_isValidHandle(io.hRead)) _close(io.hRead);
+                     if (_isValidHandle(io.hWrite)) _close(io.hWrite);
                      #if POSIX
-                     if (hFileRead)  close(hFileRead);
+                     io.hRead = io.hWrite = 0;
-                     if (hFileWrite) close(hFileWrite);
                      #elif defined(WIN32)
-                     if (hFileRead  != INVALID_HANDLE_VALUE) CloseHandle(hFileRead);
+                     io.hRead = io.hWrite = INVALID_HANDLE_VALUE;
-                     if (hFileWrite != INVALID_HANDLE_VALUE) CloseHandle(hFileWrite);
                      #else
-                     if (hFileRead)  fclose(hFileRead);
+                     io.hRead = io.hWrite = NULL;
-                     if (hFileWrite) fclose(hFileWrite);
                      #endif
-                     hFileRead = hFileWrite = 0;
                      break;
                  default:
                      throw Exception("Unknown file access mode");
              }
-             Mode = NewMode;
+             io.Mode = NewMode;
              return true;
          }
          return false;
-Line 1855 
 namespace RIFF {
+Line 2178 
 namespace RIFF {
       * @param pProgress - optional: callback function for progress notification
       * @throws RIFF::Exception if there is an empty chunk or empty list
       *                         chunk or any kind of IO error occurred
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      void File::Save(progress_t* pProgress) {
          //TODO: implementation for the case where first chunk is not a global container (List chunk) is not implemented yet (i.e. Korg files)
-Line 1862 
 namespace RIFF {
+Line 2186 
 namespace RIFF {
              throw Exception("Saving a RIFF file with layout_flat is not implemented yet");
          // make sure the RIFF tree is built (from the original file)
-         {
+         if (pProgress) {
              // divide progress into subprogress
              progress_t subprogress;
              __divide_progress(pProgress, &subprogress, 3.f, 0.f); // arbitrarily subdivided into 1/3 of total progress
-Line 1870 
 namespace RIFF {
+Line 2194 
 namespace RIFF {
              LoadSubChunksRecursively(&subprogress);
              // notify subprogress done
              __notify_progress(&subprogress, 1.f);
-         }
+         } else
+             LoadSubChunksRecursively(NULL);
          // reopen file in write mode
          SetMode(stream_mode_read_write);
-Line 1885 
 namespace RIFF {
+Line 2210 
 namespace RIFF {
          // the RIFF file offset size to be used accordingly for all chunks
          FileOffsetSize = FileOffsetSizeFor(newFileSize);
+         const HandlePair io = FileHandlePair();
+         const Handle hRead  = io.hRead;
+         const Handle hWrite = io.hWrite;
          // to be able to save the whole file without loading everything into
          // RAM and without having to store the data in a temporary file, we
          // enlarge the file with the overall positive file size change,
-Line 1900 
 namespace RIFF {
+Line 2229 
 namespace RIFF {
              // divide progress into subprogress
              progress_t subprogress;
-             __divide_progress(pProgress, &subprogress, 3.f, 1.f); // arbitrarily subdivided into 1/3 of total progress
+             if (pProgress)
+                 __divide_progress(pProgress, &subprogress, 3.f, 1.f); // arbitrarily subdivided into 1/3 of total progress
              // ... we enlarge this file first ...
              ResizeFile(newFileSize);
-Line 1916 
 namespace RIFF {
+Line 2246 
 namespace RIFF {
                  iBytesMoved = (ullPos < 4096) ? ullPos : 4096;
                  ullPos -= iBytesMoved;
                  #if POSIX
-                 lseek(hFileRead, ullPos, SEEK_SET);
+                 lseek(hRead, ullPos, SEEK_SET);
-                 iBytesMoved = read(hFileRead, pCopyBuffer, iBytesMoved);
+                 iBytesMoved = read(hRead, pCopyBuffer, iBytesMoved);
-                 lseek(hFileWrite, ullPos + positiveSizeDiff, SEEK_SET);
+                 lseek(hWrite, ullPos + positiveSizeDiff, SEEK_SET);
-                 iBytesMoved = write(hFileWrite, pCopyBuffer, iBytesMoved);
+                 iBytesMoved = write(hWrite, pCopyBuffer, iBytesMoved);
                  #elif defined(WIN32)
                  LARGE_INTEGER liFilePos;
                  liFilePos.QuadPart = ullPos;
-                 SetFilePointerEx(hFileRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
+                 SetFilePointerEx(hRead, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
-                 ReadFile(hFileRead, pCopyBuffer, iBytesMoved, &iBytesMoved, NULL);
+                 ReadFile(hRead, pCopyBuffer, iBytesMoved, &iBytesMoved, NULL);
                  liFilePos.QuadPart = ullPos + positiveSizeDiff;
-                 SetFilePointerEx(hFileWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
+                 SetFilePointerEx(hWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN);
-                 WriteFile(hFileWrite, pCopyBuffer, iBytesMoved, &iBytesMoved, NULL);
+                 WriteFile(hWrite, pCopyBuffer, iBytesMoved, &iBytesMoved, NULL);
                  #else
-                 fseeko(hFileRead, ullPos, SEEK_SET);
+                 fseeko(hRead, ullPos, SEEK_SET);
-                 iBytesMoved = fread(pCopyBuffer, 1, iBytesMoved, hFileRead);
+                 iBytesMoved = fread(pCopyBuffer, 1, iBytesMoved, hRead);
-                 fseeko(hFileWrite, ullPos + positiveSizeDiff, SEEK_SET);
+                 fseeko(hWrite, ullPos + positiveSizeDiff, SEEK_SET);
-                 iBytesMoved = fwrite(pCopyBuffer, 1, iBytesMoved, hFileWrite);
+                 iBytesMoved = fwrite(pCopyBuffer, 1, iBytesMoved, hWrite);
                  #endif
-                 if (!(iNotif % 8) && iBytesMoved > 0)
+                 if (pProgress && !(iNotif % 8) && iBytesMoved > 0)
                      __notify_progress(&subprogress, float(workingFileSize - ullPos) / float(workingFileSize));
              }
              delete[] pCopyBuffer;
              if (iBytesMoved < 0) throw Exception("Could not modify file while trying to enlarge it");
-             __notify_progress(&subprogress, 1.f); // notify subprogress done
+             if (pProgress)
+                 __notify_progress(&subprogress, 1.f); // notify subprogress done
          }
          // rebuild / rewrite complete RIFF tree ...
          // divide progress into subprogress
          progress_t subprogress;
-         __divide_progress(pProgress, &subprogress, 3.f, 2.f); // arbitrarily subdivided into 1/3 of total progress
+         if (pProgress)
+             __divide_progress(pProgress, &subprogress, 3.f, 2.f); // arbitrarily subdivided into 1/3 of total progress
          // do the actual work
-         const file_offset_t finalSize = WriteChunk(0, positiveSizeDiff, &subprogress);
+         const file_offset_t finalSize = WriteChunk(0, positiveSizeDiff, pProgress ? &subprogress : NULL);
-         const file_offset_t finalActualSize = __GetFileSize(hFileWrite);
+         const file_offset_t finalActualSize = __GetFileSize(hWrite);
          // notify subprogress done
-         __notify_progress(&subprogress, 1.f);
+         if (pProgress)
+             __notify_progress(&subprogress, 1.f);
          // resize file to the final size
          if (finalSize < finalActualSize) ResizeFile(finalSize);
-         __notify_progress(pProgress, 1.0); // notify done
+         if (pProgress)
+             __notify_progress(pProgress, 1.0); // notify done
      }
      /** @brief Save changes to another file.
-Line 1973 
 namespace RIFF {
+Line 2307 
 namespace RIFF {
       *
       * @param path - path and file name where everything should be written to
       * @param pProgress - optional: callback function for progress notification
+      * @see File::IsIOPerThread() for multi-threaded streaming
       */
      void File::Save(const String& path, progress_t* pProgress) {
          //TODO: we should make a check here if somebody tries to write to the same file and automatically call the other Save() method in that case
-Line 1982 
 namespace RIFF {
+Line 2317 
 namespace RIFF {
              throw Exception("Saving a RIFF file with layout_flat is not implemented yet");
          // make sure the RIFF tree is built (from the original file)
-         {
+         if (pProgress) {
              // divide progress into subprogress
              progress_t subprogress;
              __divide_progress(pProgress, &subprogress, 2.f, 0.f); // arbitrarily subdivided into 1/2 of total progress
-Line 1990 
 namespace RIFF {
+Line 2325 
 namespace RIFF {
              LoadSubChunksRecursively(&subprogress);
              // notify subprogress done
              __notify_progress(&subprogress, 1.f);
-         }
+         } else
+             LoadSubChunksRecursively(NULL);
          if (!bIsNewFile) SetMode(stream_mode_read);
-         // open the other (new) file for writing and truncate it to zero size
-         #if POSIX
+         {
-         hFileWrite = open(path.c_str(), O_RDWR | O_CREAT, S_IRUSR | S_IWUSR | S_IRGRP);
+             std::lock_guard<std::mutex> lock(io.mutex);
-         if (hFileWrite == -1) {
+             HandlePair& io = FileHandlePairUnsafeRef();
-             hFileWrite = hFileRead;
-             String sError = strerror(errno);
+             // open the other (new) file for writing and truncate it to zero size
-             throw Exception("Could not open file \"" + path + "\" for writing: " + sError);
+             #if POSIX
-         }
+             io.hWrite = open(path.c_str(), O_RDWR | O_CREAT, S_IRUSR | S_IWUSR | S_IRGRP);
-         #elif defined(WIN32)
+             if (io.hWrite == -1) {
-         hFileWrite = CreateFile(
+                 io.hWrite = io.hRead;
-                          path.c_str(), GENERIC_WRITE, FILE_SHARE_READ,
+                 String sError = strerror(errno);
-                          NULL, OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL |
+                 throw Exception("Could not open file \"" + path + "\" for writing: " + sError);
-                          FILE_FLAG_RANDOM_ACCESS, NULL
+             }
-                      );
+             #elif defined(WIN32)
-         if (hFileWrite == INVALID_HANDLE_VALUE) {
+             io.hWrite = CreateFile(
-             hFileWrite = hFileRead;
+                 path.c_str(), GENERIC_WRITE, FILE_SHARE_READ,
-             throw Exception("Could not open file \"" + path + "\" for writing");
+                 NULL, OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL |
-         }
+                 FILE_FLAG_RANDOM_ACCESS, NULL
-         #else
+             );
-         hFileWrite = fopen(path.c_str(), "w+b");
+             if (io.hWrite == INVALID_HANDLE_VALUE) {
-         if (!hFileWrite) {
+                 io.hWrite = io.hRead;
-             hFileWrite = hFileRead;
+                 throw Exception("Could not open file \"" + path + "\" for writing");
-             throw Exception("Could not open file \"" + path + "\" for writing");
+             }
+             #else
+             io.hWrite = fopen(path.c_str(), "w+b");
+             if (!io.hWrite) {
+                 io.hWrite = io.hRead;
+                 throw Exception("Could not open file \"" + path + "\" for writing");
+             }
+             #endif // POSIX
+             io.Mode = stream_mode_read_write;
          }
-         #endif // POSIX
-         Mode = stream_mode_read_write;
          // get the overall file size required to save this file
          const file_offset_t newFileSize = GetRequiredFileSize(FileOffsetPreference);
-Line 2029 
 namespace RIFF {
+Line 2371 
 namespace RIFF {
          // write complete RIFF tree to the other (new) file
          file_offset_t ullTotalSize;
-         {
+         if (pProgress) {
              // divide progress into subprogress
              progress_t subprogress;
              __divide_progress(pProgress, &subprogress, 2.f, 1.f); // arbitrarily subdivided into 1/2 of total progress
-Line 2037 
 namespace RIFF {
+Line 2379 
 namespace RIFF {
              ullTotalSize = WriteChunk(0, 0, &subprogress);
              // notify subprogress done
              __notify_progress(&subprogress, 1.f);
-         }
+         } else
-         file_offset_t ullActualSize = __GetFileSize(hFileWrite);
+             ullTotalSize = WriteChunk(0, 0, NULL);
+         const file_offset_t ullActualSize = __GetFileSize(FileWriteHandle());
          // resize file to the final size (if the file was originally larger)
          if (ullActualSize > ullTotalSize) ResizeFile(ullTotalSize);
-         #if POSIX
+         {
-         if (hFileWrite) close(hFileWrite);
+             std::lock_guard<std::mutex> lock(io.mutex);
-         #elif defined(WIN32)
+             HandlePair& io = FileHandlePairUnsafeRef();
-         if (hFileWrite != INVALID_HANDLE_VALUE) CloseHandle(hFileWrite);
-         #else
-         if (hFileWrite) fclose(hFileWrite);
-         #endif
-         hFileWrite = hFileRead;
-         // associate new file with this File object from now on
+             if (_isValidHandle(io.hWrite)) _close(io.hWrite);
-         Filename = path;
+             io.hWrite = io.hRead;
-         bIsNewFile = false;
-         Mode = (stream_mode_t) -1;       // Just set it to an undefined mode ...
+             // associate new file with this File object from now on
+             Filename = path;
+             bIsNewFile = false;
+             io.Mode = (stream_mode_t) -1; // Just set it to an undefined mode ...
+         }
          SetMode(stream_mode_read_write); // ... so SetMode() has to reopen the file handles.
-         __notify_progress(pProgress, 1.0); // notify done
+         if (pProgress)
+             __notify_progress(pProgress, 1.0); // notify done
      }
      void File::ResizeFile(file_offset_t ullNewSize) {
+         const Handle hWrite = FileWriteHandle();
          #if POSIX
-         if (ftruncate(hFileWrite, ullNewSize) < 0)
+         if (ftruncate(hWrite, ullNewSize) < 0)
              throw Exception("Could not resize file \"" + Filename + "\"");
          #elif defined(WIN32)
          LARGE_INTEGER liFilePos;
          liFilePos.QuadPart = ullNewSize;
          if (
-             !SetFilePointerEx(hFileWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN) ||
+             !SetFilePointerEx(hWrite, liFilePos, NULL/*new pos pointer*/, FILE_BEGIN) ||
-             !SetEndOfFile(hFileWrite)
+             !SetEndOfFile(hWrite)
          ) throw Exception("Could not resize file \"" + Filename + "\"");
          #else
          # error Sorry, this version of libgig only supports POSIX and Windows systems yet.
-Line 2079 
 namespace RIFF {
+Line 2424 
 namespace RIFF {
      }
      File::~File() {
-         #if DEBUG
+         #if DEBUG_RIFF
          std::cout << "File::~File()" << std::endl;
-         #endif // DEBUG
+         #endif // DEBUG_RIFF
          Cleanup();
      }
-Line 2094 
 namespace RIFF {
+Line 2439 
 namespace RIFF {
      }
      void File::Cleanup() {
-         #if POSIX
+         if (IsIOPerThread()) {
-         if (hFileRead) close(hFileRead);
+             for (auto it = io.byThread.begin(); it != io.byThread.end(); ++it) {
-         #elif defined(WIN32)
+                 _close(it->second.hRead);
-         if (hFileRead != INVALID_HANDLE_VALUE) CloseHandle(hFileRead);
+             }
-         #else
+         } else {
-         if (hFileRead) fclose(hFileRead);
+             _close(io.hRead);
-         #endif // POSIX
+         }
          DeleteChunkList();
          pFile = NULL;
      }
-Line 2113 
 namespace RIFF {
+Line 2458 
 namespace RIFF {
       */
      file_offset_t File::GetCurrentFileSize() const {
          file_offset_t size = 0;
+         const Handle hRead = FileHandle();
          try {
-             size = __GetFileSize(hFileRead);
+             size = __GetFileSize(hRead);
          } catch (...) {
              size = 0;
          }
-Line 2222 
 namespace RIFF {
+Line 2568 
 namespace RIFF {
          return FileOffsetSizeFor(GetCurrentFileSize());
      }
+     /** @brief Whether file streams are independent for each thread.
+      *
+      * All file I/O operations like reading from a RIFF chunk body (e.g. by
+      * calling Chunk::Read(), Chunk::ReadInt8()), writing to a RIFF chunk body
+      * (e.g. by calling Chunk::Write(), Chunk::WriteInt8()) or saving the
+      * current RIFF tree structure to some file (e.g. by calling Save())
+      * operate on a file I/O stream state, i.e. there is a "current" file
+      * read/write position and reading/writing by a certain amount of bytes
+      * automatically advances that "current" file position.
+      *
+      * By default there is only one stream state for a RIFF::File object, which
+      * is not an issue as long as only one thread is using the RIFF::File
+      * object at a time (which might also be the case in a collaborative /
+      * coroutine multi-threaded scenario).
+      *
+      * If however a RIFF::File object is read/written @b simultaniously by
+      * multiple threads this can lead to undefined behaviour as the individual
+      * threads would concurrently alter the file stream position. For such a
+      * concurrent multithreaded file I/O scenario @c SetIOPerThread(true) might
+      * be enabled which causes each thread to automatically use its own file
+      * stream state.
+      *
+      * @returns true if each thread has its own file stream state
+      *          (default: false)
+      * @see SetIOPerThread()
+      */
+     bool File::IsIOPerThread() const {
+         //NOTE: Not caring about atomicity here at all, for three reasons:
+         // 1. SetIOPerThread() is assumed to be called only once for the entire
+         //    life time of a RIFF::File, usually very early at its lifetime, and
+         //    hence a change to isPerThread should already safely be propagated
+         //    before any other thread would actually read this boolean flag.
+         // 2. This method is called very frequently, and therefore any
+         //    synchronization techique would hurt runtime efficiency.
+         // 3. Using even a mutex lock here might easily cause a deadlock due to
+         //    other locks been taken in this .cpp file, i.e. at a higher call
+         //    stack level (and this is the main reason why I removed it here).
+         return io.isPerThread;
+     }
+     /** @brief Enable/disable file streams being independent for each thread.
+      *
+      * By enabling this feature (default off) each thread will automatically use
+      * its own file I/O stream state for allowing simultanious multi-threaded
+      * file read/write operations.
+      *
+      * @b NOTE: After having enabled this feature, the individual threads must
+      * at least once check GetState() and if their file I/O stream is yet closed
+      * they must call SetMode() (i.e. once) respectively to open their own file
+      * handles before being able to use any of the Read() or Write() methods.
+      *
+      * @param enable - @c true: one independent stream state per thread,
+      *                 @c false: only one stream in total shared by @b all threads
+      * @see IsIOPerThread() for more details about this feature
+      */
+     void File::SetIOPerThread(bool enable) {
+         std::lock_guard<std::mutex> lock(io.mutex);
+         if (!io.byThread.empty() == enable) return;
+         io.isPerThread = enable;
+         if (enable) {
+             const std::thread::id tid = std::this_thread::get_id();
+             io.byThread[tid] = io;
+         } else {
+             // retain an arbitrary handle pair, close all other handle pairs
+             for (auto it = io.byThread.begin(); it != io.byThread.end(); ++it) {
+                 if (it == io.byThread.begin()) {
+                     io.hRead  = it->second.hRead;
+                     io.hWrite = it->second.hWrite;
+                 } else {
+                     _close(it->second.hRead);
+                     _close(it->second.hWrite);
+                 }
+             }
+             io.byThread.clear();
+         }
+     }
      #if POSIX
      file_offset_t File::__GetFileSize(int hFile) const {
          struct stat filestat;
-Line 2251 
 namespace RIFF {
+Line 2674 
 namespace RIFF {
  // *************** Exception ***************
  // *
+     Exception::Exception() {
+     }
+     Exception::Exception(String format, ...) {
+         va_list arg;
+         va_start(arg, format);
+         Message = assemble(format, arg);
+         va_end(arg);
+     }
+     Exception::Exception(String format, va_list arg) {
+         Message = assemble(format, arg);
+     }
      void Exception::PrintMessage() {
          std::cout << "RIFF::Exception: " << Message << std::endl;
      }
+     String Exception::assemble(String format, va_list arg) {
+         char* buf = NULL;
+         vasprintf(&buf, format.c_str(), arg);
+         String s = buf;
+         free(buf);
+         return s;
+     }
  // *************** functions ***************
  // *

 Legend:



Removed from v.3053
 


changed lines


 
Added in v.3921
 Legend:



Removed from v.3053
 


changed lines


 
Added in v.3921
-Removed from v.3053
+Added in v.3921

	ViewVC Help
Powered by ViewVC