The SessionRunner helps to start, run and shutdown a Quantum simulation. It should never be reused for multiple simulations of multiple runs of the same game session. Always recrate the runner. It has an extensive list of starting Arguments that make it start-able for a variety of use cases: Local, Multiplayer, Replay, Server etc It extracts platform dependent code into the IRunnerFactory parameter. It offers asynchronous methods to start and stop the runner but although it uses the TPL syntax for convenience it is not considered to be run in a multi-threaded environment. Use the non-async versions of the methods or use a ConcurrentExclusiveSchedulerPair.ExclusiveScheduler for unit tests and console applications. Also never use the async methods from the Quantum server plugin, parallelization is done by the Photon-Server. This class is delivered in source code to enable developers to create custom runner code. More...

Classes
struct	Arguments
	Arguments to start an online or offline Quantum simulation. More...

Public Types
enum	SessionState
	The session runner has a state machine. More...

Public Member Functions
void	Dispose ()
	Implements disposable interface. Calls Shutdown internally. This is also called from inside Session.Destroy() to signal shutdown by the simulation. More...

void	Service (double? deltaTime=null)
	To update the Quantum simulation this needs to be run from the outside. From Unity is would be a MonoBehaviour, on the plugin it would be from OnDeterministicUpdate() and the spectator has an extra service task to tick this. More...

void	Shutdown (ShutdownCause cause=ShutdownCause.Ok, string message=null)
	Shutdown the runner. Can be called from inside the simulation (during a simulation callback), the shutdown will commence during the next Service(double?) call. More...

System.Threading.Tasks.Task	ShutdownAsync (ShutdownCause cause=ShutdownCause.Ok, string message=null)
	Shutdown the runner asynchronously. Can be called from a simulation callback. Will also wait for the connection to be properly disconnected. More...

System.Threading.Tasks.Task	WaitForShutdownAsync ()
	Wait for the simulation shutdown is signaled. This is an alternative way to listen for the Arguments.ShutdownCallback callback. More...

System.Threading.Tasks.Task	WaitForShutdownAsync (CancellationToken cancellationToken)
	Wait for the simulation shutdown is signaled. This is an alternative way to listen for the Arguments.ShutdownCallback callback. More...

System.Threading.Tasks.Task	WaitForStartAsync (CancellationToken cancellationToken)
	When starting the runner synchronously this Task can be used to wait for success, error or timeout. More...

System.Threading.Tasks.Task	WaitForStartAsync (float timeoutInSeconds)
	When starting the runner synchronously this Task can be used to wait for success, error or timeout. More...

Static Public Member Functions
static implicit	operator bool (SessionRunner v)
	Support Unity null checks. More...

static SessionRunner	Start (Arguments arguments)
	Create a runner object and initiates the start procedure. This method returns right away and will not wait until the actual simulation is started after the start protocol and potentially waiting for a snapshot. Use WaitForStartAsync(CancellationToken) to get notified about the actual local game start. More...

static Task< SessionRunner >	StartAsync (Arguments arguments)
	Async version of the start sequence. Will return the runner object once the connection is complete. Arguments.StartGameTimeoutInSeconds must be greater than 0. Set explicit Arguments.TaskRunner or the default Task.Factory is used. Use Arguments.CancellationToken to cancel this task. Make sure to run this from a Unity "async void" method to not lose the unhandled exceptions. More...

Public Attributes
bool	IsRunning => State == SessionState.Running
	Returns if the SessionRunner is running a simulation. More...

Protected Member Functions
virtual void	OnShutdown (ShutdownArgs args)
	Can be overridden in a subclass not be notified on shutdowns. Is called right after the Arguments.ShutdownCallback callback. More...

Static Protected Member Functions
static SessionRunner	CreateRunnerInternal (Arguments arguments)
	Create runner object and initiates the start procedure. More...

static void	ShutdownInternal (SessionRunner runner, ShutdownCause cause, string message=null)
	Internal shutdown method. More...

Properties
ICommunicator	Communicator `[get]`
	Access the communicator object. More...

SimulationUpdateTime	DeltaTimeType `[get, set]`
	Will be used by the Unity runner to update the Quantum simulation with different delta time settings. More...

IDeterministicGame	DeterministicGame `[get]`
	Access the Quantum game. Will be created during the start sequence. More...

string	Id `[get]`
	Runner id, is set by Arguments.RunnerId. More...

