* Copyright 2010 The Apache Software Foundation

*

* Licensed to the Apache Software Foundation (ASF) under one

* or more contributor license agreements.  See the NOTICE file

* distributed with this work for additional information

* regarding copyright ownership.  The ASF licenses this file

* to you under the Apache License, Version 2.0 (the

* "License"); you may not use this file except in compliance

* with the License.  You may obtain a copy of the License at

*

*     http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

* HRegion stores data for a certain region of a table.  It stores all columns

* for each row. A given table consists of one or more HRegions.

*

* <p>We maintain multiple HStores for a single HRegion.

*

* <p>An Store is a set of rows with some column data; together,

* they make up all the data for the rows.

*

* <p>Each HRegion has a 'startKey' and 'endKey'.

* <p>The first is inclusive, the second is exclusive (except for

* the final region)  The endKey of region 0 is the same as

* startKey for region 1 (if it exists).  The startKey for the

* first region is null. The endKey for the final region is null.

*

* <p>Locking at the HRegion level serves only one purpose: preventing the

* region from being closed (and consequently split) while other operations

* are ongoing. Each row level operation obtains both a row lock and a region

* read lock for the duration of the operation. While a scanner is being

* constructed, getScanner holds a read lock. If the scanner is successfully

* constructed, it holds a read lock until it is closed. A close takes out a

* write lock and consequently will block for ongoing operations and will block

* new operations from starting while the close is in progress.

*

* <p>An HRegion is defined by its table and its key extent.

*

* <p>It consists of at least one Store.  The number of Stores should be

* configurable, so that data which is accessed together is stored in the same

* Store.  Right now, we approximate that by building a single Store for

* each column family.  (This config info will be communicated via the

* tabledesc.)

*

* <p>The HTableDescriptor contains metainfo about the HRegion's table.

* regionName is a unique identifier for this HRegion. (startKey, endKey]

* defines the keyspace for this HRegion.

