OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult > Class Template Reference

Orchestrates at most one in-flight asynchronous Task versus synchronous syncWork, optional host cancellation, and a latest-result buffer for reference-type pipelines. More...

Public Member Functions
void	Cancel ()
void	Dispose ()
	Cancels in-flight work, clears the task reference without awaiting, and releases latest and async buffers. Does not call disposeAsyncAfterWorkTask.
async ValueTask	DisposeAsync ()
	Cancels, awaits the in-flight Task, then awaits the optional disposeAsyncAfterWorkTask callback, then releases state.
void	SubmitWork (TInput[] inputs, Func< TInput[], TResult[]> syncWork, Func< TInput[], Task< TResult[]> > asyncWork)
	Submits inputs for work: syncWork on the caller when UseAsyncWork is false, or a single in-flight asyncWork when true. When true, CopyInputsForAsync is used before asyncWork. syncWork receives inputs as passed in.
bool	TryGetLatestResult (out TResult[] results)
	Tries to return the latest successful result array. Deriving types can tighten validation via ValidateLatestForTryGet.

Protected Member Functions
	SingleFlightSyncAsyncRunner (bool useAsyncWork, CancellationToken asyncWorkCancellationToken=default, Func< Task > disposeAsyncAfterWorkTask=null)
	Initializes a new runner. Only DisposeAsync runs disposeAsyncAfterWorkTask ; Dispose does not.
void	CopyInputsForAsync (TInput[] source, TInput[] destination)
	Snapshots source into destination (async path only). The arrays are the same length; buffer allocation is handled by EnsureAsyncInputBuffer / overrides.
virtual void	EnsureAsyncInputBuffer (int requiredLength)
	Ensures the internal buffer used for async input snapshots has length requiredLength .
virtual void	ReleaseAsyncInputBuffers ()
	Releases per-element resources held in EnsureAsyncInputBuffer (e.g. OpenCV Mat slots in a derived type).
virtual void	ReleaseSingleResult (TResult result)
	Disposes a single result element. Default: IDisposable when implemented.
virtual bool	ValidateLatestForTryGet (TResult[] latest)
	Optional extra checks for TryGetLatestResult. The default is true.

Properties
CancellationToken	InFlightAsyncWorkCancellationToken [get]
	Cancellation token produced by linking the constructor cancellation token with the runner local cancellation token while an asynchronous asyncWork delegate is executing. Outside that window (including the synchronous path), this is default.
bool	IsWorkInFlight [get]
	true while a previously started asynchronous Task is still in progress (not yet completed, faulted, or canceled). When true, SubmitWork will not start new work.
bool	UseAsyncWork [get, set]
	When true, at most one async task runs; a new one starts only when the previous task has completed. When false, SubmitWork runs syncWork on the caller thread (after any still-running asynchronous task from a prior async mode has finished; see IsWorkInFlight and SubmitWork remarks).

Events
Action< WorkCompletion< TResult > >	WorkCompleted
	Occurs when a submitted work unit completes (success, cancellation, or fault), on the thread that completed the operation.

Detailed Description

Orchestrates at most one in-flight asynchronous Task versus synchronous syncWork, optional host cancellation, and a latest-result buffer for reference-type pipelines.

TInput and TResult are constrained to reference types. The async path does not copy inputs by itself; override CopyInputsForAsync to snapshot inputs before asyncWork runs (for example OpenCV Mat via copyTo in a derived type).

IMPORTANT:

1. Execution modes (UseAsyncWork):
   • false: SubmitWork runs syncWork on the caller thread (after any still-running async task from a prior async mode has finished).
   • true: SubmitWork starts at most one asyncWork Task; while IsWorkInFlight is true, further SubmitWork calls are ignored.
2. Single in-flight rule:
   • Keeps one async job in flight and avoids overlapping syncWork with a still-running asyncWork (for example shared DNN Net or buffers).
   • TryGetLatestResult still returns the last completed results when a submission is skipped.
3. Cancellation:
   • Pass a host CancellationToken to the constructor (asyncWorkCancellationToken); it is linked with a per-runner local token for each async submission.
   • Inside asyncWork, pass InFlightAsyncWorkCancellationToken to APIs that accept a CancellationToken (it is only non-default while asyncWork is executing). Do not rely on it from syncWork.
   • Cancel cancels the in-flight scope via the local token; changing UseAsyncWork also cancels.
