KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > context > ObjectPool


1 /*
2  * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3  * Copyright (C) 2006 - 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.context;
10
11 import javolution.JavolutionError;
12
13 /**
14  * <p> This abstract class represents an object pool (context-local).</p>
15  *
16  * <p> Objects are always allocated in the same memory area as the pool
17  * object itself. In other words, <code>NoHeapRealtimeThread</code>
18  * executing in <code>ScopedMemory</code> can safely use pools allocated in
19  * <code>ImmortalMemory</code>.
20  *
21  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
22  * @version 3.7, December 20, 2005
23  */
24 public abstract class ObjectPool/*<T>*/ {
25
26     /**
27      * Holds the current user of this pool.
28      */
29     transient Thread JavaDoc _user;
30
31     /**
32      * Indicates if this pool is in use by this context or an inner context.
33      */
34     transient boolean _inUse;
35
36     /**
37      * Default constructor.
38      */
39     protected ObjectPool() {
40     }
41
42     /**
43      * Returns the current user of this pool or <code>null</code> if none.
44      * If the user is the current thread, then this pool is the current pool.
45      *
46      * @return the pool current user.
47      */
48     public final Thread JavaDoc getUser() {
49         return _user;
50     }
51
52     /**
53      * Indicates if this pool is currently active for the current thread.
54      * The framework ensures that local pools are visible to their users only
55      * (concurrent executions are performed in an inner pool context).
56      * Operations on local pools are therefore thread-safe without requiring
57      * synchronization.
58      *
59      * @return <code>true</code> if this pool is local for the current thread;
60      * <code>false</code> otherwise.
61      * @throws JavolutionError if this operation is called upon a pool
62      * not currently {@link #inUse in use}.
63      */
64     public final boolean isLocal() {
65         if (_user == Thread.currentThread()) return true; // Local pool.
66 if (!_inUse) throw new JavolutionError(
67             "Access to inner pool or unused pool detected");
68         if (_user == null) return false; // Outer pool or heap pool.
69 throw new JavolutionError("Concurrent access to local pool detected");
70     }
71
72     /**
73      * Indicates if this pool is in use. A pool can be in use and not having a
74      * current user if the user has entered an inner pool.
75      *
76      * @return <code>true</code> if at least one thread has been allocating from
77      * this pool; <code>false</code> if this pool is not being used at
78      * all.
79      */
80     public final boolean inUse() {
81         return _inUse;
82     }
83
84     /**
85      * Returns the number of objects held by this pool.
86      *
87      * @return this pool size.
88      */
89     public abstract int getSize();
90
91     /**
92      * Sets the number of objects held by this pool (this method is typically
93      * used to preallocate the pool after creation).
94      *
95      * @param size this pool size.
96      */
97     public abstract void setSize(int size);
98
99     /**
100      * Returns the next available object from this pool. If there is none,
101      * a new object might be allocated.
102      *
103      * @return the next available object from this pool.
104      */
105     public abstract Object JavaDoc/*{T}*/ next();
106
107     /**
108      * Explicitly recycles the specified object. Callers should make sure that
109      * the recycled object is not going to be referenced anymore
110      * (e.g. temporary object). This method will raise an exception if the
111      * specified object do not belong to the current pool context (or heap for
112      * threads executing in a heap context).
113      *
114      * @param obj the object to recycle to this pool.
115      * @throws IllegalArgumentException if the specified object belongs to
116      * to a different pool.
117      */
118     public abstract void recycle(Object JavaDoc/*{T}*/ obj);
119
120     /////////////////////
121 // Control Methods //
122 /////////////////////
123
124     /**
125      * Recycles all the objects of this pool (all used objects become new).
126      *
127      * <p> Note: This method is called upon {@link PoolContext#exit exit}
128      * of a pool context for which this pool has been used.</p>
129      */
130     protected abstract void recycleAll();
131
132     /**
133      * Removes all objects (used and new) from this pool.
134      */
135     protected abstract void clearAll();
136
137 }
Popular Tags