/*
* Javolution - Java(TM) Solution for Real-Time and Embedded Systems
* Copyright (C) 2007 - 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 javolution.lang;
/**
* <p> This interface identifies objects which can be manipulated by
* value; a JVM implementation may allocate instances of this class
* on the stack and pass references by copy.</p>
*
* <p> {@link Realtime} instances can be "explicitly" allocated on the
* "stack" by executing within a {@link javolution.context.StackContext
* StackContext} and creating new instances with an {@link
* javolution.context.ObjectFactory ObjectFactory}.
* It is the responsibility of the users to ensure
* that "stack" objects are {@link javolution.context.StackContext#outerCopy
* copied out} when
* referenced outside of the stack context. For example:[code]
* public final class Complex implements Realtime, ValueType { ... }
* ...
* public Complex sumOf(Complex[] values) {
* StackContext.enter(); // Starts stack allocation.
* try {
* Complex sum = Complex.ZERO;
* for (Complex c : values) {
* sum = sum.plus(c);
* }
* return StackContext.outerCopy(sum); // Copies outside the stack.
* } finally {
* StackContext.exit(); // Resets stacks.
* }
* }[/code]</p>
*
* <p> <b>Note:</b> "Stack" allocation is not the only optimization that a VM
* can do on {@link ValueType}. The VM might decide not to perform any
* allocation at all and store values directly in registers.</p>
*
* @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
* @version 5.0, May 6, 2007
*/
public interface ValueType extends Immutable {
/**
* Returns a deep copy of this object allocated in the memory area (RTSJ)
* and/or {@link javolution.context.AllocatorContext context} (Javolution)
* of the calling thread (the one making the copy).
*
* @return an object identical to this object but allocated by the calling
* thread (e.g. on the "stack" of the calling thread).
*/
Object copy();
}