Table of Contents

Class LargeStackThread

Namespace
RDCore.SDK.Platform
Assembly
RDCore.SDK.dll

Runs work whose depth of recursion is the depth of the code it reads - the parse of a module, its load, the evaluation of its code - on a thread whose stack has room for the deepest code RD-VBA reads.

public static class LargeStackThread
Inheritance
LargeStackThread
Inherited Members

Remarks

A parse, the tree it builds and the semantics of the tree recurse once or more for each level of an expression: a thread's default stack (1 MB) holds a few hundred levels, and MS-VBA runs expressions 2,500 deep (a chain of 2,500 terms, measured in Excel). An expression nested deeper than RD-VBA reads is a syntax error (VBC00060); one up to that depth is read on a thread of this size.

The stack is reserved, and committed only as it is used. On Linux a thread's stack counts toward the memory the system has committed to (Committed_AS): under strict overcommit (vm.overcommit_memory=2), creating a thread of this size can fail.

The work runs in the caller's culture and UI culture, which say what its messages are written in. Work that is already running on such a thread and waited for (Run<T>(Func<T>)) runs where it is, so that a parse made by a load takes no second thread. Work that is not waited for (Start(Action, CancellationToken)) runs on at most StartedAtOnce threads at a time, and the rest of it waits for one of them to be done.

Fields

StackSize

The size of the stack of a thread work is run on: 256 MB, as a program's own (RuntimeCallStack.ProgramThreadStackSize).

public const int StackSize = 268435456

Field Value

int

Properties

IsCurrent

Whether the current thread is one of StackSize: one Run<T>(Func<T>) or Start(Action, CancellationToken) made, or a program's thread (NewThread(Action, string)).

public static bool IsCurrent { get; }

Property Value

bool

Remarks

An entry point that recurses as deep as the code it reads, and is called for each of many expressions, checks it first, and calls itself through Run<T>(Func<T>) only when it is false: the request that called it takes one thread, and what it calls next runs where it is.

StartedAtOnce

How many threads run the work Start(Action, CancellationToken) is given at the same time: as many as there are processors, and at least 2.

public static int StartedAtOnce { get; }

Property Value

int

Methods

NewThread(Action, string)

A thread of StackSize, not started, that runs work for as long as it takes: the thread a program runs on. Work it waits for (Run<T>(Func<T>)) runs on it, as on a thread Run<T>(Func<T>) makes.

public static Thread NewThread(Action work, string name)

Parameters

work Action

The work.

name string

The name of the thread.

Returns

Thread

The thread, a background thread: it does not keep the process running.

Remarks

The thread starts in the culture every thread starts in, and not the caller's: what runs on it for as long as a program pleases sets its own. It is not counted among the threads of Start(Action, CancellationToken).

Exceptions

ArgumentNullException

work is null.

Run<T>(Func<T>)

Runs work on a thread of StackSize, and waits for it: what it returns is returned, and what it throws is thrown, as if the work had run on the caller's own thread.

public static T Run<T>(Func<T> work)

Parameters

work Func<T>

The work.

Returns

T

What work returned.

Type Parameters

T

What the work returns.

Remarks

An exception work throws is rethrown with the stack trace it was thrown with.

The thread is the work's own, made for it, and counted by nothing: it takes no thread of those Start(Action, CancellationToken) runs work on, and does not wait for one of them to be free. A request a client waits for is never queued behind work in the background. On a thread that is already one of StackSize (IsCurrent), the work runs where it is, and makes no thread.

Exceptions

ArgumentNullException

work is null.

Start(Action, CancellationToken)

Starts work on a thread of StackSize, and does not wait for it.

[SuppressMessage("Style", "VSTHRD200:Use \"Async\" suffix for async methods", Justification = "Public API: StartAsync would break its callers; the rename is held for a decision.")]
public static Task Start(Action work, CancellationToken token = default)

Parameters

work Action

The work.

token CancellationToken

Cancels the work while it waits for a thread: it is then never run. Once it runs, stopping it is the work's own business.

Returns

Task

A task that completes when the work does: faulted with what it throws, and cancelled when what it throws is an OperationCanceledException, or when token cancels it before it runs.

Remarks

Work runs on at most StartedAtOnce threads at a time; work started when they are all busy waits, holding no thread, for one of them to be done. Work started this way must therefore never wait for other work started this way: if every thread did, none would be left to run it.

Exceptions

ArgumentNullException

work is null.