/*
* Copyright (c) 2008 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;


/**
 * MemoryToken is a class which is used to inform the runtime about native
 * memory allocations happening outside of the JVM. The runtime uses the
 * information collected through MemoryToken to trigger garbage collections,
 * when needed.
 *
 * When the memory allocation regarding to a token changes, use {@link #setSize}
 * to update the information. The memory allocation is automatically reduced
 * when the object referencing MemoryToken instance is garbage collected, thus
 * there is no need to set the size to zero in this case.
 *
 * Add a MemoryToken instance to the Java class holding the native memory
 * handle. E.g.
 *
 * <pre>
 *
 * import com.nokia.mj.impl.rt.support.MemoryToken;
 * class GraphicsObject
 * {
 *     MemoryToken memoryToken = MemoryToken();
 *
 *     public GraphicsObject(int height, int width) {
 *         int sizeEstimate = height * width * 32;
 *         memoryToken.setSize(sizeEstimate)
 *
 *         // ...
 *     }
 * }
 *</pre>
 * @author Nokia Corporation
 * @version 1.0
 */

public class MemoryToken
{
    /** Assigned size of this memory token */
    private int tokenSize = 0;

    /** Enables finalization */
    private Finalizer finalizer = new Finalizer()
    {
        public void finalizeImpl()
        {
            doFinalize();
        }
    };

    static MemoryManager manager = new MemoryManager();

    /**
     * Creates a new token with zero sized memory.
     */
    public MemoryToken()
    {
    }

    /**
     * Creates a new token with given memory size. The call may take some time
     * if the construction triggers a garbage collection.
     *
     * @param size number of bytes assigned for this token
     */
    public MemoryToken(int size)
    {
        setSize(size);
    }

    /**
     * Changes the token's size. The call may take some time if it triggers a
     * garbage collection.
     *
     * @param newSize new number of bytes assigned for this token
     */
    public void setSize(int newSize)
    {
        // Get the old size and change size
        int oldSize;
        synchronized (this)
        {
            oldSize = tokenSize;
            tokenSize = newSize;
        }

        // Inform the manager about the size change
        manager.changeSize(oldSize, newSize);
    }

    private void doFinalize()
    {
        // Set size to zero
        setSize(0);
    }
}