Interface ISessionHalt
Whether the program has been stopped, and why.
public interface ISessionHaltRemarks
End and Stop are not values, and not errors: they come out of the middle of an expression - a function called from the right-hand side of an assignment
can End the program - through code whose only ways to answer are a value and an error. So the statement says so here, and fails the way a call that
has no answer fails; whatever is waiting for the answer sees that it has none, and the one that started the program asks this why.
A break asked for from outside takes the same road. It is what Stop is when nobody wrote it: the cancellation that reaches the interpreter is a
request to Request(RuntimeHaltKind, SourceLocation?) a Break, so that a program stopped at the keyboard and a program that stopped itself are told
apart by nothing but the place they stopped at.
⚖️RDCore provides an implementation of this interface licensed under GPLv3.
Properties
BreakOnErrors
Which run-time errors a program that runs under a Gate waits at, where they are raised. The session's, as Breakpoints are: it outlives the program and is still there when the program is started again.
ErrorBreakMode BreakOnErrors { get; set; }Property Value
Breakpoints
The lines a program that runs under a Gate waits at before it runs them. They are the session's, and outlive the program: they are still there when the program is started again.
IBreakpointTable Breakpoints { get; }Property Value
Gate
The gate a program that can be resumed runs under, or null for one that cannot, which a Stop unwinds.
IExecutionGate? Gate { get; set; }Property Value
Location
Where the program was stopped, when the statement that stopped it is known.
SourceLocation? Location { get; }Property Value
Pending
Why the program has been stopped, or null when it has not.
RuntimeHaltKind? Pending { get; }Property Value
StoppedOnCondition
The condition of the breakpoint the program waits at, while it waits because the condition could not be evaluated (see TrySuspendOnCondition(BreakpointConditionFailure, SourceLocation?)), and has not yet been resumed. null otherwise.
BreakpointConditionFailure? StoppedOnCondition { get; }Property Value
StoppedOnError
The error the program waits at, while it waits at one: the program stopped where the error was raised (see TrySuspendOnError(IVBRaisableError, bool)), and has not yet been resumed. null otherwise.
IVBRaisableError? StoppedOnError { get; }Property Value
Methods
Clear()
Forgets the request, so that the next program starts as one that was never stopped.
void Clear()Request(RuntimeHaltKind, SourceLocation?)
Stops the program.
void Request(RuntimeHaltKind kind, SourceLocation? location = null)Parameters
kindRuntimeHaltKindWhy.
locationSourceLocation?The statement that stopped it, or null when it was not one.
Remarks
The first request stands: a program that is already stopping is not stopped again by what unwinds it.
RequestStep(StepKind, int)
Asks the program to stop again at the first instruction boundary that kind says, once it is resumed.
void RequestStep(StepKind kind, int callDepth)Parameters
kindStepKindHow far the program goes before it stops.
callDepthintThe depth of the call stack the program is stepping from.
TakeStep(int)
Whether a step that was asked for is due at the instruction about to run, which forgets it: it is one step.
bool TakeStep(int callDepth)Parameters
callDepthintThe depth of the call stack at that instruction.
Returns
Remarks
Asked between every two instructions, and so nothing but a field is looked at when no step was asked for.
TrySuspend(RuntimeHaltKind, SourceLocation?)
Offers the program to the Gate to wait at the place it is stopped at.
bool TrySuspend(RuntimeHaltKind kind, SourceLocation? location)Parameters
kindRuntimeHaltKindWhy the program is stopped.
locationSourceLocation?The statement that stopped it, or null when it was not one.
Returns
- bool
true when the program waited and was resumed: it goes on from the statement after the one that stopped it, as if that had completed. false when it did not wait, because there is no gate, or because it was abandoned: the program is stopped as it is when nothing can resume it.
TrySuspendOnCondition(BreakpointConditionFailure, SourceLocation?)
Offers the program to the Gate to wait at a breakpoint whose condition could not be evaluated, as it would at any breakpoint, with StoppedOnCondition saying why for as long as it waits.
bool TrySuspendOnCondition(BreakpointConditionFailure failure, SourceLocation? location)Parameters
failureBreakpointConditionFailureThe condition, and what it raised.
locationSourceLocation?Where the breakpoint is: the instruction the program waits before.
Returns
- bool
true when the program waited and was resumed, as TrySuspend(RuntimeHaltKind, SourceLocation?) says.
TrySuspendOnError(IVBRaisableError, bool)
Offers the program to the Gate to wait where an error was raised, if BreakOnErrors says it is an error to wait at.
bool TrySuspendOnError(IVBRaisableError error, bool handled)Parameters
errorIVBRaisableErrorThe error.
handledboolWhether an activation on the call stack has a handler that would catch it: an
On Error GoToor anOn Error Resume Next.
Returns
- bool
true when the program waited and was resumed, and goes on to deal with the error as it would have. false when it did not wait: there is no gate, the mode says to go on, the program is being stopped already, or the error was waited at before - the same error travels up the call stack through every activation it passes, and is waited at where it was raised and not again.