View Javadoc
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.netty5.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  }