*/

  public static final Log LOG = LogFactory.getLog(HRegion.class);

  static final String SPLITDIR = "splits";

  static final String MERGEDIR = "merges";

  final AtomicBoolean closed = new AtomicBoolean(false);

  /* Closing can take some time; use the closing flag if there is stuff we don't

   * want to do while in closing state; e.g. like offer this region up to the

   * master as a region to close if the carrying regionserver is overloaded.

   * Once set, it is never cleared.

   */

  final AtomicBoolean closing = new AtomicBoolean(false);

  //////////////////////////////////////////////////////////////////////////////

  // Members

  //////////////////////////////////////////////////////////////////////////////

  private final Set<byte[]> lockedRows =

    new TreeSet<byte[]>(Bytes.BYTES_COMPARATOR);

  private final Map<Integer, byte []> lockIds =

    new HashMap<Integer, byte []>();

  private int lockIdGenerator = 1;

  static private Random rand = new Random();

  protected final Map<byte [], Store> stores =

    new ConcurrentSkipListMap<byte [], Store>(Bytes.BYTES_RAWCOMPARATOR);

  //These variable are just used for getting data out of the region, to test on

  //client side

  // private int numStores = 0;

  // private int [] storeSize = null;

  // private byte [] name = null;

  final AtomicLong memstoreSize = new AtomicLong(0);

  /**

   * The directory for the table this region is part of.

   * This directory contains the directory for this region.

   */

  final Path tableDir;

 

  final HLog log;

  final FileSystem fs;

  final Configuration conf;

  final HRegionInfo regionInfo;

  final Path regiondir;

  KeyValue.KVComparator comparator;

  /*

   * Set this when scheduling compaction if want the next compaction to be a

   * major compaction.  Cleared each time through compaction code.

   */

  private volatile boolean forceMajorCompaction = false;

  /*

   * Data structure of write state flags used coordinating flushes,

   * compactions and closes.

   */

  static class WriteState {

    // Set while a memstore flush is happening.

    volatile boolean flushing = false;

    // Set when a flush has been requested.

    volatile boolean flushRequested = false;

    // Set while a compaction is running.

    volatile boolean compacting = false;

    // Gets set in close. If set, cannot compact or flush again.

    volatile boolean writesEnabled = true;

    // Set if region is read-only

    volatile boolean readOnly = false;

    /**

     * Set flags that make this region read-only.

     *

     * @param onOff flip value for region r/o setting

     */

    synchronized void setReadOnly(final boolean onOff) {

      this.writesEnabled = !onOff;

      this.readOnly = onOff;

    }

    boolean isReadOnly() {

      return this.readOnly;

    }

    boolean isFlushRequested() {

      return this.flushRequested;

    }

  }

  private final WriteState writestate = new WriteState();

  final long memstoreFlushSize;

  private volatile long lastFlushTime;

  final FlushRequester flushListener;

  private final long blockingMemStoreSize;

  final long threadWakeFrequency;

  // Used to guard splits and closes

  private final ReentrantReadWriteLock splitsAndClosesLock =

    new ReentrantReadWriteLock();

  private final ReentrantReadWriteLock newScannerLock =

    new ReentrantReadWriteLock();

  // Stop updates lock

  private final ReentrantReadWriteLock updatesLock =

    new ReentrantReadWriteLock();

  private final Object splitLock = new Object();

  private boolean splitRequest;

  private final ReadWriteConsistencyControl rwcc =

      new ReadWriteConsistencyControl();

  /**

   * Name of the region info file that resides just under the region directory.

   */

  public final static String REGIONINFO_FILE = ".regioninfo";

  /**

   * Should only be used for testing purposes

   */

  public HRegion(){

    this.tableDir = null;

    this.blockingMemStoreSize = 0L;

    this.conf = null;

    this.flushListener = null;

    this.fs = null;

    this.memstoreFlushSize = 0L;

    this.log = null;

    this.regiondir = null;

    this.regionInfo = null;

    this.threadWakeFrequency = 0L;

  }

  /**

   * HRegion constructor.  his constructor should only be used for testing and

   * extensions.  Instances of HRegion should be instantiated with the

   * {@link HRegion#newHRegion(Path, HLog, FileSystem, Configuration, org.apache.hadoop.hbase.HRegionInfo, FlushRequester)} method.

   *

   *

   * @param tableDir qualified path of directory where region should be located,

   * usually the table directory.

   * @param log The HLog is the outbound log for any updates to the HRegion

   * (There's a single HLog for all the HRegions on a single HRegionServer.)

   * The log file is a logfile from the previous execution that's

   * custom-computed for this HRegion. The HRegionServer computes and sorts the

   * appropriate log info for this HRegion. If there is a previous log file

   * (implying that the HRegion has been written-to before), then read it from

   * the supplied path.

   * @param fs is the filesystem.

   * @param conf is global configuration settings.

   * @param regionInfo - HRegionInfo that describes the region

   * is new), then read them from the supplied path.

   * @param flushListener an object that implements CacheFlushListener or null

   * making progress to master -- otherwise master might think region deploy

   * failed.  Can be null.

   *

   * @see HRegion#newHRegion(Path, HLog, FileSystem, Configuration, org.apache.hadoop.hbase.HRegionInfo, FlushRequester)

   */

  public HRegion(Path tableDir, HLog log, FileSystem fs, Configuration conf,

      HRegionInfo regionInfo, FlushRequester flushListener) {

    this.tableDir = tableDir;

    this.comparator = regionInfo.getComparator();

    this.log = log;

    this.fs = fs;

    this.conf = conf;

    this.regionInfo = regionInfo;

    this.flushListener = flushListener;

    this.threadWakeFrequency = conf.getLong(HConstants.THREAD_WAKE_FREQUENCY,

        10 * 1000);

    String encodedNameStr = this.regionInfo.getEncodedName();

    this.regiondir = new Path(tableDir, encodedNameStr);

    if (LOG.isDebugEnabled()) {

      // Write out region name as string and its encoded name.

      LOG.debug("Creating region " + this);

    }

    long flushSize = regionInfo.getTableDesc().getMemStoreFlushSize();

    if (flushSize == HTableDescriptor.DEFAULT_MEMSTORE_FLUSH_SIZE) {

      flushSize = conf.getLong("hbase.hregion.memstore.flush.size",

                      HTableDescriptor.DEFAULT_MEMSTORE_FLUSH_SIZE);

    }

    this.memstoreFlushSize = flushSize;

    this.blockingMemStoreSize = this.memstoreFlushSize *

      conf.getLong("hbase.hregion.memstore.block.multiplier", 2);

  }

  /**

   * Initialize this region.

   * @return What the next sequence (edit) id should be.

   * @throws IOException e

   */

  public long initialize() throws IOException {

    return initialize(null);

  }

  /**

   * Initialize this region.

   *

   * @param reporter Tickle every so often if initialize is taking a while.

   * @return What the next sequence (edit) id should be.

   * @throws IOException e

   */

  public long initialize(final Progressable reporter)

  throws IOException {

    // Write HRI to a file in case we need to recover .META.

    checkRegioninfoOnFilesystem();

    // Remove temporary data left over from old regions

    cleanupTmpDir();

   

    // Load in all the HStores.  Get maximum seqid.

    long maxSeqId = -1;

    for (HColumnDescriptor c : this.regionInfo.getTableDesc().getFamilies()) {

      Store store = instantiateHStore(this.tableDir, c);

      this.stores.put(c.getName(), store);

      long storeSeqId = store.getMaxSequenceId();

      if (storeSeqId > maxSeqId) {

        maxSeqId = storeSeqId;

      }

    }

    // Recover any edits if available.

    maxSeqId = replayRecoveredEditsIfAny(this.regiondir, maxSeqId, reporter);

    // Get rid of any splits or merges that were lost in-progress.  Clean out

    // these directories here on open.  We may be opening a region that was

    // being split but we crashed in the middle of it all.

    FSUtils.deleteDirectory(this.fs, new Path(regiondir, SPLITDIR));

    FSUtils.deleteDirectory(this.fs, new Path(regiondir, MERGEDIR));

    // See if region is meant to run read-only.

    if (this.regionInfo.getTableDesc().isReadOnly()) {

      this.writestate.setReadOnly(true);

    }

    this.writestate.compacting = false;

    this.lastFlushTime = EnvironmentEdgeManager.currentTimeMillis();

    // Use maximum of log sequenceid or that which was found in stores

    // (particularly if no recovered edits, seqid will be -1).

    long nextSeqid = maxSeqId + 1;

    LOG.info("Onlined " + this.toString() + "; next sequenceid=" + nextSeqid);

    return nextSeqid;

  }

  /*

   * Move any passed HStore files into place (if any).  Used to pick up split

   * files and any merges from splits and merges dirs.

   * @param initialFiles

   * @throws IOException

   */

  private static void moveInitialFilesIntoPlace(final FileSystem fs,

    final Path initialFiles, final Path regiondir)

  throws IOException {

    if (initialFiles != null && fs.exists(initialFiles)) {

      fs.rename(initialFiles, regiondir);

    }

  }

  /**

   * @return True if this region has references.

   */

  boolean hasReferences() {

    for (Store store : this.stores.values()) {

      for (StoreFile sf : store.getStorefiles()) {

        // Found a reference, return.

        if (sf.isReference()) return true;

      }

    }

    return false;

  }

  /*

   * Write out an info file under the region directory.  Useful recovering

   * mangled regions.

   * @throws IOException

   */

  private void checkRegioninfoOnFilesystem() throws IOException {

    // Name of this file has two leading and trailing underscores so it doesn't

    // clash w/ a store/family name.  There is possibility, but assumption is

    // that its slim (don't want to use control character in filename because

    //

    Path regioninfo = new Path(this.regiondir, REGIONINFO_FILE);

    if (this.fs.exists(regioninfo) &&

        this.fs.getFileStatus(regioninfo).getLen() > 0) {

      return;

    }

    FSDataOutputStream out = this.fs.create(regioninfo, true);

    try {

      this.regionInfo.write(out);

      out.write('\n');

      out.write('\n');

      out.write(Bytes.toBytes(this.regionInfo.toString()));

    } finally {

      out.close();

    }

  }

  /** @return a HRegionInfo object for this region */

  public HRegionInfo getRegionInfo() {

    return this.regionInfo;

  }

  /** @return true if region is closed */

  public boolean isClosed() {

    return this.closed.get();

  }

  /**

   * @return True if closing process has started.

   */

  public boolean isClosing() {

    return this.closing.get();

  }

   public ReadWriteConsistencyControl getRWCC() {

     return rwcc;

   }

  /**

   * Close down this HRegion.  Flush the cache, shut down each HStore, don't

   * service any more calls.

   *

   * <p>This method could take some time to execute, so don't call it from a

   * time-sensitive thread.

   *

   * @return Vector of all the storage files that the HRegion's component

   * HStores make use of.  It's a list of all HStoreFile objects. Returns empty

   * vector if already closed and null if judged that it should not close.

   *

   * @throws IOException e

   */

  public List<StoreFile> close() throws IOException {

    return close(false);

  }

  /**

   * Close down this HRegion.  Flush the cache unless abort parameter is true,

   * Shut down each HStore, don't service any more calls.

   *

   * This method could take some time to execute, so don't call it from a

   * time-sensitive thread.

   *

   * @param abort true if server is aborting (only during testing)

   * @return Vector of all the storage files that the HRegion's component

   * HStores make use of.  It's a list of HStoreFile objects.  Can be null if

   * we are not to close at this time or we are already closed.

   *

   * @throws IOException e

   */

  public List<StoreFile> close(final boolean abort) throws IOException {

    if (isClosed()) {

      LOG.warn("region " + this + " already closed");

      return null;

    }

    synchronized (splitLock) {