/*
 * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
 * Copyright (C) 2005 - Javolution (http://javolution.org/)
 * All rights reserved.
 * 
 * Permission to use, copy, modify, and distribute this software is
 * freely granted, provided that this notice is preserved.
 */
package javolution37.javolution.realtime;

import javolution37.javolution.lang.Reference;
import javolution37.javolution.lang.Text;

/**
 * 
 This class encapsulates a reference allocated on the current stack
 *     when executing in {@link PoolContext}. The reachability level of a
 *     stack reference is the scope of the {@link PoolContext} in which it
 *     has been {@link #newInstance created}.
 *     
 * 
 Stack references are automatically cleared based upon their 
 *     reachability level like any java.lang.ref.Reference.
 *     In other words, stack references are automatically cleared when exiting
 *     the {@link PoolContext} where they have been factory produced.
 *     
 * 
 Stack references are typically used by functions having more than one
 *     return value to avoid creating new objects on the heap. For example:[code]
 *     // Returns both the position and its status.
 *     public Coordinates getPosition(Reference status) {
 *         ...
 *     }
 *     ...
 *     StackReference status = StackReference.newInstance(); // On the stack.
 *     Coordinates position = getPosition(status);
 *     if (status.get() == ACCURATE) ...[/code] 
 *     See also {@link ConcurrentContext} for examples of 
 *     {@link StackReference} usage.
 *          
 * @author  Jean-Marie Dautelle
 * @version 3.4, July 3, 2005
 */
public final class StackReference  extends RealtimeObject implements
        Reference  {

    /**
     * Holds the factory.
     */
    private static final Factory FACTORY = new Factory() {
        protected Object create() {
            return new StackReference();
        }

        protected void cleanup(Object obj) {
            ((StackReference) obj)._value = null;
        }
    };

    /**
     * Holds the reference value.
     */
    private  T _value;

    /**
     * Default constructor (private, instances should be created using 
     * factories).
     */
    private StackReference() {
    }

    /**
     * Returns a new stack reference instance allocated on the current stack
     * when executing in {@link PoolContext}.
     * 
     * @return a local reference object.
     */
    public static  StackReference   newInstance() {
        return (StackReference) FACTORY.object();
    }
    /**
     * Returns the text representation of the current value of this 
     * reference.
     *
     * @return Text.valueOf(this.get())
     */
    public Text toText() {
        return Text.valueOf(this.get());
    }
    
    // Implements Reference interface.
    public  T get() {
        return _value;
    }

    // Implements Reference interface.
    public void set( T value) {
        _value = value;
    }
}