001/**
002 * Copyright The Apache Software Foundation
003 *
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *     http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020package org.apache.hadoop.hbase;
021
022import java.io.IOException;
023
024import org.apache.hadoop.hbase.classification.InterfaceAudience;
025
026/**
027 * An interface for an application-specific lock.
028 */
029@InterfaceAudience.Private
030public interface InterProcessLock {
031
032  /**
033   * Acquire the lock, waiting indefinitely until the lock is released or
034   * the thread is interrupted.
035   * @throws IOException If there is an unrecoverable error releasing the lock
036   * @throws InterruptedException If current thread is interrupted while
037   *                              waiting for the lock
038   */
039  void acquire() throws IOException, InterruptedException;
040
041  /**
042   * Acquire the lock within a wait time.
043   * @param timeoutMs The maximum time (in milliseconds) to wait for the lock,
044   *                  -1 to wait indefinitely
045   * @return True if the lock was acquired, false if waiting time elapsed
046   *         before the lock was acquired
047   * @throws IOException If there is an unrecoverable error talking talking
048   *                     (e.g., when talking to a lock service) when acquiring
049   *                     the lock
050   * @throws InterruptedException If the thread is interrupted while waiting to
051   *                              acquire the lock
052   */
053  boolean tryAcquire(long timeoutMs)
054  throws IOException, InterruptedException;
055
056  /**
057   * Release the lock.
058   * @throws IOException If there is an unrecoverable error releasing the lock
059   * @throws InterruptedException If the thread is interrupted while releasing
060   *                              the lock
061   */
062  void release() throws IOException, InterruptedException;
063
064  /**
065   * If supported, attempts to reap all the locks of this type by forcefully
066   * deleting the locks (both held and attempted) that have expired according
067   * to the given timeout. Lock reaping is different than coordinated lock revocation
068   * in that, there is no coordination, and the behavior is undefined if the
069   * lock holder is still alive.
070   * @throws IOException If there is an unrecoverable error reaping the locks
071   */
072  void reapExpiredLocks(long expireTimeoutMs) throws IOException;
073
074  /**
075   * If supported, attempts to reap all the locks of this type by forcefully
076   * deleting the locks (both held and attempted). Lock reaping is different
077   * than coordinated lock revocation in that, there is no coordination, and
078   * the behavior is undefined if the lock holder is still alive.
079   * Calling this should have the same affect as calling {@link #reapExpiredLocks(long)}
080   * with timeout=0.
081   * @throws IOException If there is an unrecoverable error reaping the locks
082   */
083  void reapAllLocks() throws IOException;
084
085  /**
086   * An interface for objects that process lock metadata.
087   */
088  interface MetadataHandler {
089
090    /**
091     * Called after lock metadata is successfully read from a distributed
092     * lock service. This method may contain any procedures for, e.g.,
093     * printing the metadata in a humanly-readable format.
094     * @param metadata The metadata
095     */
096    void handleMetadata(byte[] metadata);
097  }
098
099  /**
100   * Visits the locks (both held and attempted) of this type with the given
101   * {@link MetadataHandler}.
102   * @throws IOException If there is an unrecoverable error
103   */
104  void visitLocks(MetadataHandler handler) throws IOException;
105}