/*
* Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/

package com.nokia.mj.impl.rt.support;

import com.nokia.mj.impl.utils.Logger;

/**
 * MemoryManagerCtr is a class which can be used to try to keep number of
 * allocated objects in defined limits. This is handy in such objects that
 * consume very little Java heap, but consumes fair big amount of native
 * resources. In some cases (TCK, benchmarks) objects are allocated in a tight
 * loop which can cause out of memory situations.
 * <p>
 * The user must define two thresholds of object counts: the lower limit
 * defines a threshold when a young GC (if supported by the VM) should be
 * triggered. The upper limit defines a threshold when a full GC should be
 * triggered. If VM does not support young GC, then full GC is triggered
 * also when young GC threshold is exceeded. GC triggering happens
 * upon every instantiation of a new object when the number of objects
 * exceeds the defined limits.
 * <p>
 * A static instance of the memory manager is created per use case - which is
 * normally one problematic class. There can be more than one instances of
 * memory managers. When the user wants to increase instance count it should
 * get a new memory token using {@link #setSize} method and keep the reference
 * to memory token active as long as the problematic object is active. When a
 * memory token is created it will increse the object count of the associated
 * memory manager. If a threshold is exceeded, the memory manager will trigger
 * either young GC or full GC and asks the JVM to run finalizers.
 * <p>
 * When the problematic object is GC'ed also the memory token will be GC'ed.
 * Once the Memory token is finalized the token will decrease the amount of
 * allocated objects.
 * <p>
 * <pre>
 *
 * import com.nokia.mj.impl.rt.support.MemoryManagerCtr;
 *
 * class GraphicsObject
 * {
 *     private static MemoryManagerCtr mMemoryManager = new
                                 MemoryManagerCtr(20, 40);
 *     private Object mMemoryToken = mMemoryManager.getMemoryToken();
 *
 *     public GraphicsObject()
 *     {
 *         // ...
 *     }
 * }
 * </pre>
 * <p>
 * Note: There should be one static memory manager per problematic case/class.
 * There can be more than one instances of memory managers.
 */

public class MemoryManagerCtr
{

    /** A count of created objects.*/
    private int mInstanceCount = 0;

    /** A Threshold when a young GC should start.*/
    private int mYoungGcThreshold = 0;

    /** A Threshold when a full GC should start.*/
    private int mFullGcThreshold = 0;

    /** Tells if collection is going on */
    private boolean mCollectionOngoing = false;

    /** Should we trace operations.*/
    private boolean mTraceEnabled = false;


    /**
     * Creates a new counter based manager with given limits.
     *
     * @param youngGcThreshold number of objects when the young GC should
     *        be started to be used.
     * @param fullGcThreshold number of objects when the full GC should
     *        be started to be used.
     */
    public MemoryManagerCtr(int youngGcThreshold, int fullGcThreshold)
    {
        mYoungGcThreshold = youngGcThreshold;
        mFullGcThreshold = fullGcThreshold;
    }

    /**
     * Creates a new counter based memory token and associates it to the
     * memory manager. It will increase the object count of the memory manager
     * by one. The user should store the token as long the problematic object
     * is alive. Normally this is achived by defining the token as a member
     * variable and ensure that it is always instantiated when the problematic
     * object is created.
     * <p>
     * Once the token is finalized it will decrease the object count of the
     * memory manager.
     * @return A memory token.
     */
    public Object getMemoryToken()
    {
        return new MemoryToken();
    }

    /**
     * Informs the manager about the addition of one token.
     */
    private void incCtr()
    {
        // Info whether to run young GC, full GC or no GC at all.
        Boolean runYoungGc = null;
        synchronized (this)
        {
            mInstanceCount++;

            // Some other thread is doing the collection.
            if (mCollectionOngoing)
            {
                return;
            }

            if (mInstanceCount >= mYoungGcThreshold)
            {
                // Mark that we will request GC.
                mCollectionOngoing = true;

                traceString("Threshold exceeded: " + mInstanceCount);
                if (mInstanceCount < mFullGcThreshold)
                {
                    // Mark that we will request young GC.
                    runYoungGc = new Boolean(true);
                }
                else
                {
                    // Mark that we will request full GC.
                    runYoungGc = new Boolean(false);
                }
            }
        }

        // Do we need to run GC at all.
        if (runYoungGc != null)
        {
            if (runYoungGc.booleanValue() == true)
            {
                // Run fast collection if supported.
                traceString("Asking YoungGc");
                if (!JvmInternal.runYoungGenerationGc())
                {
                    // Run full collection.
                    traceString("Asking fullGc - youngGc not supported");
                    System.gc();
                }
            }
            else
            {
                // Run full collection.
                traceString("Asking fullGc");
                System.gc();
            }

            traceString("Asking finalization");
            // Ask the JVM to run finalizers.
            JvmInternal.runFinalization();

            synchronized (this)
            {
                // Mark that GC request has been sent.
                mCollectionOngoing = false;
            }
        }
    }

    /**
     * Informs the manager about finalization of one token.
     */
    private synchronized void decCtr()
    {
        mInstanceCount--;
    }

    private void traceString(String s)
    {
        if (mTraceEnabled)
        {
            Logger.WLOG(Logger.EUtils, "MemoryManagerCtr: " + s);
        }
    }

    /**
     * A class for increasing an decreasing the count of unfinalized
     * objects.
     */
    private class MemoryToken
    {
        /** Enables finalization */
        private Finalizer finalizer = new Finalizer()
        {
            public void finalizeImpl()
            {
                decCtr();
            }
        };

        /**
         * Creates a new counter based token.
         */
        private MemoryToken()
        {
            incCtr();
        }
    }

}