private void ensureFileRegionAllocatedAndZeroed(@NotNull RegionAllocationAtomicityLock regionAllocationAtomicityLock,
                                                    @NotNull FileChannel channel,
                                                    int pageSize) throws IOException {
      //Why do we zero a page via writing to FileChannel, and not just mmap page, and then fill the mmapped buffer with
      // zeros? Because mmap is tricky: it is possible to write to a mmapped buffer beyond current EOF -- but it is
      // an 'undefined behavior', and results vary on different platforms, and could be anything from OK to SIGBUS, and
      // to very tricky bugs.
      //Why do we write zeros from start to finish, and not just write single 0 at the end of region, and allow OS
      // to expand the file and fill everything until new EOF? Because on many modern FSes file could be sparse, and
      // a single write to the far end of the file could leave huge unallocated gap in the middle of the file -- the
      // gap which lately leads to SIGBUS if e.g. no disk space to allocate block for it.
      // Filling the file explicitly by writing zeroes _seems to_ (as of today) forces FS to allocate all the blocks
      // immediately -- so disk space or any other disk-related issues present themself as some kind of IOException,
      // and not as SIGBUS.

      RegionAllocationAtomicityLock.Region region = regionAllocationAtomicityLock.region(offsetInFile, pageSize);

      //The difference between the branches:
      //In the 'correct' branch: we don't touch already existing part of the file -- because it could be already written
      //  to, and we don't want to ruin that data.
      //In the unfinished (='recovering') branch: we intentionally zero _all_ the region -- because we know we didn't
      //  finish page allocation, so page wasn't published for use => nobody should _legally_ write anything meaningful
      //  into it, but page-zeroing is likely also un-finished, hence it could be some _garbage_ on the page, which we
      //  want to erase
      if (region.isUnfinished()) {
        //recover from page-allocation-and-zeroing-interrupted-in-the-middle
        LOG.warn("mmapped file region " + region + " allocation & zeroing has been started, " +
                 "but hasn't been properly finished -- IDE was crashed/killed? -> try finishing the job");
        IOUtil.fillFileRegionWithZeros(channel, offsetInFile, offsetInFile + pageSize);
      }
      else {
        region.start();
        IOUtil.allocateFileRegion(channel, offsetInFile + pageSize);
      }

      //do not use 'finally': we want to mark region 'finished' only if file region allocation & zeroing was _successful_
      region.finish();
    }
private void ensureFileRegionAllocatedAndZeroed(@NotNull RegionAllocationAtomicityLock regionAllocationAtomicityLock,
                                                    @NotNull FileChannel channel,
                                                    int pageSize)