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 usesetDebugger(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 usewithDebugger(java.util.function.Consumer<com.apple.foundationdb.record.query.plan.temp.debug.Debugger>)
andmapDebugger(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 thatwithDebugger(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 capturerootReference
amdtaskStack
.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.MatchExpressionEvent
Events of this class are generated when the planner attempts to match an expression.static class
Debugger.MatchExpressionWithCandidateEvent
Events of this class are generated when the planner attempts to match an expression to the expression of a match candidate.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
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description static Debugger
getDebugger()
static void
install()
static <T> Optional<T>
mapDebugger(Function<Debugger,T> function)
Apply theFunction
on the currently set debugger.String
nameForObject(Object object)
void
onDone()
void
onEvent(Debugger.Event event)
void
onInstall()
void
onQuery(RecordQuery recordQuery, PlanContext planContext)
void
onRegisterExpression(RelationalExpression expression)
void
onRegisterQuantifier(Quantifier quantifier)
void
onRegisterReference(ExpressionRef<? extends RelationalExpression> reference)
void
onSetup()
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 void
withDebugger(Consumer<Debugger> action)
Invoke theConsumer
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
-
withDebugger
static void withDebugger(@Nonnull Consumer<Debugger> action)
Invoke theConsumer
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 theFunction
on the currently set debugger. Do not do anything if there is no debugger set.- Type Parameters:
T
- the typefunction
produces- Parameters:
function
- function to apply- Returns:
Optional.empty()
if there is no debugger currently set for this thread or if the function returnednull
,Optional.of(result)
whereresult
is the result of applyingfunction
, otherwise.
-
install
static void install()
-
setup
static void setup()
-
query
static void query(RecordQuery recordQuery, PlanContext planContext)
-
registerExpression
static void registerExpression(RelationalExpression expression)
-
registerReference
static void registerReference(ExpressionRef<? extends RelationalExpression> reference)
-
registerQuantifier
static void registerQuantifier(Quantifier quantifier)
-
onEvent
void onEvent(Debugger.Event event)
-
onDone
void onDone()
-
onRegisterExpression
void onRegisterExpression(RelationalExpression expression)
-
onRegisterReference
void onRegisterReference(ExpressionRef<? extends RelationalExpression> reference)
-
onRegisterQuantifier
void onRegisterQuantifier(Quantifier quantifier)
-
onInstall
void onInstall()
-
onSetup
void onSetup()
-
onQuery
void onQuery(RecordQuery recordQuery, PlanContext planContext)
-
-