hunt.net.buffer.ReferenceCounted source code

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  *   http://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 module hunt.net.buffer.ReferenceCounted;
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 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     bool 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     bool release(int decrement);
77 }