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.hbase.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 IOException If there is an unrecoverable error
103 */
104 void visitLocks(MetadataHandler handler) throws IOException;
105 }