01: /*
02: * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
03: * Copyright (C) 2007 - Javolution (http://javolution.org/)
04: * All rights reserved.
05: *
06: * Permission to use, copy, modify, and distribute this software is
07: * freely granted, provided that this notice is preserved.
08: */
09: package javolution.lang;
10:
11: /**
12: * <p> This interface identifies objects which can be manipulated by
13: * value; a JVM implementation may allocate instances of this class
14: * on the stack and pass references by copy.</p>
15: *
16: * <p> {@link Realtime} instances can be "explicitly" allocated on the
17: * "stack" by executing within a {@link javolution.context.StackContext
18: * StackContext} and creating new instances with an {@link
19: * javolution.context.ObjectFactory ObjectFactory}.
20: * It is the responsibility of the users to ensure
21: * that "stack" objects are {@link javolution.context.StackContext#outerCopy
22: * copied out} when
23: * referenced outside of the stack context. For example:[code]
24: * public final class Complex implements Realtime, ValueType { ... }
25: * ...
26: * public Complex sumOf(Complex[] values) {
27: * StackContext.enter(); // Starts stack allocation.
28: * try {
29: * Complex sum = Complex.ZERO;
30: * for (Complex c : values) {
31: * sum = sum.plus(c);
32: * }
33: * return StackContext.outerCopy(sum); // Copies outside the stack.
34: * } finally {
35: * StackContext.exit(); // Resets stacks.
36: * }
37: * }[/code]</p>
38: *
39: * <p> <b>Note:</b> "Stack" allocation is not the only optimization that a VM
40: * can do on {@link ValueType}. The VM might decide not to perform any
41: * allocation at all and store values directly in registers.</p>
42: *
43: * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
44: * @version 5.0, May 6, 2007
45: */
46: public interface ValueType extends Immutable {
47:
48: /**
49: * Returns a deep copy of this object allocated in the memory area (RTSJ)
50: * and/or {@link javolution.context.AllocatorContext context} (Javolution)
51: * of the calling thread (the one making the copy).
52: *
53: * @return an object identical to this object but allocated by the calling
54: * thread (e.g. on the "stack" of the calling thread).
55: */
56: Object copy();
57:
58: }
|