00001 /* 00002 * Copyright (c) 2000, 2020, Oracle and/or its affiliates. 00003 * 00004 * Licensed under the Universal Permissive License v 1.0 as shown at 00005 * http://oss.oracle.com/licenses/upl. 00006 */ 00007 #ifndef COH_WEAK_REFERENCE_HPP 00008 #define COH_WEAK_REFERENCE_HPP 00009 00010 #include "coherence/lang/compatibility.hpp" 00011 00012 #include "coherence/lang/abstract_spec.hpp" 00013 #include "coherence/lang/Object.hpp" 00014 #include "coherence/lang/Reference.hpp" 00015 #include "coherence/lang/TypedHandle.hpp" 00016 00017 COH_OPEN_NAMESPACE2(coherence,lang) 00018 00019 00020 /** 00021 * WeakReferences allow one Object to safely reference another without blocking 00022 * it from being destroyed. WeakReferences are necessary when building Object 00023 * graphs to avoid leaking the Object graph due to cyclical references. 00024 * 00025 * WeakReferences provide getter methods to safely obtain a normal Handle to the 00026 * weakly referenced Object if it still exists. Once the Object becomes only 00027 * weakly referenced its associated WeakReference will be automatically NULL'd 00028 * out so that the Object may be reclaimed. 00029 * 00030 * Consider a simple case of an Object tree, where parent's reference their 00031 * children, and children reference their parents. With normal reference 00032 * counting handles, the tree would be leaked even once all external references 00033 * to the tree have been dropped. To resolve this issue the tree could be 00034 * constructed such that parents reference their children via normal Handles, 00035 * but children reference their parents via WeakReferences. This way as long as 00036 * the parent is externally referenced its entire sub-tree will be retained. 00037 * Once all external Handles to the parent are dropped the entire tree will be 00038 * reclaimed as only WeakReferences would hold it together. 00039 * 00040 * Similar to MemberHandles, WeakReferences transfer their constness to their 00041 * referenced Object. That is if a View to a WeakReference is held then only the 00042 * View to the referenced Object will be available. 00043 * 00044 * Do to the need to call the get() which returns an Object::View or Handle 00045 * and then perform a cast, WeakReferences are somewhat cumbersome to make use 00046 * of. WeakHandle and WeakView are TypedHandle like wrappers for WeakReference 00047 * which makes using WeakReferences much simpler. In most cases these should be 00048 * used rather than direct use of WeakReferences. 00049 * 00050 * @see WeakHandle 00051 * @see WeakView 00052 * 00053 * @author mf 2008.04.10 00054 */ 00055 class COH_EXPORT WeakReference 00056 : public abstract_spec<WeakReference, 00057 extends<Object>, 00058 implements<Reference> > 00059 { 00060 // ----- static methods ------------------------------------------------- 00061 00062 public: 00063 /* 00064 * Return the WeakReference associated with the supplied Object. 00065 * 00066 * @param oh the Object to weakly reference. 00067 * 00068 * @return the WeakReference associated with the supplied Object. 00069 */ 00070 static WeakReference::Holder valueOf(Object::Holder oh); 00071 00072 00073 // ----- WeakReference interface ---------------------------------------- 00074 00075 public: 00076 /** 00077 * Return a Holder, containing a View to the referenced Object 00078 * 00079 * @return a view to the referenced Object 00080 */ 00081 virtual Object::Holder get() const = 0; 00082 00083 /** 00084 * Return a Holder to the referenced Object. 00085 * 00086 * @return a Handle unless the Object has become solely refereed by 00087 * Views. 00088 */ 00089 virtual Object::Holder get() = 0; 00090 }; 00091 00092 COH_CLOSE_NAMESPACE2 00093 00094 #endif // COH_WEAK_REFERENCE_HPP