View Javadoc

1   /**
2    * Copyright The Apache Software Foundation
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  package org.apache.hadoop.hbase;
21  
22  import java.io.IOException;
23  
24  import org.apache.hadoop.classification.InterfaceAudience;
25  
26  /**
27   * An interface for an application-specific lock.
28   */
29  @InterfaceAudience.Private
30  public interface InterProcessLock {
31  
32    /**
33     * Acquire the lock, waiting indefinitely until the lock is released or
34     * the thread is interrupted.
35     * @throws IOException If there is an unrecoverable error releasing the lock
36     * @throws InterruptedException If current thread is interrupted while
37     *                              waiting for the lock
38     */
39    void acquire() throws IOException, InterruptedException;
40  
41    /**
42     * Acquire the lock within a wait time.
43     * @param timeoutMs The maximum time (in milliseconds) to wait for the lock,
44     *                  -1 to wait indefinitely
45     * @return True if the lock was acquired, false if waiting time elapsed
46     *         before the lock was acquired
47     * @throws IOException If there is an unrecoverable error talking talking
48     *                     (e.g., when talking to a lock service) when acquiring
49     *                     the lock
50     * @throws InterruptedException If the thread is interrupted while waiting to
51     *                              acquire the lock
52     */
53    boolean tryAcquire(long timeoutMs)
54    throws IOException, InterruptedException;
55  
56    /**
57     * Release the lock.
58     * @throws IOException If there is an unrecoverable error releasing the lock
59     * @throws InterruptedException If the thread is interrupted while releasing
60     *                              the lock
61     */
62    void release() throws IOException, InterruptedException;
63  
64    /**
65     * If supported, attempts to reap all the locks of this type by forcefully
66     * deleting the locks (both held and attempted) that have expired according
67     * to the given timeout. Lock reaping is different than coordinated lock revocation
68     * in that, there is no coordination, and the behavior is undefined if the
69     * lock holder is still alive.
70     * @throws IOException If there is an unrecoverable error reaping the locks
71     */
72    void reapExpiredLocks(long expireTimeoutMs) throws IOException;
73  
74    /**
75     * If supported, attempts to reap all the locks of this type by forcefully
76     * deleting the locks (both held and attempted). Lock reaping is different
77     * than coordinated lock revocation in that, there is no coordination, and
78     * the behavior is undefined if the lock holder is still alive.
79     * Calling this should have the same affect as calling {@link #reapExpiredLocks(long)}
80     * with timeout=0.
81     * @throws IOException If there is an unrecoverable error reaping the locks
82     */
83    void reapAllLocks() throws IOException;
84  
85    /**
86     * An interface for objects that process lock metadata.
87     */
88    interface MetadataHandler {
89  
90      /**
91       * Called after lock metadata is successfully read from a distributed
92       * lock service. This method may contain any procedures for, e.g.,
93       * printing the metadata in a humanly-readable format.
94       * @param metadata The metadata
95       */
96      void handleMetadata(byte[] metadata);
97    }
98  
99    /**
100    * Visits the locks (both held and attempted) of this type with the given
101    * {@link MetadataHandler}.
102    * @throws InterruptedException If there is an unrecoverable error
103    */
104   void visitLocks(MetadataHandler handler) throws IOException;
105 }