water

Class Scope

java.lang.Object

water.Scope

public class Scope
extends java.lang.Object

A "scope" for tracking Key lifetimes; an experimental API.

A Scope defines a SINGLE THREADED local lifetime management context, stored in Thread Local Storage. Scopes can be explicitly entered or exited. User keys created by this thread are tracked, and deleted when the scope is exited. Since enter & exit are explicit, failure to exit means the Keys leak (there is no reliable thread-on-exit cleanup action). You must call Scope.exit() at some point. Only user keys & Vec keys are tracked.

Scopes support nesting. Scopes support partial cleanup: you can list Keys you'd like to keep in the exit() call. These will be "bumped up" to the higher nested scope - or escaped and become untracked at the top-level.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Scope.Safe

Constructor Summary

Constructors

Constructor and Description
Scope()

Method Summary

Modifier and Type	Method and Description
static Scope	current() debugging purpose
static void	enter() Enter a new Scope
static Key[]	exit(Key... keep) Exit the innermost Scope, remove all Keys created since the matching enter call except for the listed Keys.
static boolean	isActive()
static int	nLevel() for testing purpose
static Frame	protect(Frame... frames) Protects the listed frames and their vecs inside this scope and inner scopes so that they can't be removed, for example if an unprotected frame shares some Vecs.
static void	reset() for testing purpose
static Scope.Safe	safe(Frame... protectedFrames) Enters a new scope and protects the passed frames in that scope.
static <T extends Keyed<T>> T	track_generic(T keyed)
static Frame	track(Frame... frames) Track one or more Frames, as well as all their Vecs independently.
static Vec	track(Vec vec) Track a single Vec.
static Frame	untrack(Frame... frames)
static <K extends Key> void	untrack(java.lang.Iterable<K> keys) Untrack the specified keys.
static <K extends Key> void	untrack(K... keys) Untrack the specified keys.

Methods inherited from class java.lang.Object

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

Constructor Detail

Scope

public Scope()

Method Detail

current

public static Scope current()

debugging purpose

nLevel

public static int nLevel()

for testing purpose

reset

public static void reset()

for testing purpose

enter

public static void enter()

Enter a new Scope

exit

public static Key[] exit(Key... keep)

Exit the innermost Scope, remove all Keys created since the matching enter call except for the listed Keys.

Returns:

Returns the list of kept keys.

isActive

public static boolean isActive()

Returns:

true iff we are inside a scope

track_generic

public static <T extends Keyed<T>> T track_generic(T keyed)

track

public static Vec track(Vec vec)

Track a single Vec.

Parameters:

vec -

Returns:

track

public static Frame track(Frame... frames)

Track one or more Frames, as well as all their Vecs independently. The tracked frames and vecs will be removed from DKV when exit(Key[]) is called, but for Frames, they will be removed without their Vecs as those are tracked independently, and we want to be able to untrack(Key[]) them (or spare them at exit(Key[]) without them being removed together with the Frame to which they're attached.

Parameters:

frames -

Returns:

the first Frame passed as param

untrack

public static <K extends Key> void untrack(K... keys)

Untrack the specified keys. Note that if a key corresponds to a , then only the frame key is untracked, not its vecs. Use untrack(Frame...) is you need a behaviour symmetrical to track(Frame...).

Parameters:

keys -

untrack

public static <K extends Key> void untrack(java.lang.Iterable<K> keys)

Untrack the specified keys. Note that if a key corresponds to a , then only the frame key is untracked, not its vecs. Use untrack(Frame...) is you need a behaviour symmetrical to track(Frame...).

Parameters:

keys -

untrack

public static Frame untrack(Frame... frames)

Parameters:

frames -

Returns:

the first Frame passed as a param.

protect

public static Frame protect(Frame... frames)

Protects the listed frames and their vecs inside this scope and inner scopes so that they can't be removed, for example if an unprotected frame shares some Vecs.

Parameters:

frames -

Returns:

the first protected frame.

safe

public static Scope.Safe safe(Frame... protectedFrames)

Enters a new scope and protects the passed frames in that scope. To be used as a resource in a try block: the new "safe" scope will then be auto-exited.