001 // LTMemory.java, created by wbeebee
002 // Copyright (C) 2001 Wes Beebee <wbeebee@mit.edu>
003 // Licensed under the terms of the GNU GPL; see COPYING for details.
004 package javax.realtime;
005
006 /**
007 * @author Wes Beebee <<a href="mailto:wbeebee@mit.edu">wbeebee@mit.edu</a>>
008 */
009
010 /** <code>LTMemory</code> represents a memory area, allocated per
011 * <code>RealtimeThread</code>, or for a group of real-time threads,
012 * guaranteed by the system to have linear time allocation. The memory
013 * area described by a <code>LTMemory</code> instance does not exist in
014 * the Java heap, and is not subject to garbage collection. Thus, it is
015 * safe to use a <code>LTMemory</code> object as the memory area associated
016 * with a <code>NoHeapRealtimeThread</code>, or to enter the memory area
017 * using the <code>enter()</code> method within a <code>NoHeapRealtimeThread</code>.
018 * An <code>LTMemory</code> area has an initial size. Enough memory must be
019 * committed by the completion of the constructor to satisfy this initial
020 * requirement. (Committed means that this memory must always be available
021 * for allocation). The initial memory allocation must behave, with respect
022 * to successful allocation, as if it were contiguous; i.e., a correct
023 * implementation must guarantee that any sequence of object allocations
024 * that could ever without exceeding a specified initial memory size will
025 * always succeed without exceeding that initial memory size and succeed
026 * for any instance of <code>LTMemory</code> with that initial memory size.
027 * <i>(Note: It is important to understand that the above statement does
028 * <b>not require that if the initial memory size is N and
029 * (sizeof(object1) + sizeof(object2) + ... + sizeof(objectn) = N) the
030 * allocations of objects 1 through n will necessarily succeed.)</b></i>
031 * Execution time of an allocator aloocating from this initial area must
032 * be linear in the size of the allocated object. Execution time of an
033 * allocator allocating from memory between initial and maximum is
034 * allowed to vary. Furthermore, the underlying system is not required to
035 * guarantee that memory between initial and maximum will always be available.
036 * (Node: to ensure that all requested memory is available set initial and
037 * maximum to the same value).
038 */
039 public class LTMemory extends ScopedMemory {
040
041 /** The logic associated with <code>this</code>. */
042 Runnable logic;
043
044 /** This constructs a LTMemory of the appropriate size (the maximum allowed
045 * to be allocated in the scope). The performance hit of allocating a
046 * large block of memory is taken when this constructor
047 * is called.
048 */
049 protected void initNative(long sizeInBytes) {}
050
051 /** Create an <code>LTMemory</code> of the given size.
052 *
053 * @param initialSizeInBytes The size in bytes of the memory to allocate for
054 * this area. This memory must be committed before
055 * the completion of the constructor.
056 * @param maxSizeInBytes The size in bytes of the memory to allocate for this area.
057 */
058 public LTMemory(long initialSizeInBytes,
059 long maxSizeInBytes) {
060 super(maxSizeInBytes);
061 initNative(initialSizeInBytes, maxSizeInBytes);
062 }
063
064 /** Create an <code>LTMemory</code> of the given size and logic.
065 *
066 * @param initialSizeInBytes The size in bytes of the memory to allocate for
067 * this area. This memory must be committed before
068 * the completion of the constructor.
069 * @param maxSizeInBytes The size in bytes of the memory to allocate for this area.
070 * @param logic The <code>run()</code> method of the given <code>Runnable</code>
071 * will be executed using <code>this</code> as its initial memory area.
072 */
073 public LTMemory(long initialSizeInBytes,
074 long maxSizeInBytes,
075 Runnable logic) {
076 this(initialSizeInBytes, maxSizeInBytes);
077 this.logic = logic;
078 }
079
080 /** Creates a <code>LTMemory</code> of the given size estimated by two instances of
081 * <code>SizeEstimator</code>.
082 *
083 * @param initial An instance of <code>SizeEstimator</code> used to give an estimate
084 * of the initial size. This memory must be committed before the
085 * completion of the constructor.
086 *
087 * @param maximum An instance of <code>SizeEstimator</code> used to give an estimate
088 * for the maximum bytes to allocate for this area.
089 */
090 public LTMemory(SizeEstimator initial,
091 SizeEstimator maximum) {
092 this(initial.getEstimate(), maximum.getEstimate());
093 }
094
095 /** Creates a <code>LTMemory</code> of the given size estimated by two instances of
096 * <code>SizeEstimator</code> and logic.
097 *
098 * @param initial An instance of <code>SizeEstimator</code> used to give an estimate
099 * of the initial size. This memory must be committed before the
100 * completion of the constructor.
101 * @param maximum An instance of <code>SizeEstimator</code> used to give an estimate
102 * for the maximum bytes to allocate for this area.
103 * @param logic The <code>run()</code> of the given <code>Runnable</code> will be
104 * executed using <code>this</code> as its initial memory area.
105 */
106 public LTMemory(SizeEstimator initial,
107 SizeEstimator maximum,
108 Runnable logic) {
109 this(initial, maximum);
110 this.logic = logic;
111 }
112
113 /** Creates a <code>LTMemory</code> of the given size. */
114 public LTMemory(long size) {
115 super(size);
116 initNative(size, size);
117 }
118
119 /** Gets the maximum allowable size for <code>this</code>.
120 *
121 * @return The maximum size for <code>this</code..
122 */
123 public long getMaximumSize() {
124 return size;
125 }
126
127 /** Prints the string "LTMemory".
128 *
129 * @return The string "LTMemory".
130 */
131 public String toString() {
132 return "LTMemory";
133 }
134
135
136
137 /** Initialize the native component of this MemoryArea (set up the MemBlock) */
138 private native void initNative(long minimum, long maximum);
139
140 /** Invoke this method when you're finished with the MemoryArea
141 * (could be a finalizer if we had finalizers...)
142 */
143
144 public void done() {
145 doneNative();
146 }
147
148 /** This will actually free the memory (if refcount = 0). */
149 private native void doneNative();
150 }