KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > realtime > Realtime


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 import javolution.lang.Text;
11
12 /**
13  * <p> This interface identifies classes whose instances can be moved to
14  * different {@link ObjectSpace ObjectSpace} for higher
15  * performance and higher predictability.</p>
16  *
17  * <p> Real-time objects may contain references (direct or indirect) to
18  * other real-time objects. Whether these objects being referenced
19  * have to be moved along when a real-time object is moved to a different
20  * object space depends whether or not the referenced objects are heap
21  * allocated. Heap allocated objects (such as intrinsic data structures) are
22  * moved implicitly with the object; but non-heap objects (external objects)
23  * might have to be moved explicitly. For example:<pre>
24  * public class Person extends RealtimeObject { // Implements Realtime.
25  * private FastList children = new FastList(); // Also Realtime.
26  * ...
27  * public boolean move(ObjectSpace os) {
28  * if (super.move(os)) { // Propagates to external references.
29  * // The children list is intrinsic (heap allocated) but
30  * // it contains references to external persons (the children).
31  * for (Iterator i=children.fastIterator(); i.hasNext();) {
32  * ((Person)i.next()).move(os);
33  * }
34  * return true;
35  * }
36  * return false;
37  * }
38  * }</pre></p>
39  *
40  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
41  * @version 3.0, February 16, 2005
42  */
43 public interface Realtime {
44
45     /**
46      * Moves this real-time object to the specified object space.
47      *
48      * @param os the object space to move this real-time object to.
49      * @return <code>true</code> if this move has to be propagated to
50      * non-heap external references; <code>false</code> otherwise.
51      */
52     boolean move(ObjectSpace os);
53
54     /**
55      * Returns the textual representation of this real-time object
56      * (equivalent to <code>toString</code> except that the returned value
57      * can be allocated from the local context space).
58      *
59      * @return this object's textual representation.
60      */
61     Text toText();
62
63     /**
64      * This inner class represents an object space destination.
65      * Applications may create their own object space. Here are few examples
66      * of possible spaces with their defining characteristics.<UL>
67      * <LI><B>AGING:</B> Objects are accessible by all; recycling is
68      * done when the objects are old enough.<BR>Constraint:
69      * It assumes that old objects become obsolete and are not referenced
70      * anymore.
71      * <LI><B>FLIP:</B> Objects are accessible by all; recycling
72      * is done when the object space is flipped.<BR>Constraint:
73      * Objects from previous period (before flip) are discarded.</LI>
74      * </UL>
75      */
76     public static class ObjectSpace {
77         
78         /**
79          * Identifies the {@link HeapContext heap} space;
80          * objects are accessible by all; they are indirectly recycled
81          * through garbage collection (default space).
82          */
83         public static final ObjectSpace HEAP = new ObjectSpace();
84     
85         /**
86          * Identifies the {@link PoolContext stack} space;
87          * objects are accessible by the current thread only;
88          * they are recycled when the current thread
89          * {@link PoolContext#exit exits} the {@link PoolContext} scope
90          * where the object has been {@link ObjectFactory factory} produced.
91          */
92         public static final ObjectSpace LOCAL = new ObjectSpace();
93     
94         /**
95          * Identifies the {@link Context#getOuter() outer} object space;
96          * it is the object space after {@link PoolContext#exit exiting}
97          * the current {@link PoolContext} (typically the {@link #HEAP}
98          * or another {@link #LOCAL} space).
99          */
100         public static final ObjectSpace OUTER = new ObjectSpace();
101     
102         /**
103          * Identifies the hold space; objects are accessible by all;
104          * they are moved back to their original space when not held
105          * anymore (internal counter).
106          */
107         public static final ObjectSpace HOLD = new ObjectSpace();
108     
109         /**
110          * Default constructor (allows extension).
111          */
112         public ObjectSpace() {}
113     
114     }
115 }
Popular Tags