4. Accessing results:
   • Use TryGetLatestResult for the live buffer owned by the runner; do not Dispose returned elements unless you have copied ownership off—see TryGetLatestResult remarks.
5. Resource management:
   • Implements IDisposable and IAsyncDisposable; prefer DisposeAsync when you can await so the optional disposeAsyncAfterWorkTask runs after the in-flight task.
   • Dispose does not await that hook.
6. Thread safety:
   • Public surface is safe to call from multiple threads; internal coordination uses locks.
7. Work completion event:
   • WorkCompleted is raised on the thread that completed the work (same as ProcessingWorkerBase.ProcessingCompleted); handlers receive only WorkCompletion<TResult> (no sender argument). WorkCompletionKind is defined in this namespace; ProcessingWorkerBase uses its own nested ProcessingWorkerBase.ProcessingCompletionKind for ProcessingCompletion. Synchronous path: SubmitWork caller thread. Asynchronous path: the await continuation thread; when SubmitWork is called from the Unity main thread, await asyncWork(...).ConfigureAwait(true) typically resumes on the captured System.Threading.SynchronizationContext (often the main thread), but this is not guaranteed. Do not use Unity main-thread-only APIs in the handler unless you know the completion thread; marshal if needed.
   • Do not dispose Results elements in the handler; ownership matches TryGetLatestResult.
   • No event when SubmitWork is skipped (in-flight) or when work returns null outputs.
   • Prefer unsubscribing before Dispose when possible.

Example Usage:

// TInput/TResult are reference types (e.g. Mat[] in a derived runner).
var runner = new MyRunner(
    useAsyncWork: true,
    asyncWorkCancellationToken: hostCts.Token,
    disposeAsyncAfterWorkTask: async () => { await worker.WaitForCompletionTaskAsync(); });
 
runner.SubmitWork(
    myInputs,
    syncWork: inputs => ComputeSync(inputs),
    asyncWork: async inputs =>
    {
        CancellationToken ct = runner.InFlightAsyncWorkCancellationToken;
        return await ComputeAsync(inputs, ct);
    });
 
void OnWorkCompleted(WorkCompletion<TResult> completion)
{
    switch (completion.Kind)
    {
        case WorkCompletionKind.Succeeded:
            // completion.Results is the same live buffer as TryGetLatestResult; do not Dispose elements.
            break;
        case WorkCompletionKind.Canceled:
            break;
        case WorkCompletionKind.Faulted:
            Debug.LogException(completion.Error);
            break;
    }
}
runner.WorkCompleted += OnWorkCompleted;
 
if (runner.TryGetLatestResult(out TResult[] results))
{
    // Consume results; do not Dispose owned elements unless documented otherwise.
}
 
runner.WorkCompleted -= OnWorkCompleted;
await runner.DisposeAsync();

Type Constraints

TInput	:	class
TResult	:	class

Constructor & Destructor Documentation

SingleFlightSyncAsyncRunner()

OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.SingleFlightSyncAsyncRunner ( bool useAsyncWork, CancellationToken asyncWorkCancellationToken = default, Func< Task > disposeAsyncAfterWorkTask = null )

protected

Initializes a new runner. Only DisposeAsync runs disposeAsyncAfterWorkTask ; Dispose does not.

Parameters

useAsyncWork	Initial async (non-in-flight) mode.
asyncWorkCancellationToken	Token that cancels the linked work scope; combined with the local token used by Cancel and UseAsyncWork changes.
disposeAsyncAfterWorkTask	Optional async cleanup after the in-flight Task (e.g. async () => { await a.WaitForCompletionTaskAsync(); await b.WaitForCompletionTaskAsync(); }).

Member Function Documentation

Cancel()

void OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.Cancel

(

)

CopyInputsForAsync()

void OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.CopyInputsForAsync ( TInput[] source, TInput[] destination )

abstractprotected

Snapshots source into destination (async path only). The arrays are the same length; buffer allocation is handled by EnsureAsyncInputBuffer / overrides.

Dispose()

void OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.Dispose

(

)

Cancels in-flight work, clears the task reference without awaiting, and releases latest and async buffers. Does not call disposeAsyncAfterWorkTask.

