1 /*
2 * Copyright 2013 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.util;
17
18 /**
19 * A reference-counted object that requires explicit deallocation.
20 * <p>
21 * When a new {@link ReferenceCounted} is instantiated, it starts with the reference count of {@code 1}.
22 * {@link #retain()} increases the reference count, and {@link #release()} decreases the reference count.
23 * If the reference count is decreased to {@code 0}, the object will be deallocated explicitly, and accessing
24 * the deallocated object will usually result in an access violation.
25 * </p>
26 * <p>
27 * If an object that implements {@link ReferenceCounted} is a container of other objects that implement
28 * {@link ReferenceCounted}, the contained objects will also be released via {@link #release()} when the container's
29 * reference count becomes 0.
30 * </p>
31 */
32 public interface ReferenceCounted {
33 /**
34 * Returns the reference count of this object. If {@code 0}, it means this object has been deallocated.
35 */
36 int refCnt();
37
38 /**
39 * Increases the reference count by {@code 1}.
40 */
41 ReferenceCounted retain();
42
43 /**
44 * Increases the reference count by the specified {@code increment}.
45 */
46 ReferenceCounted retain(int increment);
47
48 /**
49 * Records the current access location of this object for debugging purposes.
50 * If this object is determined to be leaked, the information recorded by this operation will be provided to you
51 * via {@link ResourceLeakDetector}. This method is a shortcut to {@link #touch(Object) touch(null)}.
52 */
53 ReferenceCounted touch();
54
55 /**
56 * Records the current access location of this object with an additional arbitrary information for debugging
57 * purposes. If this object is determined to be leaked, the information recorded by this operation will be
58 * provided to you via {@link ResourceLeakDetector}.
59 */
60 ReferenceCounted touch(Object hint);
61
62 /**
63 * Decreases the reference count by {@code 1} and deallocates this object if the reference count reaches at
64 * {@code 0}.
65 *
66 * @return {@code true} if and only if the reference count became {@code 0} and this object has been deallocated
67 */
68 boolean release();
69
70 /**
71 * Decreases the reference count by the specified {@code decrement} and deallocates this object if the reference
72 * count reaches at {@code 0}.
73 *
74 * @return {@code true} if and only if the reference count became {@code 0} and this object has been deallocated
75 */
76 boolean release(int decrement);
77 }