KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > realtime > ObjectPool


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.JavolutionError;
12
13 /**
14  * This abstract class represents an object pool managed by a
15  * {@link PoolContext}. {@link #isLocal Local} pools are safe to use
16  * without synchronization. The real-time framework guarantees that
17  * no more than one thread can have access to any local pool at any
18  * given time. As for operations upon non-local pools, synchronization
19  * has to be performed on the pool itself to guarantee thread-safety.
20  *
21  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
22  * @version 3.0, February 16, 2005
23  */
24 public abstract class ObjectPool/*<T>*/ {
25
26     /**
27      * Holds a pool returning <code>null</code> values.
28      */
29     public static final ObjectPool NULL = new ObjectPool() {
30         public Object next() {
31             return null;
32         }
33         public void recycle(Object obj) {}
34         protected void recycleAll() {}
35         protected void clearAll() {}
36     };
37     
38
39     /**
40      * Holds the outer pool of this pool or <code>null</code> if none.
41      */
42     ObjectPool/*<T>*/ outer;
43
44     /**
45      * Holds the current user of this pool.
46      */
47     Thread user;
48
49     /**
50      * Indicates if this pool is in use by this context or an inner context.
51      */
52     boolean inUse;
53
54     /**
55      * Default constructor.
56      */
57     protected ObjectPool() {
58     }
59
60     /**
61      * Returns the current user of this pool or <code>null</code> if none.
62      *
63      * @return the pool current user.
64      */
65     public final Thread getUser() {
66         return user;
67     }
68
69     /**
70      * Indicates if this pool is actively used by the current thread.
71      * The framework ensures that local pools are visible to their users only
72      * (concurrent executions are performed in an inner pool context).
73      * Operations on local pools are therefore thread-safe without requiring
74      * synchronization.
75      *
76      * @return <code>true</code> if this pool is local for the current thread;
77      * <code>false</code> otherwise.
78      * @throws JavolutionError if this operation is called upon a pool
79      * not currently {@link #inUse in use}.
80      */
81     public final boolean isLocal() {
82         if (inUse) {
83             if (user == null) {
84                 return false; // Outer pool.
85 } else {
86                 if (user == Thread.currentThread()) {
87                     return true; // Local pool.
88 } else {
89                     throw new JavolutionError(
90                             "Concurrent access to local pool detected");
91                 }
92             }
93         } else {
94             throw new JavolutionError(
95                     "Access to inner pool or unused pool detected");
96         }
97     }
98
99     /**
100      * Indicates if this pool is in use. A pool can be in use and not having a
101      * current user if the user has entered an inner pool.
102      *
103      * @return <code>true</code> if at least one thread has been allocating from
104      * this pool; <code>false</code> if this pool is not being used at
105      * all (e.g. inner pool).
106      */
107     public final boolean inUse() {
108         return inUse;
109     }
110
111     /**
112      * Returns the outer pool of this pool.
113      *
114      * @return the outer pool or <code>null</code> if the outer is the heap.
115      */
116     public final ObjectPool/*<T>*/ getOuter() {
117         return outer;
118     }
119
120     /**
121      * Returns the next available object from this pool. If there is none,
122      * a new object from the {@link #getOuter outer} pool is moved to this pool
123      * and returned.
124      *
125      * @return the next available object from this pool.
126      */
127     public abstract Object/*T*/ next();
128
129     /**
130      * Recycles the specified object. Callers should make sure that the recycled
131      * object is not going to be referenced anymore (in a heap context it would
132      * be garbage collected).
133      *
134      * @param obj the object to recycle to this pool.
135      * @throws JavolutionError if the specified object do not belong to the pool.
136      */
137     public abstract void recycle(Object/*T*/ obj);
138
139     /////////////////////
140 // Control Methods //
141 /////////////////////
142
143     /**
144      * Recycles all the objects of this pool (all used objects become new).
145      *
146      * <p> Note: This method is called upon {@link PoolContext#exit exit}
147      * of a pool context for which this pool has been used.</p>
148      */
149     protected abstract void recycleAll();
150
151     /**
152      * Removes all objects (used and new) from this pool.
153      *
154      * <p> Note: This method is called upon {@link PoolContext#clear
155      * clearing} of the pool context this pool belongs to.
156      */
157     protected abstract void clearAll();
158
159 }
Popular Tags