DisposeAsync()

async ValueTask OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.DisposeAsync

(

)

Cancels, awaits the in-flight Task, then awaits the optional disposeAsyncAfterWorkTask callback, then releases state.

EnsureAsyncInputBuffer()

virtual void OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.EnsureAsyncInputBuffer ( int requiredLength )

protectedvirtual

Ensures the internal buffer used for async input snapshots has length requiredLength .

ReleaseAsyncInputBuffers()

virtual void OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.ReleaseAsyncInputBuffers ( )

protectedvirtual

Releases per-element resources held in EnsureAsyncInputBuffer (e.g. OpenCV Mat slots in a derived type).

ReleaseSingleResult()

virtual void OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.ReleaseSingleResult ( TResult result )

protectedvirtual

Disposes a single result element. Default: IDisposable when implemented.

SubmitWork()

void OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.SubmitWork	(	TInput[]	inputs,
		Func< TInput[], TResult[]>	syncWork,
		Func< TInput[], Task< TResult[]> >	asyncWork )

Submits inputs for work: syncWork on the caller when UseAsyncWork is false, or a single in-flight asyncWork when true. When true, CopyInputsForAsync is used before asyncWork. syncWork receives inputs as passed in.

If a previous asynchronous Task is still in progress (IsWorkInFlight is true), this method does nothing: neither syncWork nor a new asyncWork is started. That keeps at most one async job in flight and avoids overlapping synchronous work with a still-running async job (e.g. shared Net or buffers). TryGetLatestResult still reflects the last completed work when a submission is skipped.

Parameters

inputs	Input batch (not null, non-empty).
syncWork	Synchronous work (not null when UseAsyncWork is false).
asyncWork	Asynchronous work (not null when UseAsyncWork is true); no CancellationToken parameter—use InFlightAsyncWorkCancellationToken.

TryGetLatestResult()

bool OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.TryGetLatestResult

(

out TResult[]

results

)

Tries to return the latest successful result array. Deriving types can tighten validation via ValidateLatestForTryGet.

Disposal of the latest result buffer (including each element when IDisposable) is this runner's responsibility: it is released when newer results replace it or when this instance is disposed. Do not call Dispose on results or its elements; the same instances remain owned by the runner until then. results is the runner's live buffer: mutating an element in place changes the stored result. If you need to modify it, clone (or copy) the element (or the array) first, then work on the copy.

ValidateLatestForTryGet()

virtual bool OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.ValidateLatestForTryGet ( TResult[] latest )

protectedvirtual

Optional extra checks for TryGetLatestResult. The default is true.

Property Documentation

InFlightAsyncWorkCancellationToken

CancellationToken OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.InFlightAsyncWorkCancellationToken

get

Cancellation token produced by linking the constructor cancellation token with the runner local cancellation token while an asynchronous asyncWork delegate is executing. Outside that window (including the synchronous path), this is default.

IsWorkInFlight

bool OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.IsWorkInFlight

get

true while a previously started asynchronous Task is still in progress (not yet completed, faulted, or canceled). When true, SubmitWork will not start new work.

UseAsyncWork

bool OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.UseAsyncWork

getset

When true, at most one async task runs; a new one starts only when the previous task has completed. When false, SubmitWork runs syncWork on the caller thread (after any still-running asynchronous task from a prior async mode has finished; see IsWorkInFlight and SubmitWork remarks).

Event Documentation

WorkCompleted

Action<WorkCompletion<TResult> > OpenCVForUnity.UnityIntegration.Runner.SingleFlightSyncAsyncRunner< TInput, TResult >.WorkCompleted

Occurs when a submitted work unit completes (success, cancellation, or fault), on the thread that completed the operation.

For WorkCompletionKind.Succeeded, WorkCompletion<TResult>.Results is the same live buffer as TryGetLatestResult; do not Dispose elements unless ownership has been copied off. Unity objects and UGUI should only be touched from the main thread; marshal from the handler when the completion thread may differ. Handlers receive only the WorkCompletion<TResult> value (no sender argument).

---

The documentation for this class was generated from the following file:

• OpenCVForUnity/Assets/OpenCVForUnity/org/opencv/unity/Runner/SingleFlightSyncAsyncRunner.cs