cz.advel.stack
Class Stack

java.lang.Object
  cz.advel.stack.Stack

public class Stack
extends java.lang.Object

Support for stack allocation of "value" objects. The only requirements for "value" objects is that they must have public zero argument constructor and set method with one argument of the same type (or superclass) which copies data from given instance.

Example usage:

 public static Vector3f average(Vector3f v1, Vector3f v2, Vector3f out) {
     out.add(v1, v2);
     out.scale(0.5f);
     return out;
 }
 
 public static void test() {
     Vector3f v1 = Stack.alloc(Vector3f.class);
     v1.set(0f, 1f, 2f);
 
     Vector3f v2 = Stack.alloc(v1);
     v2.x = 10f;
 
     Vector3f avg = average(v1, v2, Stack.alloc(Vector3f.class));
 }
 

which is transformed into something like the following code. The actual generated code has mangled names for unique type identification and can have other minor differences.

 public static void test() {
     $Stack stack = $Stack.get();
     stack.pushVector3f();
     try {
         Vector3f v1 = stack.getVector3f();
         v1.set(0f, 1f, 2f);
 
         Vector3f v2 = stack.getVector3f(v1);
         v2.x = 10f;
 
         Vector3f avg = average(v1, v2, stack.getVector3f());
     }
     finally {
         stack.popVector3f();
     }
 }
 

Rules:

• classes needs to be instrumented by provided InstrumentationTask for ANT, otherwise error is throwed in runtime
• stack is pushed only once per method, do not use stack allocation in loops
• returning of stack allocated objects is not supported, use output parameter instead (like in the example)
• working with stack is thread-safe, the data are separate for each thread
• combining different libraries works fine, each must have their stack stored in different package, so you'll just end up with multiple stacks in final application, which is fine, because the values are used between them without problem
• when creating and destroying threads you must be aware that the implementation uses ThreadLocal to persist stack instances between method calls, it's advisable to call cleanCurrentThread method on thread just before destroying

Method Summary

static <T> T	alloc(java.lang.Class<T> cls) Returns stack allocated object.
static <T> T	alloc(T obj) Returns stack allocated object with copied value from given parameter.
static void	cleanCurrentThread() Removes all cached stack instances for current thread.
static void	internalRegisterThreadLocal(java.lang.ThreadLocal local) Used internally.
static void	libraryCleanCurrentThread() Removes all cached stack instances for current thread in current library.

Methods inherited from class java.lang.Object

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

Method Detail

alloc

public static <T> T alloc(java.lang.Class<T> cls)

Returns stack allocated object.

Requires instrumentation of your classes in order to work.

Parameters:

cls - class type, must be compile-time constant

Returns:

stack allocated instance of given class

alloc

public static <T> T alloc(T obj)

Returns stack allocated object with copied value from given parameter.

Requires instrumentation of your classes in order to work.

Parameters:

obj - object to copy on stack, the type must be statically known

Returns:

stack allocated instance with copied data

internalRegisterThreadLocal

public static void internalRegisterThreadLocal(java.lang.ThreadLocal local)

Used internally.

cleanCurrentThread

public static void cleanCurrentThread()

Removes all cached stack instances for current thread.

libraryCleanCurrentThread

public static void libraryCleanCurrentThread()

Removes all cached stack instances for current thread in current library.

Requires instrumentation of your classes in order to work.

See Also:

InstrumentationTask.setIsolated(boolean)