2.3 Application Host

Note

This specification may be incomplete at this time.

🎯 The RDCore platform shall provide with the rdc.exe CLI client, the ability to compose, host, analyze, run, and debug any RD-VBA application.

2.3.1 Composition Root

The environment host is responsible for composing a RD-VBA from its references, instructions, and symbols; configuring the host VBA environment implicit storage, and loading any application settings and additional workspace resources into the runtime environment.

It then proceeds to resolve an entry point, initiates an execution session, construct and push a ICallStackFrame to the evaluation engine that then proceeds to sequentially evaluate each instruction in the frame.

2.3.1.1 Execution Session

An execution session holds the state of the execution engine and exposes methods that advance execution steps:

Member Description
State Describes the current mode of the session
Frame Exposes the current stack frame
GetCurrentStack Exposes the current call stack
StepInto Advances execution by a single step
StepOver Advances execution into the next statement
StepOut Advances execution to the next statement in the current scope, stepping over any statements in-between

2.3.1.2 Virtual Heap

The IVirtualHeap interface extends ISymbolProvider and ISymbolResolver and should typically be exposed to the internal API through these specialized get-only interfaces.

  • ISymbolProvider exposes a single Define method that loads a specified Symbol and addresses it using its Uri.

The ISymbolResolver interface exposes the following members:

Member Description
Resolve Resolves a specified identifier name to a defined Symbol by inspecting a specified allocation scope
GetValue Gets the currently held VBTypedValue for a specified Symbol
TryRead Gets the VBTypedValue held at the specified address (offset) if it exists

The IVirtualHeap interface represents a service that manages the run-time memory structure of an execution context; it exposes the following additional members to the execution engine:

Member Description
CreateObject Creates a new VBObjectValue of a specified class type
SetValue Associates a specified VBTypedValue to a Symbol
Allocate Allocates a VBTypedValue or a specified number of bytes at the current memory address pointer
Deallocate Deallocates the memory held by the symbol at a specified Uri
Note

The RDCore implementation (⚖️GPLv3) of this service is intended to be thread-safe. While RD-VBA normally executes on a single thread, its runtime implementation is not inherently single-threaded and it is host-dependent whether a RD-VBA environment host supports the concurrent execution of RD-VBA execution threads. This concurrent execution capability is intended to be (optionally) used for eventual unit testing features.

An implementation of IVirtualHeap should:

  • Maintain an internal global heap to hold a VBTypedValue for any given Symbol that is globally-scoped;
  • Maintain an internal workspace heap to hold a VBTypedValue for any given Symbol that is workspace-scoped;
  • Maintain an internal static locals heap to hold a VBTypedValue for any given Symbol that is module-scoped;
  • Maintain an internal object heap to hold the Symbol references and their respective associated VBTypedValue for any given VBObjectValue;
  • Maintain an internal address pointer to track the current memory offset;
  • Maintain an internal symbol table mapping a Uri to its associated Symbol;
  • Maintain an internal name table holding the current representation (casing) of all loaded symbols;
  • Maintain an internal memory map mapping a VBTypedValue to a memory address (offset);
  • Maintain an internal raw address map mapping a memory address (offset) to a Uri.

ScopeKind defines the allocation scopes.

The current memory address pointer should be incremented by a host-defined IntPtrSize that represents the size of a pointer in the current environment (32 or 64 bits).

The correctly-scoped allocation of all symbols upon their definition should then suffice to make symbol resolution automatically follow the MS-VBAL specification with regards to the order in which an identifier name is resolved, provided that lookups are done in the specified order:

  1. If a name refers to a symbol defined on the local stack frame, then the resolved symbol is locally scoped;
  2. If a name refers to a symbol defined in the static locals heap, then the resolved symbol is locally scoped but preserves its value between calls;
  3. If a name refers to a symbol defined in the workspace heap, then the resolved symbol is workspace-scoped;
  4. If a name refers to a symbol defined in the global heap, then the resolved symbol is globally-scoped.
  • If multiple symbols match a specified name before reaching the global scope, then the name is ambiguous and an appropriate compile-time error should be issued, in this case VBC009303 Duplicate declaration.
  • If multiple symbols match a specified name within the global scope, then the name is disambiguated using the reference priority order of the referenced library a matching symbol is defined in. This priotity is determined by the order in which project references appear in the .rdproj file of a workspace folder.
Note

The VBA standard library always has the lowest priority (i.e. always appears first), meaning any other project reference that defines any identically-named class type or public/global member is always going to shadow the VBA library definitions; this shadowing should be detected in the semantic layer and reported through semantic flags so RDCore.Diagnostics can issue shadowed declaration diagnostics.

2.3.2 Mode / State

Provided that the host application is able to respond to keyboard inputs, execution in running mode may be suspended at any point to enter break mode through what has traditionally been a Ctrl+Pause|Break keyboard shortcut in the Microsoft Visual Basic Editor, however the platform considers this an implementation detail of the environment host, that may offer the same functionality through different, implementation-defined means that may or may not be equivalent.

At any point in time, a VBA host environment may be in either one of the following modes / states:

  • Design: a static context exists and is actively being synchronized with the workspace source code being edited;
  • Run: the host environment is actively executing instructions uninterrupted;
  • Break: execution is halted at the current instruction either through a manual break, a semantic break (e.g. a failed Assert call, or a Stop keyword was encountered), or an unhandled run-time error has occurred and instructions can be manually stepped over/into, or rewinded;

👉 The exact behavior of the host environment on error is implementation-defined: depending on the workspace application configuration, a failing workspace application may terminate the host process with an error code, or enter break mode and offer to debug at that location.

⏮️ RD-VBAL §2.2 RDPROJ Structure | ⏭️ RD-VBAL §2.4 Static Types

Edit this page