ch.awae.utils

Class Trampoline

java.lang.Object

ch.awae.utils.Trampoline

public final class Trampoline
extends java.lang.Object

Utility class for implementing trampoline based primitive recursion.

Whenever a method has a tail call that tail call can be externalised by not returning the result of the call, but instead an object instructing the Trampoline to perform the call to that method and to return the value provided by that function. That function can itself return the instruction to call another method. This allows for iterative execution instead of recursive one preventing StackOverflowErrors.

This class provides all helper methods required for Trampoline implementations with functions with up to two arguments (helpers for more arguments may be added in the future). Use Trampoline.Result<T> (where T is the return type of the complete trampolined call structure) as the return type of any involved method. Normal methods invoked from inside a Trampoline must either be called as a subcall and the result packed into a #Result instance using result(T) or they can be wrapped into a #Result using bounceWrapped(java.util.function.Supplier<T>).

Since:

awaeUtils 0.0.1

Author:

Andreas Wälchli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Trampoline.Result<T> Helper class representing the result of a single trampoline step.

Constructor Summary

Constructors

Constructor and Description
Trampoline()

Method Summary

Modifier and Type	Method and Description
static <T,A,B> Trampoline.Result<T>	bounce(java.util.function.BiFunction<A,B,Trampoline.Result<T>> f, A param0, B param1) Bounce to a BiFunction for the next step.
static <T,A> Trampoline.Result<T>	bounce(java.util.function.Function<A,Trampoline.Result<T>> f, A param0) Bounce to a Function for the next step.
static <T> Trampoline.Result<T>	bounce(java.util.function.Supplier<Trampoline.Result<T>> f) Bounce to a Supplier for the next step.
static <T,A,B> Trampoline.Result<T>	bounceWrapped(java.util.function.BiFunction<A,B,T> f, A param0, B param1) Bounces to a generic BiFunction.
static <T,A> Trampoline.Result<T>	bounceWrapped(java.util.function.Function<A,T> f, A param0) Bounces to a generic Function.
static <T> Trampoline.Result<T>	bounceWrapped(java.util.function.Supplier<T> f) Bounces to a generic Supplier.
static <T> Trampoline.Result<T>	result(T value) Wraps a value into a Result instance representing that value
static <T> T	run(Trampoline.Result<T> result) Starts a new trampoline with a given #Result.

Methods inherited from class java.lang.Object

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

Constructor Detail

Trampoline

public Trampoline()

Method Detail

result

public static <T> Trampoline.Result<T> result(T value)

Wraps a value into a Result instance representing that value

Parameters:

value - the value to wrap into a Result

Returns:

the Result containing the value

bounce

public static <T> Trampoline.Result<T> bounce(java.util.function.Supplier<Trampoline.Result<T>> f)

Bounce to a Supplier for the next step.

Parameters:

f - the function

Returns:

a Result instance representing a Trampoline step. When executing that step the Function f will be called. The return value of that call determines the next trampoline action.

bounce

public static <T,A> Trampoline.Result<T> bounce(java.util.function.Function<A,Trampoline.Result<T>> f,
                                                A param0)

Bounce to a Function for the next step.

Parameters:

f - the function

param0 - the function parameter

Returns:

a Result instance representing a Trampoline step. When executing that step the function f will be called with the parameter param0. The return value of that call determines the next trampoline action.

bounce

public static <T,A,B> Trampoline.Result<T> bounce(java.util.function.BiFunction<A,B,Trampoline.Result<T>> f,
                                                  A param0,
                                                  B param1)

Bounce to a BiFunction for the next step.

Parameters:

f - the function

param0 - the first function parameter

param1 - the second function parameter

Returns:

a Result instance representing a Trampoline step. When executing that step the function f will be called with the parameters param0 and param1. The return value of that call determines the next trampoline action.

bounceWrapped

public static <T> Trampoline.Result<T> bounceWrapped(java.util.function.Supplier<T> f)

Bounces to a generic Supplier.

This method is designed to provide a hook into an arbitrary external method. This does interrupt normal trampoline functionality until the supplier function returns. The return value of the supplier is then wrapped into a Result and returned.

Parameters:

f - the function

Returns:

a Result instance representing a Trampoline step. When executing that step the Function f will be called. The return value of that call will be wrapped into a Result and returned to the trampoline.

bounceWrapped

public static <T,A> Trampoline.Result<T> bounceWrapped(java.util.function.Function<A,T> f,
                                                       A param0)

Bounces to a generic Function.

This method is designed to provide a hook into an arbitrary external method. This does interrupt normal trampoline functionality until the function returns. The return value of the function is then wrapped into a Result and returned.

Parameters:

f - the function

param0 - the function parameter

Returns:

a Result instance representing a Trampoline step. When executing that step the function f will be called with the parameter param0. The return value of that call will be wrapped into a Result and returned to the trampoline.

bounceWrapped

public static <T,A,B> Trampoline.Result<T> bounceWrapped(java.util.function.BiFunction<A,B,T> f,
                                                         A param0,
                                                         B param1)

Bounces to a generic BiFunction.

This method is designed to provide a hook into an arbitrary external method. This does interrupt normal trampoline functionality until the function returns. The return value of the function is then wrapped into a Result and returned.

Parameters:

f - the function

param0 - the first function parameter

param1 - the second function parameter

Returns:

a Result instance representing a Trampoline step. When executing that step the function f will be called with the parameters param0 and param1. The return value of that call will be wrapped into a Result and returned to the trampoline.

run

public static <T> T run(Trampoline.Result<T> result)

Starts a new trampoline with a given #Result.

Usually the passed result is generated with one of the bounce(java.util.function.Supplier<ch.awae.utils.Trampoline.Result<T>>) methods. Using a bounceWrapped(java.util.function.Supplier<T>) method is recommended, since those methods break the normal trampoline execution.

Parameters:

result - the Result to start the trampoline from

Returns:

the return value of the last trampoline step