coherence/lang/HeapAnalyzer.hpp

/*
* HeapAnalyzer.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_HEAP_ANALYZER_HPP
#define COH_HEAP_ANALYZER_HPP

#include "coherence/lang/interface_spec.hpp"
#include "coherence/lang/Object.hpp"
#include "coherence/lang/TypedHandle.hpp"

COH_OPEN_NAMESPACE2(coherence,lang)


/**
* HeapAnalyzer provides a base diagnostics interface for tracking heap useage.
*
* There is at most one HeapAnalyzer registered with the system for the
* lifetime of the process. The HeapAnalyzer impelmentation may be specified
* via the "tangosol.coherence.heap.analyzer" system property. The property
* can be set to one of the following values:
* <ul>
*  <li>none      No heap analysis will be performed.</li>
*  <li>object    The coherence::lang::ObjectCountHeapAnalyzer will be used.</li>
*  <li>class     The coherence::lang::ClassBasedHeapAnalyzer will be used.</li>
*  <li>[custom]  The name of a class registered with the SystemClassLoader.</li>
* </ul>
*
* In the case where a custom class is specified, it must implement this
* interface.  The custom analyzer will be initialized as soon as the class
* is registered with the SystemClassLoader. As static initalization order
* cannot be guarenteed, this custom analyzer will not be notified of managed
* objects created earlier in the static initialization order.
*
* The active analyzer may be obtained from the System::getHeapAnalyzer()
* method.
*
* The HeapAnalyzer and Snapshot interfaces are intentionally narrow.
* Implementations are expected to provide usefull information via the toStream
* method, as well as by possibly augmenting the interfaces. The minimal
* interface is sufficient for detecting memory leaks.
*
* HeapAnalyzer::Snapshot::View vSnap = hAnalyzer->capture();
*   ...
*   ...
* std::cout << "Heap changed by: " << hAnalyzer->delta(vSnap) << std::endl;
*
* @see ObjectCountHeapAnalyzer
* @see ClassBasedHeapAnalyzer
*
* @author mf  2008.04.27
*/
class COH_EXPORT HeapAnalyzer
    : public interface_spec<HeapAnalyzer>
    {
    // ----- nested interface: Snapshot -------------------------------------

    public:
        /**
        * Snapshot provides a abstract mechanism for comparing successive
        * heap analysis points.
        */
        class COH_EXPORT Snapshot
            : public interface_spec<Snapshot>
            {
            // ----- Snapshot interface ---------------------------------

            public:
                /**
                * Return the number of registered objects reflected by this
                * snapshot.
                *
                * @return the number of registered objects
                */
                virtual int64_t getObjectCount() const = 0;
            };


    // ----- HeapAnalyzer interface -----------------------------------------

    public:
        /**
        * Capture a Snapshot of the current state of the heap.
        *
        * @return a Snapshot of the current state of the heap.
        */
        virtual Snapshot::View capture() const = 0;

        /**
        * Compute the delta between the supplied Snapshot and the current heap
        * state.
        *
        * @param vThat  the snapshot to compare against.
        *
        * @return a snapshot containing the delta
        */
        virtual Snapshot::View delta(Snapshot::View vThat) const = 0;

        /**
        * Return the number of registered objects.
        *
        * @return the number of registered objects
        */
        virtual int64_t getObjectCount() const = 0;

    protected:
        /**
        * Register a newly created Object with the system.
        *
        * This method is called automatically by coherence::lang::Object once
        * the Object has finished construction.
        *
        * @param o  the newly created Object.
        */
        virtual void registerObject(const Object& o) = 0;

        /**
        * Unregister an Object with the system.
        *
        * This method is called automatically by coherence::lang::Object
        * just prior to the deletion of the Object.  No new handles or views
        * may be created to the object.
        *
        * @param o  the Object to unregister
        */
        virtual void unregisterObject(const Object& o) = 0;


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

    public:
        /**
        * Ensure that the delta between the current heap and the supplied
        * snapshot is as expected.
        *
        * This method can be used to perform quick memory leak assertions.
        *
        * @code
        * HeapAnalyzer::Snapshot::View vSnapStart = System::getHeapAnalyzer()->capture();
        *   ...
        *   ...
        * HeapAnalyzer::ensureHeap(vSnapStart);
        * @endcode
        *
        * @param vSnap   the snapshot to ensure
        * @param cDelta  the allowable change in the heap's object count
        *
        * @throws IllegalStateException if the delta does not contain the
        *         expected amount. The text of the exception will include the
        *         output of the Snapshots toStream() method.
        */
        static void ensureHeap(Snapshot::View vSnap, int64_t cDelta = 0);

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

    friend class Object;
    };

COH_CLOSE_NAMESPACE2

#endif // COH_HEAP_ANALYZER_HPP

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