Table of Contents

Interface ISessionTurn

Namespace
RDCore.SDK.Runtime.Abstract.Execution
Assembly
RDCore.SDK.dll

Whose turn it is to run code in a session: the program that is running, or an event that something outside the workspace raised.

public interface ISessionTurn

Remarks

A session runs one thing at a time. The interpreter is not re-entrant from two threads, and the objects of a program are not safe to be read by one thread while another changes them - but the objects of a library are not the program's to schedule. A host application raises an event when something happens to it, at a time that is its own, on a thread that is its own; the procedures that handle the event are the program's, and run in the program's session.

MS-VBAL says when an event is handled only for the events of the language itself (§5.4.2.20: RaiseEvent invokes the handlers, there and then), and for the others it says only that DoEvents "yields execution so that the operating system can process externally generated events" (§6.1.2.8.1.5). The rest is how MS-VBA gets an event from a host application, which is a call from the server to the program, and a program can only take a call when it is not busy: while it waits for a call of its own to return (the server raises NewWorkbook before Workbooks.Add returns, and the handlers may answer it), when it yields with DoEvents, and when it is over. That is all of it: nothing is handled in the middle of a statement, and a program that does none of these is a program no event reaches. Until the session is open to it (IsOpenForEvents) an event waits, and so does whatever raised it.

A program that is running holds the turn, and gives it up while it waits for a call to finish (Yield()), which is what opens the session to the events.

⚖️RDCore provides implementations of this interface licensed under GPLv3.

Properties

EventScope

What surrounds the handling of an event when no program is running to own the session: the host's, since what the handlers print has nowhere to go but where the host says. null when the host says nothing.

Func<IDisposable>? EventScope { get; set; }

Property Value

Func<IDisposable>

Remarks

Called when such an event is about to be handled; the scope it returns is disposed when it has been. An event that is handled while a program runs prints where the program does.

IsOpenForEvents

Whether an event that no call was waiting for may be handled now: no program is running, one waits for a call, or one is pumping.

bool IsOpenForEvents { get; }

Property Value

bool

Remarks

Not while the program waits at a stop (Stopped()): no code of the program runs then, as none does in MS-VBA's break mode. The one exception is code that runs beside the program that waits (Alongside()), whose calls may raise events of their own.

IsRunning

Whether a program runs in the session: what Running last said.

bool IsRunning { get; }

Property Value

bool

RunsAnEventOfTheProgram

Whether the calling thread is running the handlers of an event of the program: one raised while the program gave the turn up (Yield(), Pump()), or while the handlers of another such event did.

bool RunsAnEventOfTheProgram { get; }

Property Value

bool

Remarks

Such a thread runs the program's code as the program's own thread does, and may be held where the program stops (Suspend(RuntimeHaltKind, SourceLocation?)). An event raised by a call of code beside a program that waits (Alongside()) is not one: it is that code's. The default is false.

RunsAnEventOfTheSession

Whether the calling thread is running the handlers of an event that was handled while no program runs: the turn was free (no program, and no code beside one at a stop), as it is for a click on a form that the prompt showed, or on a form that a macro left shown when it ended.

bool RunsAnEventOfTheSession { get; }

Property Value

bool

Remarks

Such a thread runs code of the session that no request runs, and may be held where its handler stops (Suspend(RuntimeHaltKind, SourceLocation?)), as MS-VBA's break mode holds it. An event handled while a program runs, waits or pumps is the program's (RunsAnEventOfTheProgram), and one raised by a call of code beside a program that waits (Alongside()) is that code's. The default is false.

ServeOfTheCallingThread

What the calling thread does with time it waits, when it is running the handlers of an event that was raised with one (RunEvent(Action, Action<TimeSpan>)): it waits up to the time given, making the calls asked of the thread meanwhile.

Action<TimeSpan>? ServeOfTheCallingThread { get; }

Property Value

Action<TimeSpan>

Remarks

null for any other thread. The default is null.

Methods

Alongside()

Says that the calling thread runs code beside the program that waits at a stop (an expression a debugger evaluates, a statement typed at the stop) for as long as the returned scope is not disposed.

IDisposable Alongside()

Returns

IDisposable

The scope of the code.

Remarks

The calls that code makes give the turn up as the program's do (Yield()), but only to the events they raise themselves: those are the code's, handled at once and not held where they stop, and an event of the program that waits goes on waiting. The default does nothing.

Enter()

Takes the turn for a program that starts. Waits for an event that is being handled to be done.

void Enter()

Exit()

Gives the turn back: the program is over, and the events that waited for it are handled.

void Exit()

Pump()

Lets the asynchronous events that wait be handled, and goes on when they have been: what DoEvents does.

void Pump()

RunEvent(Action)

Runs handle in the session, and returns when it is done.

void RunEvent(Action handle)

Parameters

handle Action

What handles the event.

Remarks

Called by whatever received the event, on whatever thread that is, once the event may be handled: a synchronous one at once, an asynchronous one when IsOpenForEvents. It blocks that thread, which is the point: the server that raised the event is waiting for the handlers to be done - they may set an argument it passed by reference, such as the Cancel of an event that can be cancelled.

RunEvent(Action, Action<TimeSpan>)

Runs handle in the session, as RunEvent(Action) does, for an event raised on a thread that has calls of its own to make while it waits.

void RunEvent(Action handle, Action<TimeSpan> serve)

Parameters

handle Action

What handles the event.

serve Action<TimeSpan>

What the thread the event was raised on does with time it waits: it waits up to the time given, making the calls asked of it meanwhile.

Remarks

A thread that raises an event is often the only thread its objects can be called on: an apartment of COM objects, the thread of a form's window. While that thread waits for something (the turn, or the person at a debugger when a handler of the event is stopped at a breakpoint), the calls asked of it meanwhile still have to be made, or whoever asked for one waits forever. serve is how: it waits up to the time it is given, making those calls meanwhile.

While the program waits at a stop (Stopped()), the handlers of an event of the program wait for it to be resumed, by serve, and run after it in the order their events came; an event raised by a call of code beside the program (Alongside()) is handled at once.

The default ignores serve, and is RunEvent(Action).

Stopped()

Says that the program waits at a stop (a Stop, a breakpoint, an error a debugger waits at) for as long as the returned scope is not disposed.

IDisposable Stopped()

Returns

IDisposable

The scope of the stop.

Remarks

No code of the program runs meanwhile, as none does in MS-VBA's break mode. An event of the program that comes meanwhile is not dropped: it waits, and is handled once the program is resumed, in the order such events came, and after the thread that waited at the stop has the turn back, so that the code the program goes on with comes first. Called on the thread that waits at the stop, by whatever holds the program there. The default does nothing.

Waiting()

Says that an asynchronous event waits for the session to be open to it, for as long as the returned scope is not disposed - which is how Pump() knows there is something to wait for.

IDisposable Waiting()

Returns

IDisposable

Yield()

Gives the turn up while the program waits for a call to finish, and takes it back when the returned scope is disposed.

IDisposable Yield()

Returns

IDisposable

Remarks

A scope for code that is not in a turn does nothing: only what holds the turn can give it up.

Events

Running

Raised with true when a program starts running in the session and none was, and with false when the last one ends: what a host of windows needs to know to hold their messages while a program runs, as MS-VBA does (none is dispatched until the program waits for it, at DoEvents or a modal form, or ends). Raised on the thread that starts or ends the program.

event Action<bool>? Running

Event Type

Action<bool>