Photon Quantum 3.0.0

Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Member Functions | Properties | List of all members
Quantum.SessionRunner Class Reference

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 Destroy ()
 Calls shutdown. Backwards compatibility. More...
 
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)
 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)
 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.OnShutdown 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.OnShutdown 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< SessionRunnerStartAsync (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 (ShutdownCause cause)
 Can be overridden in a subclass not be notified on shutdowns. Is called right after tje Arguments.OnShutdown 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)
 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...
 
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

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.

◆ Destroy()

void Quantum.SessionRunner.Destroy ( )
inline

Calls shutdown. Backwards compatibility.

◆ OnShutdown()

virtual void Quantum.SessionRunner.OnShutdown ( ShutdownCause  cause)
inlineprotectedvirtual

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

Parameters
causeThe shutdown cause

◆ 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
deltaTimeIf 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
argumentsStart runner arguments.
Returns
Session runner object
Exceptions
ArgumentExceptionArguments 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
argumentsStart runner arguments.
Returns
Session runner object
Exceptions
ArgumentExceptionArguments were invalid, check exception message.
SessionRunnerExceptionSession failed to start.

◆ Shutdown()

void Quantum.SessionRunner.Shutdown ( ShutdownCause  cause = ShutdownCause.Ok)
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
causeShutdown cause

◆ ShutdownAsync()

System.Threading.Tasks.Task Quantum.SessionRunner.ShutdownAsync ( ShutdownCause  cause = ShutdownCause.Ok)
inline

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

Parameters
causeShutdown cause
Returns
Once the complete shutdown is completed.
Exceptions
SessionRunnerExceptionTaskFactory was never set.

◆ 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
timeoutInSecondsWait 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
cancellationTokenCancellation 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.OnShutdown callback.

Parameters
cancellationTokenToken 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.OnShutdown 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
argumentsStart arguments.
Returns
Initialized runner object.

◆ ShutdownInternal()

static void Quantum.SessionRunner.ShutdownInternal ( SessionRunner  runner,
ShutdownCause  cause 
)
inlinestaticprotected

Internal shutdown method.

Parameters
runnerSession runner object.
causeShutdown code.

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.