Runtime class

Hosts the identity slots a process onboards with and produces its sessions. Create it after Library.Init; every Session comes from Runtime.Onboard or Runtime.Rejoin on it.

Namespace: Quaternar.Qaros · Assembly: Quaternar.Qaros.dll

public sealed class Runtime : IDisposable

Implements: IDisposable

Remarks

The canonical startup: try Runtime.Rejoin with the persisted OnboardingId; on StatusCode.OnboardingSessionNotFound run Runtime.Onboard and persist the id it returns. Dispose sessions before the runtime, and the runtime before Library.Destroy.

Methods

Member	Description
Create(RuntimeOptions?)	Creates the runtime. Set RuntimeOptions.RuntimeBinariesFolderPath to the SDK bin folder the native library was loaded from: left empty, sessions still work but Session.InviteTargetApp never completes.
Rejoin(RejoinOptions, IProgress<ActionProgress>?, CancellationToken)	Restores the session last persisted for RejoinOptions.OnboardingId. Pops no UI, so call it optimistically on every start. Blocks until the restore validated or failed.
RejoinAsync(RejoinOptions, IProgress<ActionProgress>?, CancellationToken)	Async Runtime.Rejoin: returns at once, and the task completes on a library thread with the same results.
Onboard(OnboardOptions, IProgress<ActionProgress>?, CancellationToken)	Runs full onboarding with the mode chosen by OnboardOptions.UseCode or OnboardOptions.UseInvite, and blocks until it succeeded or failed. Persist the returned OnboardSession.OnboardingId: it is the ticket for every later Runtime.Rejoin and Runtime.Forget.
OnboardAsync(OnboardOptions, IProgress<ActionProgress>?, CancellationToken)	Async Runtime.Onboard: returns at once and keeps the UI responsive; the task completes with the same results. Canceling cancellationToken cancels the task.
Forget(ForgetOptions)	Erases everything stored for an identity slot: certificate, persisted peer id and session state. Afterwards only a full Runtime.Onboard gets back in. Needs no session, so it also serves a "forget this hub" action while disconnected.
Dispose()	Releases the runtime. Dispose its sessions first.

Create

Creates the runtime. Set RuntimeOptions.RuntimeBinariesFolderPath to the SDK bin folder the native library was loaded from: left empty, sessions still work but Session.InviteTargetApp never completes.

public static Result<Runtime> Create(RuntimeOptions? options = null)

Parameters

Name	Type	Description
options	RuntimeOptions

Returns: Result<Runtime>

Rejoin

Restores the session last persisted for RejoinOptions.OnboardingId. Pops no UI, so call it optimistically on every start. Blocks until the restore validated or failed.

public Result<Session> Rejoin(RejoinOptions options, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
options	RejoinOptions	The onboarding id to restore, and optional presentation and GPU.
progress	IProgress<ActionProgress>	Optional progress reports.
cancellationToken	CancellationToken	Cancels the restore; the call then returns a failure.

Returns: Result<Session>

Remarks

The session keeps the peer id the onboard persisted. Presentation fields left null keep their persisted values.

Expected failures: StatusCode.OnboardingSessionNotFound means this slot has nothing persisted here, fall back to Runtime.Onboard. StatusCode.ArgumentNotSupported means the onboarding id is OnboardingId.Default.

progress is reported from a library thread while this call blocks. A Progress<T> created on a UI thread posts there, so do not block that thread on this call if you want to see the reports.

RejoinAsync

Async Runtime.Rejoin: returns at once, and the task completes on a library thread with the same results.

public Task<Result<Session>> RejoinAsync(RejoinOptions options, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
options	RejoinOptions
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Task<Result<Session>>

Onboard

Runs full onboarding with the mode chosen by OnboardOptions.UseCode or OnboardOptions.UseInvite, and blocks until it succeeded or failed. Persist the returned OnboardSession.OnboardingId: it is the ticket for every later Runtime.Rejoin and Runtime.Forget.

public Result<OnboardSession> Onboard(OnboardOptions options, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
options	OnboardOptions	The onboarding mode and its optional extensions.
progress	IProgress<ActionProgress>	Optional progress reports, for an onboarding UI.
cancellationToken	CancellationToken	Cancels the onboarding; the call then returns a failure.

Returns: Result<OnboardSession>

Remarks

With OnboardOptions.OnboardingId unset a new identity slot is created; set to an id an earlier onboard returned, that slot is re-enrolled.

Expected failures: StatusCode.PakeError means the code was wrong or expired, or the invite was rejected or expired: re-prompt for a code or mint a fresh invite. StatusCode.OnboardingHubUnreachable means no hub answered: check that it runs and pass its host and port with OnboardOptions.WithHost. StatusCode.ArgumentNotSupported means a zero OnboardOptions.WithPeerId id, a host port of 0, or a GPU the session cannot create its devices on.

progress is reported from a library thread while this call blocks.

OnboardAsync

Async Runtime.Onboard: returns at once and keeps the UI responsive; the task completes with the same results. Canceling cancellationToken cancels the task.

public Task<Result<OnboardSession>> OnboardAsync(OnboardOptions options, IProgress<ActionProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
options	OnboardOptions
progress	IProgress<ActionProgress>
cancellationToken	CancellationToken

Returns: Task<Result<OnboardSession>>

Forget

Erases everything stored for an identity slot: certificate, persisted peer id and session state. Afterwards only a full Runtime.Onboard gets back in. Needs no session, so it also serves a "forget this hub" action while disconnected.

public Result<Unit> Forget(ForgetOptions options)

Parameters

Name	Type	Description
options	ForgetOptions

Returns: Result<Unit>

Remarks

Fails with StatusCode.OnboardingSessionStillActive while a session of the slot is alive: dispose it first. A slot with nothing persisted fails with StatusCode.OnboardingSessionNotFound.

Dispose

Releases the runtime. Dispose its sessions first.

public void Dispose()