Action< ShutdownArgs >	OnShutdownCallback `[get, set]`
	Get and set the shutdown callback. More...

RecordingFlags	RecordingFlags `[get]`
	Access the recording flags that the runner was started with. More...

DeterministicSession	Session `[get]`
	Access the Quantum session. Will be created during the start sequence. More...

SessionState	State `[get]`
	Get the current state of the runner. More...

Detailed Description

The SessionRunner helps to start, run and shutdown a Quantum simulation. It should never be reused for multiple simulations of multiple runs of the same game session. Always recrate the runner. It has an extensive list of starting Arguments that make it start-able for a variety of use cases: Local, Multiplayer, Replay, Server etc It extracts platform dependent code into the IRunnerFactory parameter. It offers asynchronous methods to start and stop the runner but although it uses the TPL syntax for convenience it is not considered to be run in a multi-threaded environment. Use the non-async versions of the methods or use a ConcurrentExclusiveSchedulerPair.ExclusiveScheduler for unit tests and console applications. Also never use the async methods from the Quantum server plugin, parallelization is done by the Photon-Server. This class is delivered in source code to enable developers to create custom runner code.

Member Enumeration Documentation

◆ SessionState

enum Quantum.SessionRunner.SessionState

strong

The session runner has a state machine.

Enumerator
NotStarted	Freshly created state.
Starting	The runner is starting and waiting for the start protocol to complete.
Running	The simulation is running.
ShuttingDown	The runner is shutting down and waiting to complete shutdown sequence.
Shutdown	The runner is shutdown.

Member Function Documentation

◆ operator bool()

static implicit Quantum.SessionRunner.operator bool ( SessionRunner v )

inlinestatic

Support Unity null checks.

Parameters

v

◆ Dispose()

void Quantum.SessionRunner.Dispose ( )

inline

Implements disposable interface. Calls Shutdown internally. This is also called from inside Session.Destroy() to signal shutdown by the simulation.

◆ OnShutdown()

virtual void Quantum.SessionRunner.OnShutdown ( ShutdownArgs args )

inlineprotectedvirtual

Can be overridden in a subclass not be notified on shutdowns. Is called right after the Arguments.ShutdownCallback callback.

Parameters

args	The shutdown arguments

◆ Service()

void Quantum.SessionRunner.Service ( double? deltaTime = null )

inline

To update the Quantum simulation this needs to be run from the outside. From Unity is would be a MonoBehaviour, on the plugin it would be from OnDeterministicUpdate() and the spectator has an extra service task to tick this.

Parameters

deltaTime If null the internal stopwatch is used to update, otherwise pass in the desired delta time to progress the simulation.

◆ Start()

static SessionRunner Quantum.SessionRunner.Start ( Arguments arguments )

inlinestatic

Create a runner object and initiates the start procedure. This method returns right away and will not wait until the actual simulation is started after the start protocol and potentially waiting for a snapshot. Use WaitForStartAsync(CancellationToken) to get notified about the actual local game start.

Parameters

arguments Start runner arguments.

Returns: Session runner object

Exceptions

ArgumentException Arguments were invalid, check exception message.

◆ StartAsync()

static Task<SessionRunner> Quantum.SessionRunner.StartAsync ( Arguments arguments )

inlinestatic

Async version of the start sequence. Will return the runner object once the connection is complete. Arguments.StartGameTimeoutInSeconds must be greater than 0. Set explicit Arguments.TaskRunner or the default Task.Factory is used. Use Arguments.CancellationToken to cancel this task. Make sure to run this from a Unity "async void" method to not lose the unhandled exceptions.

Parameters

arguments Start runner arguments.

Returns: Session runner object

Exceptions

ArgumentException	Arguments were invalid, check exception message.
SessionRunnerException	Session failed to start.

◆ Shutdown()

void Quantum.SessionRunner.Shutdown	(	ShutdownCause	cause = `ShutdownCause.Ok`,
		string	message = `null`
	)

inline

Shutdown the runner. Can be called from inside the simulation (during a simulation callback), the shutdown will commence during the next Service(double?) call.

Parameters

cause	Shutdown cause
message	The message for ShutdownArgs

◆ ShutdownAsync()

System.Threading.Tasks.Task Quantum.SessionRunner.ShutdownAsync	(	ShutdownCause	cause = `ShutdownCause.Ok`,
		string	message = `null`
	)

inline

Shutdown the runner asynchronously. Can be called from a simulation callback. Will also wait for the connection to be properly disconnected.

