Package com.apple.foundationdb.record.query.plan.temp.debug

Interface Debugger

public interface Debugger

This interface functions as a stub providing hooks which can be called from the planner logic during planning. As the planner is currently single-threaded as per planning of a query, we keep an instance of an implementor of this class in the thread-local. (per-thread singleton). The main mean of communication with the debugger is the set of statics defined within this interface. Debugging functionality should only be enabled in test cases, never in deployments. In order to enable debugging capabilities, clients should use setDebugger(com.apple.foundationdb.record.query.plan.temp.debug.Debugger) which sets a debugger to be used for the current thread. Once set, the planner starts interacting with the debugger in order to communicate important state changes, like begin of planning, end of planner, etc. Clients using the debugger should never hold on/manage/use an instance of a debugger directly. Instead clients should use withDebugger(java.util.function.Consumer<com.apple.foundationdb.record.query.plan.temp.debug.Debugger>) and mapDebugger(java.util.function.Function<com.apple.foundationdb.record.query.plan.temp.debug.Debugger, T>)to invoke methods on the currently installed debugger. There is a guarantee that withDebugger(java.util.function.Consumer<com.apple.foundationdb.record.query.plan.temp.debug.Debugger>) does not invoke any given action if there is no debugger currently set for this thread. In this way, the planner implementation can freely call debug hooks which never will incur any penalties (performance or otherwise) for a production deployment.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Debugger.AbstractEventWithState	Abstract event class to capture rootReference amd taskStack.
static class	Debugger.AdjustMatchEvent	Events of this class are generated when the planner attempts to adjust an existing match.
static interface	Debugger.Event	Tag interface for all events.
static interface	Debugger.EventWithCurrentGroupReference	Interface for events that hold a group ref.
static interface	Debugger.EventWithState	Interface for events that hold a root reference.
static class	Debugger.ExecutingTaskEvent	Events of this class are generated every time the planner executes a task.
static class	Debugger.ExploreExpressionEvent	Events of this class are generated when the planner explores an expression.
static class	Debugger.ExploreGroupEvent	Events of this class are generated when the planner explores a group.
static class	Debugger.Location	Enum to indicate where an event happened.
static class	Debugger.OptimizeGroupEvent	Events of this class are generated when the planner optimizes a group.
static class	Debugger.OptimizeInputsEvent	Events of this class are generated when the planner optimizes inputs.
static class	Debugger.Shorthand	Shorthands to identify a kind of event.
static class	Debugger.TransformEvent	Events of this class are generated when the planner transforms an expression using a rule.
static class	Debugger.TransformRuleCallEvent	Events of this class are generated when the planner calls a transformation rule.

Field Summary

Fields

Modifier and Type	Field	Description
static ThreadLocal<Debugger>	THREAD_LOCAL	The thread local variable.

Method Summary

Modifier and Type	Method	Description
static Debugger	getDebugger()
static Optional<Integer>	getIndexOptional(Class<?> clazz)
static void	install()
static <T> Optional<T>	mapDebugger(Function<Debugger,T> function)	Apply the Function on the currently set debugger.
String	nameForObject(Object object)
void	onDone()
void	onEvent(Debugger.Event event)
int	onGetIndex(Class<?> clazz)
void	onInstall()
void	onQuery(RecordQuery recordQuery, PlanContext planContext)
void	onRegisterExpression(RelationalExpression expression)
void	onRegisterQuantifier(Quantifier quantifier)
void	onRegisterReference(ExpressionRef<? extends RelationalExpression> reference)
void	onSetup()
int	onUpdateIndex(Class<?> clazz, IntUnaryOperator updateFn)
static void	query(RecordQuery recordQuery, PlanContext planContext)
static void	registerExpression(RelationalExpression expression)
static void	registerQuantifier(Quantifier quantifier)
static void	registerReference(ExpressionRef<? extends RelationalExpression> reference)
static void	setDebugger(Debugger debugger)	Set the debugger.
static void	setup()
static Optional<Integer>	updateIndex(Class<?> clazz, IntUnaryOperator updateFn)
static void	withDebugger(Consumer<Debugger> action)	Invoke the Consumer on the currently set debugger.

Field Detail

THREAD_LOCAL

static final ThreadLocal<Debugger> THREAD_LOCAL

The thread local variable. This constructor by itself does not set anything within the thread locals of the lading thread. TODO make this private when we use Java 11

Method Detail

setDebugger

static void setDebugger(Debugger debugger)

Set the debugger. Override the currently set debugger if necessary.

Parameters:

debugger - the new debugger

getDebugger

@Nullable
static Debugger getDebugger()

withDebugger

static void withDebugger(@Nonnull
                         Consumer<Debugger> action)

Invoke the Consumer on the currently set debugger. Do not do anything if there is no debugger set.

Parameters:

action - consumer to invoke

mapDebugger

@Nonnull
static <T> Optional<T> mapDebugger(@Nonnull
                                   Function<Debugger,T> function)

Apply the Function on the currently set debugger. Do not do anything if there is no debugger set.

Type Parameters:

T - the type function produces

Parameters:

function - function to apply

Returns:

Optional.empty() if there is no debugger currently set for this thread or if the function returned null, Optional.of(result) where result is the result of applying function, otherwise.

install

static void install()

setup

static void setup()

query

static void query(RecordQuery recordQuery,
                  PlanContext planContext)

getIndexOptional

static Optional<Integer> getIndexOptional(Class<?> clazz)

updateIndex

@Nonnull
@CanIgnoreReturnValue
static Optional<Integer> updateIndex(Class<?> clazz,
                                     IntUnaryOperator updateFn)

registerExpression

static void registerExpression(RelationalExpression expression)

registerReference

static void registerReference(ExpressionRef<? extends RelationalExpression> reference)

registerQuantifier

static void registerQuantifier(Quantifier quantifier)

nameForObject

@Nullable
String nameForObject(@Nonnull
                     Object object)

onEvent

void onEvent(Debugger.Event event)

onDone

void onDone()

onGetIndex

int onGetIndex(@Nonnull
               Class<?> clazz)

onUpdateIndex

int onUpdateIndex(@Nonnull
                  Class<?> clazz,
                  @Nonnull
                  IntUnaryOperator updateFn)

onRegisterExpression

void onRegisterExpression(@Nonnull
                          RelationalExpression expression)

onRegisterReference

void onRegisterReference(@Nonnull
                         ExpressionRef<? extends RelationalExpression> reference)

onRegisterQuantifier

void onRegisterQuantifier(@Nonnull
                          Quantifier quantifier)

onInstall

void onInstall()

onSetup

void onSetup()

onQuery

void onQuery(RecordQuery recordQuery,
             PlanContext planContext)