]>
Commit | Line | Data |
---|---|---|
7c673cae | 1 | // Copyright (c) 2016, Facebook, Inc. All rights reserved. |
11fdf7f2 TL |
2 | // This source code is licensed under both the GPLv2 (found in the |
3 | // COPYING file in the root directory) and Apache 2.0 License | |
4 | // (found in the LICENSE.Apache file in the root directory). | |
7c673cae FG |
5 | |
6 | package org.rocksdb; | |
7 | ||
8 | /** | |
9 | * AbstractNativeReference is the base-class of all RocksDB classes that have | |
10 | * a pointer to a native C++ {@code rocksdb} object. | |
11 | * <p> | |
12 | * AbstractNativeReference has the {@link AbstractNativeReference#dispose()} | |
13 | * method, which frees its associated C++ object.</p> | |
14 | * <p> | |
15 | * This function should be called manually, however, if required it will be | |
16 | * called automatically during the regular Java GC process via | |
17 | * {@link AbstractNativeReference#finalize()}.</p> | |
18 | * <p> | |
19 | * Note - Java can only see the long member variable (which is the C++ pointer | |
20 | * value to the native object), as such it does not know the real size of the | |
21 | * object and therefore may assign a low GC priority for it; So it is strongly | |
22 | * suggested that you manually dispose of objects when you are finished with | |
23 | * them.</p> | |
24 | */ | |
25 | public abstract class AbstractNativeReference implements AutoCloseable { | |
26 | ||
27 | /** | |
28 | * Returns true if we are responsible for freeing the underlying C++ object | |
29 | * | |
30 | * @return true if we are responsible to free the C++ object | |
31 | * @see #dispose() | |
32 | */ | |
33 | protected abstract boolean isOwningHandle(); | |
34 | ||
35 | /** | |
36 | * Frees the underlying C++ object | |
37 | * <p> | |
38 | * It is strong recommended that the developer calls this after they | |
39 | * have finished using the object.</p> | |
40 | * <p> | |
41 | * Note, that once an instance of {@link AbstractNativeReference} has been | |
42 | * disposed, calling any of its functions will lead to undefined | |
43 | * behavior.</p> | |
44 | */ | |
45 | @Override | |
46 | public abstract void close(); | |
47 | ||
48 | /** | |
49 | * @deprecated Instead use {@link AbstractNativeReference#close()} | |
50 | */ | |
51 | @Deprecated | |
52 | public final void dispose() { | |
53 | close(); | |
54 | } | |
55 | ||
56 | /** | |
57 | * Simply calls {@link AbstractNativeReference#dispose()} to free | |
58 | * any underlying C++ object reference which has not yet been manually | |
59 | * released. | |
60 | * | |
61 | * @deprecated You should not rely on GC of Rocks objects, and instead should | |
62 | * either call {@link AbstractNativeReference#close()} manually or make | |
63 | * use of some sort of ARM (Automatic Resource Management) such as | |
64 | * Java 7's <a href="https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html">try-with-resources</a> | |
65 | * statement | |
66 | */ | |
67 | @Override | |
68 | @Deprecated | |
69 | protected void finalize() throws Throwable { | |
70 | if(isOwningHandle()) { | |
71 | //TODO(AR) log a warning message... developer should have called close() | |
72 | } | |
73 | dispose(); | |
74 | super.finalize(); | |
75 | } | |
76 | } |