Parameters

cause	Shutdown cause
message	The message for ShutdownArgs

Returns: Once the complete shutdown is completed.

Exceptions

SessionRunnerException The runner has no TaskFactory with a Scheduler (e.g. started with DotNetRunnerFactory), use Shutdown instead.

◆ WaitForStartAsync() [1/2]

System.Threading.Tasks.Task Quantum.SessionRunner.WaitForStartAsync ( float timeoutInSeconds )

inline

When starting the runner synchronously this Task can be used to wait for success, error or timeout.

Parameters

timeoutInSeconds Wait for game start timeout.

Returns: Returns when the start has completed or failed.

◆ WaitForStartAsync() [2/2]

System.Threading.Tasks.Task Quantum.SessionRunner.WaitForStartAsync ( CancellationToken cancellationToken )

inline

When starting the runner synchronously this Task can be used to wait for success, error or timeout.

Parameters

cancellationToken Cancellation token.

Returns: Returns when the start has completed or failed.

◆ WaitForShutdownAsync() [1/2]

System.Threading.Tasks.Task Quantum.SessionRunner.WaitForShutdownAsync ( CancellationToken cancellationToken )

inline

Wait for the simulation shutdown is signaled. This is an alternative way to listen for the Arguments.ShutdownCallback callback.

Parameters

cancellationToken Token to cancel this task

Returns: After the runner shut down.

◆ WaitForShutdownAsync() [2/2]

System.Threading.Tasks.Task Quantum.SessionRunner.WaitForShutdownAsync ( )

inline

Wait for the simulation shutdown is signaled. This is an alternative way to listen for the Arguments.ShutdownCallback callback.

Returns: After the runner shut down.

◆ CreateRunnerInternal()

static SessionRunner Quantum.SessionRunner.CreateRunnerInternal ( Arguments arguments )

inlinestaticprotected

Create runner object and initiates the start procedure.

Parameters

arguments Start arguments.

Returns: Initialized runner object.

◆ ShutdownInternal()

static void Quantum.SessionRunner.ShutdownInternal	(	SessionRunner	runner,
		ShutdownCause	cause,
		string	message = `null`
	)

inlinestaticprotected

Internal shutdown method.

Parameters

runner	Session runner object.
cause	Shutdown code.
message	The message for ShutdownArgs

Member Data Documentation

◆ IsRunning

bool Quantum.SessionRunner.IsRunning => State == SessionState.Running

Returns if the SessionRunner is running a simulation.

Property Documentation

◆ Session

DeterministicSession Quantum.SessionRunner.Session

get

Access the Quantum session. Will be created during the start sequence.

◆ DeterministicGame

IDeterministicGame Quantum.SessionRunner.DeterministicGame

get

Access the Quantum game. Will be created during the start sequence.

◆ Id

string Quantum.SessionRunner.Id

get

Runner id, is set by Arguments.RunnerId.

◆ Communicator

ICommunicator Quantum.SessionRunner.Communicator

get

Access the communicator object.

◆ State

SessionState Quantum.SessionRunner.State

get

Get the current state of the runner.

◆ DeltaTimeType

SimulationUpdateTime Quantum.SessionRunner.DeltaTimeType

getset

Will be used by the Unity runner to update the Quantum simulation with different delta time settings.

◆ RecordingFlags

RecordingFlags Quantum.SessionRunner.RecordingFlags

get

Access the recording flags that the runner was started with.

◆ OnShutdownCallback

Action<ShutdownArgs> Quantum.SessionRunner.OnShutdownCallback

getset

Get and set the shutdown callback.

Quantum 3 3.1.0

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Properties

Detailed Description

Member Enumeration Documentation

◆ SessionState

Member Function Documentation

◆ operator bool()

◆ Dispose()

◆ OnShutdown()

◆ Service()

◆ Start()

◆ StartAsync()

◆ Shutdown()

◆ ShutdownAsync()

◆ WaitForStartAsync() [1/2]

◆ WaitForStartAsync() [2/2]

◆ WaitForShutdownAsync() [1/2]

◆ WaitForShutdownAsync() [2/2]

◆ CreateRunnerInternal()

◆ ShutdownInternal()

Member Data Documentation

◆ IsRunning

Property Documentation

◆ Session

◆ DeterministicGame

◆ Id

◆ Communicator

◆ State

◆ DeltaTimeType

◆ RecordingFlags

◆ OnShutdownCallback