com.dautelle.realtime
Class PoolContext

java.lang.Object
  com.dautelle.realtime.Context
      com.dautelle.realtime.PoolContext

public final class PoolContext

extends Context

This class represents a pool context; it is used to reduce memory allocation and its "evil-brother" garbage collection.

Threads executing in a pool context may allocate objects from the context's pools and recycle objects to the context's pool. As for all contexts, pool context are thread-local and can be reused over and over by the same thread.

Objects allocated within a pool context should not be directly referenced outside of the context unless they have been exported first. If you follow this simple rule, then pool context are completely safe. In fact, pool contexts promote the use of immutable objects (as their allocation cost is being significantly reduced) and often lead to safer, faster and more robust applications.

Recycling occurs automatically upon exit and is typically very fast as all objects are recycled in block (faster than GC). Individual recycling is also supported for methods having access to the object pool (e.g. member methods on their own pool). The ArrayPool class has its pools public and therefore allows for individual recycling of any array.

Upon thread termination, pool objects associated to a thread are candidate for garbage collection (the "export rule" guarantees that these objects are not referenced anymore). Nonetheless, it is possible to move pools' objects to the heap directly (without waiting for thread finalization) by calling the clear() static method. Applications exporting to the heap may also clear from time to time in order to keep the memory footprint low (this allows for all unused objects to be garbage collected).

Version:

6.0, May 24, 2004

Author:

Jean-Marie Dautelle

Method Summary

static void	clear() Clears unused pools for the current thread.
static void	enter() Enters a PoolContext.
static void	exit() Exits the current PoolContext.

Methods inherited from class com.dautelle.realtime.Context

current, getInner, getOuter, getOwner, pop, push, push

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

enter

public static void enter()

Enters a PoolContext.

exit

public static void exit()

Exits the current PoolContext.

Throws:

java.lang.ClassCastException - if the current context is not a PoolContext.

clear

public static void clear()

Clears unused pools for the current thread. This method is typically called to maintain a low memory footprint. For example, if the system is low in free memory or even upon thread termination to ensure that pool objects are garbage collected as soon as possible (without waiting for thread finalization):

 public class MyThread extends Thread {
      public void run() {
          try { 
              while (...) {
                  PoolContext.enter();
                  try {
                      ... // Real-Time executions. 
                  } finally {
                      PoolContext.exit();
                      if (Runtime.getRuntime().freeMemory() < 1000000) {
                          System.out.prinln("Low memory - Clear pools");
                          PoolContext.clear();
                      }
                  }
              }
          } finally {  
              PoolContext.clear(); // Called as soon as thread terminates.
          } 
      }
 }