coherence/lang/Object.hpp

/*
* Object.hpp
*
* Copyright 2001-2008 by Oracle. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_OBJECT_HPP
#define COH_OBJECT_HPP

#include "coherence/lang/compatibility.hpp"

#include "coherence/lang/cloneable_spec.hpp"
#include "coherence/lang/TypedHandle.hpp"
#include "coherence/lang/TypedHolder.hpp"
#include "coherence/native/NativeAtomic64.hpp"

#include <ostream>

COH_OPEN_NAMESPACE2(coherence,native)
class NativeCondition;
COH_CLOSE_NAMESPACE2

COH_OPEN_NAMESPACE2(coherence,lang)

class SmartMember;
class WeakReference;

using coherence::native::NativeAtomic64;
using coherence::native::NativeCondition;


/**
* Object is the base class for all Coherence managed objects.
*
* The interface for Object provides support basic operations such as equality,
* hashing, printing, cloning, synchronization, and notification.
*
* Objects have automatically managed memory, through built-in thread-safe
* reference counting. The reference count is maintained through the use of
* smart-pointers, known as handles. All references to an Object should be
* maintained through a handle rather then a raw pointer, or C++ reference.
*
* Each managed class includes inner definitions of handles which can be used
* to reference instance of that class, as well as derived class instances.
* These definitions provide functionality corresponding to const and non-const
* pointers. The names for these handles are Handle for the non-const, View for
* the const pointer equivalent, and Holder for a hybrid. The Holder type acts
* like a View but allows for a safe down-cast to a Handle, which will only
* succeede if the Holder was assigned from a Handle, and will fail with a
* ClassCastException if it had been assigned from a View. Note that in
* documentation the term "handle" is used to describe any handle type
* including Handle/View/Holder, while "Handle" referes to the specific
* "Handle" type.
*
* The handles are aware of the inheritance hierarchy, allowing direct
* assignment from a handle from a derived class to a handle of a base class.
* These up-casts are automatic, and an explict cast operation is rarely
* needed, except to resolve compiler type ambiguities. Assignment from a View
* to a Handle is also automatic as the const-interface of a class can
* naturanlly be considered a base-class. Assingment of a handle to a derived
* type is not automatic, and requires an explicit down-cast via the coherence
* cast<H>(h) function. The template paramter is the desired handle type, while
* the function parmeter is the handle to cast. If the supplied handle is
* non-NULL and is not an instance of the class associated with H, a
* ClassCastException will be thrown. There is a corresponding instanceof<H>(h)
* method which can be used to perform the type-check without the risk of
* triggering an exception. The use of instanceof, is optional, and is only
* needed if the type is actually in question.
*
* @code
* Object::Handle hObject = ...
* Foo::Handle    hFoo;
*
* if (instanceof<Foo::Handle>(hObject))
*   {
*   hFoo = cast<Foo::Handle>(hObject);
*   }
* @endcode
*
* These convenience handles are not thread-safe, and should not be used in a
* multi-threaded context if the handle will be updated. They should only be
* used as local variables, though they are free to reference objects shared
* by many threads. The most common place where thread-safe handles are
* needed is for data members of managed objects. For these cases the
* Coherence API includes a variety of thread-safe handles/views, namely
* MemberHandle, MemberView, MemberHolder, WeakHandle, WeakView. It is strongly
* encouraged that any class which extends from Object use only thread-safe
* handles when referencing other Objects.
*
* By convention managed objects will also block direct external access to
* their constructor and destructors. Constructors are accessed via public
* static "create" factory methods. The copy constructor is accessed via the
* public virtual "clone" method. Destructors are protected and destruction
* is triggered automatically when the internal reference count reaches zero.
*
* @see class_spec     for defining non-cloneable classes
* @see cloneable_spec for defining cloneable classes
* @see abstract_spec  for defining abstract classes
* @see interface_spec for defining interfaces
* @see throwable_spec for defining exceptions
*
* @author mf 2007.07.05
*/
class COH_EXPORT Object
    : public cloneable_spec<Object,
        extends<> >
    {
    friend class factory<Object>;

    // ----- constructors ---------------------------------------------------

    protected:
        /**
        * Construct a new Object.
        */
        Object();

        /**
        * Copy constructor.
        */
        Object(const Object& that);

        /**
        * Destructor.
        */
        virtual ~Object();

    private:
        /**
        * Blocked assignment operator.
        *
        * @internal
        */
        Object& operator=(const Object&);


    // ----- Object interface -----------------------------------------------

    public:
        /**
        * Return true iff the specified Object is "equal" to this Object.
        *
        * This method implements an <i>equivalence relation</i> on Objects:
        * <ul>
        * <li>It is <i>reflexive</i>: for any non-null handle
        *     <code>h</code>, <code>h->equals(h)</code> must return
        *     <code>true</code>.
        * <li>It is <i>symmetric</i>: for any non-null handles
        *     <code>h1</code> and <code>h2</code>, <code>h1->equals(h2)</code>
        *     should return <code>true</code> if and only if
        *     <code>h2->equals(h1)</code> returns <code>true</code>.
        * <li>It is <i>transitive</i>: for any non-null handles
        *     <code>h1</code>, <code>h2</code>, and <code>h3</code>, if
        *     <code>h1->equals(h2)</code> returns <code>true</code> and
        *     <code>h2->equals(h3)</code> returns <code>true</code>, then
        *     <code>h1->equals(h3)</code> should return <code>true</code>.
        * <li>It is <i>consistent</i>: for any non-null handles
        *     <code>h1</code> and <code>h2</code>, multiple invocations of
        *     <tt>h1->equals(h2)</tt> consistently return <code>true</code>
        *     or consistently return <tt>false</tt>, provided no
        *     information used in comparisons on the objects is modified.
        * <li>If the supplied handle is <tt>NULL</tt> then <tt>false</tt>
        *     must be returned.
        * </ul>
        *
        * The default implementation is a reference equality comparision.
        *
        * @param v  the Object::View to compare against, may be <tt>NULL</tt>
        *
        * @return <tt>true</tt> iff the given handle references an Object
        *         that is "equal" to this Object
        *
        * @see #equals(Object::View v1, Object::View v2)
        */
        virtual bool equals(Object::View v) const;

        /**
        * Return a hash code value for the Object. This method is supported
        * for the benefit of hash-based containers.
        *
        * The general contract of <code>hashCode</code> is:
        * <ul>
        * <li>Whenever it is invoked on the same Object more than once
        *     during an execution of an application, the <tt>hashCode</tt>
        *     method must consistently return the same value, provided no
        *     information used in <tt>equals</tt> comparisons on the object
        *     is modified. This value need not remain consistent from one
        *     execution of an application to another execution of the same
        *     application.
        * <li>If two Objects are equal according to the <tt>equals</tt>
        *     method, then calling the <code>hashCode</code> method on each
        *     of the two Objects must produce the same value.
        * <li>It is <em>not</em> required that if two Objects are unequal
        *     according to the <tt>equals</tt> method, then calling the
        *     <tt>hashCode</tt> method on each of the two objects must
        *     produce distinct results. However, the programmer should be
        *     aware that producing distinct results for unequal objects may
        *     improve the performance of hash-based containers.
        * </ul>
        *
        * The default implementation is identity based.
        *
        * @return a hash code value for this Object
        */
        virtual size32_t hashCode() const;

        /**
        * Return a handle to a deep copy of the original Object.
        *
        * The returned clone should be sufficient decoupled from the original
        * such that futher modifications to the original Object will not be
        * visible within the cloned object.  More specifically, the following
        * is expected to hold true.
        *
        * @code
        * h->clone() != h &&
        * h->clone()->equals(h) &&
        * typeid(*h) == typeid(*(h->clone()))
        * @endcode
        *
        * Note that this suggests that data members of a cloned object are
        * expected to cloned if they are tested for equality (via a call to
        * equals) within the cloned object's equals method.  If a data member
        * is compared via reference equality, or not even considered within
        * equals, then it does not necessarily need to be deeply cloned.
        *
        * Object is cloneable, but it's derived classes are not automatically
        * cloneable, and CloneNotSupportedExceptions are thrown. To be made
        * cloneable the derived class should use the cloneable_spec<> helper
        * template in its declaration, and define a protected copy constructor.
        * The derived class does not need to override this method, as that is
        * done by the cloneable_spec<> template.
        *
        * @return a copy of the original Object
        *
        * @throws CloneNotSupportedException if the object cannot be deep
        *         cloned
        *
        * @see isImmutable()
        */
        virtual Object::Handle clone() const;

        /**
        * Return <tt>true</tt> iff no further changes can be made to the
        * Object, that would effect the outcome of a call to its equals method.
        * Except for Objects which are naturally immutable (such as String),
        * being immutable generally implies that the Object is only referenced
        * via const pointers or views. Objects which hold references to child
        * Objects, may need to take the immutability of their children into
        * account when determining their own immutability.
        *
        * This extended check is not performed by the default implementation,
        * but can be integrated into the immutability checks by overiding
        * this method, as well as making use of MemberHandles to reference
        * child Objects.
        *
        * A typicial derived implementaiton may look as follows:
        *
        * <pre>
        * bool isImmutable() const
        *     {
        *     if (m_fImmutable) // check recorded state
        *         {
        *         return true; // already marked as immutable, avoid calculation
        *         }
        *     else if (Object::isImmutable()) // ensure shallow immutability
        *         {
        *         // ensure deap immutability
        *         if (m_child1->isImmutable() && m_child2->isImmutable() ...
        *                                     && m_childN->isImmutable())
        *             {
        *             // record and return immutability
        *             return m_fImmutable = true;
        *             }
        *         // some Objects which comprise this Object are still mutable
        *         }
        *     return false;
        *     }
        * </pre>
        *
        * The default implementation return true iff the Object is only
        * referenced via const pointers and or views.
        *
        * @return true iff the Object is immutable
        */
        virtual bool isImmutable() const;

        /**
        * Output a human-readable description of this Object to the given
        * stream.
        *
        * coherence::lang::operator<<(std::ostream, Object::View) is defined
        * and will call into the toStream method, to output Objects.  If a
        * manged String object is desired, the COH_TO_STRING macro can be used
        * to build up a String from streamable contents.
        *
        * @code
        * Object::View vKey   = ...
        * Object::View vValue = ...
        * std::cout << vKey << " = " << vValue << std::endl;
        *
        * String::Handle hs = COH_TO_STRING(vKey << " = " << vValue);
        * @endcode
        *
        * @param out  the stream used to output the description
        */
        virtual void toStream(std::ostream& out) const;

        /**
        * Return an estimate as to the shallow byte size of the object.
        *
        * The shallow size should not include the cost of referenced managed
        * objects, or non-fixed dynamically allocated memory. That for a
        * given object it is assumed that a call to this method will always
        * return the same value.
        *
        * For classes defined via the class_spec template an auto-generated
        * implementation is provided which utilizes the standard C sizeof()
        * operator to compute the size.  User defined implementations are
        * only needed to account for dymacic memory allocated during
        * construction.
        *
        * @return the approximate shallow byte size of the object
        */
        virtual size32_t sizeOf() const;


    // ----- synchronization and notification interface ---------------------

    public:
        /**
        * Block the calling thread while waiting for notification.
        *
        * The caller must be synchronized on the Object's monitor when calling
        * this method. The monitor will be automatically released while the
        * thread awaits notification, and reacquired before the call returns.
        * This method is subject to spurious wakeups, and the caller should
        * externally verify that the condition being waited for has been
        * reached.
        *
        * To synchronize on an object, the COH_SYNCHRONIZED macro is used.
        * The macro defines a block of code which is a critical section,
        * during which no other thread may acquire synchronization on the same
        * object.
        *
        * @code
        * Object::Handle hObject = ...
        * COH_SYNCHRONIZED (hObject)
        *   {
        *   while (testSomeCondition() == false)
        *     {
        *     hObject->wait();
        *     }
        *   }
        * @endcode
        *
        * @see notify
        * @see notifyAll
        */
        void wait() const;

        /**
        * Block the calling thread while waiting for notification.
        *
        * The caller must be synchronized on the Object's monitor when calling
        * this method. The monitor will be automatically released while the
        * thread awaits notification, and reacquired before the call returns.
        * This method is subject to spurious wakeups, and the caller should
        * externally verify that the condition being waited for has been
        * reached.
        *
        * @param cMillis  the duration to wait to wait, a value of zero will
        *                 wait indefinitely for notification
        *
        * @see wait
        * @see notify
        * @see notifyAll
        */
        void wait(int64_t cMillis) const;

        /**
        * Notify a waiting thread.
        *
        * The caller must be synchronized on the Object's monitor when calling
        * this method.
        *
        * @code
        * Object::Handle hObject = ...
        * COH_SYNCHRONIZED (hObject)
        *   {
        *   setSomeCondition(true);
        *   hObject->notify();
        *   }
        * @endcode
        *
        * @see wait
        * @see notifyAll
        */
        void notify() const;

        /**
        * Notify all waiting threads.
        *
        * The caller must be synchronized on the Object's monitor when calling
        * this method.
        *
        * @see wait
        * @see notify
        */
        void notifyAll() const;

    private:
        /**
        * Enter the Object's monitor, waiting as long as necessary.
        * <p/>
        * The monitor supports recursive entry, allowing the same thread to
        * reenter the same monitor. The thread must exit the monitor the
        * same number of times, by calling the exitMonitor, for the Monitor
        * to be released.
        *
        * It is recommended that the COH_SYNCHRONIZED macro be used in place
        * of direct calls to enterMonitor/exitMonitor. The use of this macro
        * only requires public level view access to the Object
        * <pre>
        * // outside of synchronized block
        * COH_SYNCHRONIZED (vObject) // monitor entered
        *     {
        *     // critical section goes here
        *     // ...
        *     // ...
        *     } // monitor automatically exited
        * // outside of synchronized block
        * </pre>
        *
        * @see exitMonitor
        */
        void enterMonitor() const;

        /**
        * Exit the Object's monitor.
        *
        * This must be called by the thread which locked the monitor.
        *
        * @see enterMonitor
        */
        void exitMonitor() const;

        /**
        * Acquire the shared read lock for the Object's data members.
        *
        * The data member read/write lock is intended for protecting small
        * sections of non-blocking code, such as primitive data-member access
        * and assignment. The read lock does support limited recursion,
        * and each call to acquire must be matched by a corresponding
        * call to release. For more advanced read/write lock support the
        * ThreadGate class should be utilized.
        *
        * The member read lock may be acquired using the
        * COH_SYNCHRONIZED_MEMBER_READ macro.
        *
        * @see SynchronizedMemberReadBlock
        * @see coherence::util::ThreadGate
        */
        void acquireMemberReadLock() const;

        /**
        * Release the read lock for the Object's data members
        */
        void releaseMemberReadLock() const;

        /**
        * Acquire the write lock for the Object's data members.
        *
        * Unlike the member read lock, write locks do not support
        * recursion, nor do they support lock promotion from a read to a
        * write lock. Attempts to use them such a manor will result in
        * dead-lock.
        *
        * The member write lock may be acquired using the
        * COH_SYNCHRONIZED_MEMBER_WRITE macro.
        *
        * @see SynchronizedMemberWriteBlockm
        */
        void acquireMemberWriteLock() const;

        /**
        * Release the write lock for the Object's data members.
        */
        void releaseMemberWriteLock() const;


    // ----- reference counting interface -----------------------------------

    public:
        /**
        * @internal
        *
        * Increment the non-const reference count for this Object.
        *
        * NOTE: This method is intended for use by smart pointers such as
        * TypedHandle, and its usage should be limited.
        *
        * This operation must return <tt>NULL</tt> if the Object is
        * immutable.
        *
        * @return a pointer to the Object or <tt>NULL</tt> if new non-const
        *         attachments are disallowed
        *
        * @see _detach
        */
        Object* _attach();

        /**
        * @internal
        *
        * Increment the const reference count for this Object.
        *
        * NOTE: This method is intended for use by smart pointers such as
        * TypedHandle, and its usage should be limited.
        *
        * @return a constant pointer to the Object, or <tt>NULL</tt> if new
        *         const attachments are disallowed
        *
        * @see _detach
        */
        const Object* _attach() const;

        /**
        * @internal
        *
        * Return a WeakReference to this Object.
        *
        * Unlike non-weak attachments, there is no corresponding _detachWeak,
        * as the return type is a handle.
        *
        * See the WeakHandle template class which will automatically manage
        * the weak attachment to the Object.
        *
        * NOTE: This method is intended for use by smart pointers such as
        * WeakHandle, and its usage should be limited.
        *
        * @see WeakReference
        * @see WeakHandle
        *
        * @return a WeakReference to this Object
        */
        TypedHandle<WeakReference> _attachWeak();

        /**
        * @internal
        *
        * Return a WeakReference View to this Object.
        *
        * Unlike non-weak attachments, there is no corresponding _detachWeak,
        * as the return type is a handle.
        *
        * See the WeakView template class which will automatically manage the
        * weak attachment to the Object.
        *
        * NOTE: This method is intended for use by smart pointers such as
        * WeakHandle, and its usage should be limited.
        *
        * @see WeakReference
        * @see WeakView
        *
        * @return a WeakReference to this Object
        */
        TypedHandle<const WeakReference> _attachWeak() const;

        /**
        * @internal
        *
        * Decrement the non-const reference count for this Object and
        * automatically delete this Object if the total reference count drops
        * to zero.
        *
        * NOTE: This method is intended for use by smart pointers such as
        * TypedHandle, and its usage should be limited.
        *
        * @see _attach
        */
        void _detach();

        /**
        * @internal
        *
        * Decrement the const reference count for this Object and
        * automatically delete this Object if the total reference count drops
        * to zero.
        *
        * NOTE: This method is intended for use by smart pointers such as
        * TypedHandle, and its usage should be limited.
        *
        * @see _attach
        */
        void _detach() const;


    // ----- life cycle events ----------------------------------------------

    protected:
        /**
        * Event called once the Object has finished being constructed.
        * Specifically when the first attachment is made. This provides a
        * safe point at which Handles/Views to "this" can be created. It is
        * not safe to create Handles/Views to an Object from within its
        * constructor, thus any operations which rely upon this should be
        * deferred until the onInit event is triggered.
        *
        * As with all event methods any derived implementation should
        * include a call to the super class's implementation. Specifically
        * delegation to Object::onInit() must eventually occur or an
        * IllegalStateException will result.
        *
        * The default implementation calls the onInit() method of each of the
        * Object's SmartMembers.
        */
        virtual void onInit();

        /**
        * Event called when the Object becomes only referenced via const
        * pointers (Views). Assuming a const-correct class, once this method
        * returns no further visible changes can be made to the object.
        *
        * As with all event methods any derived implementation should include
        * a call to the super class's implementation.
        *
        * The default implmenetation calls the onConst() method of each of
        * the Object's SmartMembers.
        *
        * @see isImmutable
        */
        virtual void onConst();


    // ----- helper methods -------------------------------------------------

    protected:
        /**
        * Return a reference to the constructed base Object.
        *
        * This reference is suitable for use in derived class constructors as
        * the Object class will have completed construction.
        *
        * @return the Object reference
        */
        Object& self();

        /**
        * Return a reference to the constructed base Object.
        *
        * @return the const Object reference
        */
        const Object& self() const;

    private:
        /**
        * Increment the Object's reference count.
        *
        * @param fHandle  true if the attachment is via a handle, false if
        *                 via a view
        *
        * @return true iff the attachment succeeded
        */
        bool attachInternal(bool fHandle) const;

        /**
        * Decrement the Object's reference count.
        *
        * @param fHandle  true if the detachment is via a handle, false if
        *                 via a view
        */
        void detachInternal(bool fHandle) const;

        /**
        * Return the WeakReference associated with this Object, creating one
        * if necessary.
        *
        * @return the WeakReference associated with this Object
        */
        TypedHandle<WeakReference> ensureWeakReference() const;

        /**
        * Return the NativeCondition which backs the Object's monitor,
        * creating one if necessary.
        *
        * The life of the returned condition is bounded to the Object.
        *
        * @return the NativeCondition which backs the Object's monitor
        */
        NativeCondition& ensureMonitor() const;


    // ----- static methods -------------------------------------------------

    public:
        /**
        * Compare two Objects for equality.
        *
        * This method implements an <i>equivalence relation</i> for two
        * potentially <tt>NULL</tt> handles.
        *
        * @param v1  the first Object to compare
        * @param v2  the second Object to compare
        *
        * @return  <tt>true</tt> iff v1 and v2 are <tt>NULL</tt> or
        *          reference Objects which are equal
        */
        static bool equals(Object::View v1, Object::View v2);

        /**
        * Return a clone of the supplied Object.
        *
        * @param v  the Object to clone
        *
        * @return a clone of the Object, or NULL if NULL was supplied
        */
        static Object::Handle clone(Object::View v);

        /**
        * Output an Object to a stream.
        *
        * If the handle is NULL then the string "NULL" will be written to the
        * stream.
        *
        * @param out  the stream used to output the Object
        * @param v    the Object to output
        */
        static void toStream(std::ostream& out, Object::View v);

    // ----- memory management ----------------------------------------------

    public:
        /**
        * @internal
        *
        * Default allocator for Objects.
        *
        * @param cb  the number of bytes to allocate
        *
        * @return the allocated memory
        *
        * @throws IllegalStateException if the allocation fails
        */
        static void* operator new(size_t cb);

        /**
        * @internal
        *
        * Default deallocator for Objects.
        *
        * @param po  the memory to deallocate
        */
        static void operator delete(void* po);


    // ----- data members ---------------------------------------------------

    private:
        /**
        * 64bit atomic Object lifecycle.
        */
        mutable NativeAtomic64 m_atomicLifeCycle;

        /**
        * Pointer to the NativeCondition which is used to implement the
        * Object's monitor functionality.
        *
        * The validity of this pointer is governed by the Object's
        * life-cycle. A non-NULL pointer is not sufficient to ensure that
        * the condition is ready for use.
        */
        mutable NativeCondition* m_pCondition;

        /**
        * The WeakReference to this Object.
        *
        * The validity of this handle is governed by the Object's life-cycle.
        * A non-NULL handle is not sufficient to ensure that the reference is
        * ready for use.
        */
        mutable TypedHandle<WeakReference> m_hWeakThis;

        /**
        * Pointer to the top of the stack of SmartMembers bound to this
        * Object, or NULL if none exist.
        */
        SmartMember* m_pSmartMemberStack;


    // ----- friends --------------------------------------------------------

    friend class SmartMember;
    friend class SynchronizedBlock;
    friend class SynchronizedMemberReadBlock;
    friend class SynchronizedMemberWriteBlock;
    friend class System;
    };


// ----- non-member operators and functions ---------------------------------

/**
* Output a human-readable description of the specified Object to the given
* stream.
*
* @param out  the stream used to output the description
* @param o    the Object to describe
*
* @return the supplied stream
*/
COH_EXPORT std::ostream& operator<<(std::ostream& out, const Object& o);

/**
* @internal
*
* Specialized extends implementation for classes deriving directly from Object.
*
* This specialization bring Object in virtually (as interfaces dervie from it
* virtually as well.
*/
template<class A> class COH_EXPORT_SPEC extends<Object, A>
    : public virtual Object
    {
    public:
        typedef Void<Object> inherited;
        typedef A            alias;
    };

/**
* @internal
*
* Specialized extends implementation for classes deriving directly from Object.
*
* This specialization bring Object in virtually (as interfaces dervie from it
* virtually as well.
*/
template<> class COH_EXPORT_SPEC extends<Object, Void<Object> >
    : public virtual Object
    {
    public:
        typedef Void<Object> inherited;
        typedef Void<Object> alias;
    };

COH_CLOSE_NAMESPACE2

#endif // COH_OBJECT_HPP

Copyright (c) 2000-2008 Oracle. All rights reserved.