Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/lang/WeakReference.hpp

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

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.