KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > realtime > StackReference


1 /*
2  * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3  * Copyright (C) 2005 - Javolution (http://javolution.org/)
4  * All rights reserved.
5  *
6  * Permission to use, copy, modify, and distribute this software is
7  * freely granted, provided that this notice is preserved.
8  */
9 package javolution.realtime;
10
11 import javolution.lang.Reference;
12
13 /**
14  * <p> This class encapsulates a reference allocated on the current stack
15  * when executing in {@link PoolContext}. The reachability level of a
16  * stack reference is the scope of the {@link PoolContext} in which it
17  * has been {@link #newInstance created}.</p>
18  *
19  * <p> Stack references are automatically cleared based upon their
20  * reachability level like any <code>java.lang.ref.Reference</code>.
21  * In other words, stack references are automatically cleared when exiting
22  * the {@link PoolContext} where they have been factory produced.</p>
23  *
24  * <p> Stack references are typically used by functions having more than one
25  * return value to avoid creating new objects on the heap. For example:<pre>
26  * // Returns both the position and its status.
27  * public Coordinates getPosition(Reference&lt;Status&gt; status) {
28  * ...
29  * }
30  * ...
31  * StackReference&lt;Status&gt; status = StackReference.newInstance(); // On the stack.
32  * Coordinates position = getPosition(status);
33  * if (status.get() == ACCURATE) ...</pre>
34  * See also {@link ConcurrentContext} for examples of
35  * {@link StackReference} usage.</p>
36  *
37  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
38  * @version 3.4, July 3, 2005
39  */
40 public final class StackReference/*<T>*/extends RealtimeObject implements
41         Reference/*<T>*/{
42
43     /**
44      * Holds the factory.
45      */
46     private static final Factory FACTORY = new Factory() {
47         protected Object create() {
48             return new StackReference();
49         }
50
51         protected void cleanup(Object obj) {
52             ((StackReference) obj)._value = null;
53         }
54     };
55
56     /**
57      * Holds the reference value.
58      */
59     private Object/*T*/_value;
60
61     /**
62      * Default constructor (private, instances should be created using
63      * factories).
64      */
65     private StackReference() {
66     }
67
68     /**
69      * Returns a new stack reference instance allocated on the current stack
70      * when executing in {@link PoolContext}.
71      *
72      * @return a local reference object.
73      */
74     public static/*<T>*/StackReference /*<T>*/newInstance() {
75         return (StackReference) FACTORY.object();
76     }
77
78     // Implements Reference interface.
79 public Object/*T*/get() {
80         return _value;
81     }
82
83     // Implements Reference interface.
84 public void set(Object/*T*/value) {
85         _value = value;
86     }
87 }
Popular Tags