Orchestration C API

SilKit_ReturnCode SilKit_LifecycleService_Create(SilKit_LifecycleService **outLifecycleService, SilKit_Participant *participant, const SilKit_LifecycleConfiguration *startConfiguration)

Create a lifecycle service at this SIL Kit simulation participant.

The object returned must not be deallocated using free()!

Parameters

  • outLifecycleService – Pointer that refers to the resulting lifecycle service (out parameter).

  • participant – The simulation participant at which the lifecycle service should be created.

  • startConfiguration – The desired start configuration of the lifecycle.

SilKit_ReturnCode SilKit_LifecycleService_SetCommunicationReadyHandler(SilKit_LifecycleService *lifecycleService, void *context, SilKit_LifecycleService_CommunicationReadyHandler_t handler)

Register a callback that is executed once communication with controllers is possible.

The handler is called after SilKit_ParticipantState_CommunicationInitialized is reached. This handler is invoked on the SilKit I/O worker thread, and receiving messages during the handler invocation is not possible. For an asynchronous invocation, see SilKit_LifecycleService_SetCommunicationReadyHandlerAsync and SilKit_LifecycleService_CompleteCommunicationReadyHandlerAsync. After the handler has been processed, the participant switches to the SilKit_ParticipantState_ReadyToRun state.

Parameters

  • lifecycleService – The lifecycle service that switched to the CommunicationInitialized participant state.

  • context – A user provided context accessible in the handler

  • handler – The handler to be called on initialization

SilKit_ReturnCode SilKit_LifecycleService_SetStartingHandler(SilKit_LifecycleService *lifecycleService, void *context, SilKit_LifecycleService_StartingHandler_t handler)

(Asynchronous participants only) Register a callback that is executed once directly before the participant enters SilKit_ParticipantState_Running.

This handler is triggered just before the participant changes to SilKit::Services::Orchestration::ParticipantState::Running. It is only triggered if the participant does NOT use virtual time synchronization. It does not block other participants from changing to ParticipantState::Running and should only be used for lightweight operations such as starting timers. It is executed in the context of an internal thread that received the command. After the handler has been processed, the participant switches to the SilKit_ParticipantState_Running state.

Parameters

  • lifecycleService – The lifecycle service that triggers the StartingHandler.

  • context – A user provided context accessible in the handler.

  • handler – The handler to be called when starting.

SilKit_ReturnCode SilKit_LifecycleService_SetStopHandler(SilKit_LifecycleService *lifecycleService, void *context, SilKit_LifecycleService_StopHandler_t handler)

Register a callback that is executed on simulation stop.

The handler is called when the participant has entered the SilKit_ParticipantState_Stopping state. It is executed in the context of an internal thread that received the command. After the handler has been processed, the participant switches to the SilKit_ParticipantState_Stopped state.

Throwing an error inside the handler will cause a call to ReportError().

Parameters

  • lifecycleService – The lifecycle service receiving the stop command

  • context – A user provided context accessible in the handler

  • handler – The handler to be called

SilKit_ReturnCode SilKit_LifecycleService_SetShutdownHandler(SilKit_LifecycleService *lifecycleService, void *context, SilKit_LifecycleService_ShutdownHandler_t handler)

Register a callback that is executed on simulation shutdown.

The handler is called when the participant is entering the SilKit_ParticipantState_ShuttingDown state. It is executed in the context of the middleware thread that received the command. After the handler has been processed, the participant switches to the SilKit_ParticipantState_Shutdown state and is allowed to terminate.

Parameters

  • lifecycleService – The lifecycle service receiving the shutdown command

  • context – A user provided context accessible in the handler

  • handler – The handler to be called

SilKit_ReturnCode SilKit_LifecycleService_StartLifecycle(SilKit_LifecycleService *lifecycleService)

Start the lifecycle.

Parameters

lifecycleService – The instance of the lifecycleService.

SilKit_ReturnCode SilKit_LifecycleService_WaitForLifecycleToComplete(SilKit_LifecycleService *lifecycleService, SilKit_ParticipantState *outParticipantState)

Wait for to asynchronous run operation to complete and return the final participant state.

Blocks until the simulation is shutdown. Prior to this method, SilKit_LifecycleService_StartLifecycle has to be called.

Parameters

  • lifecycleService – The lifecycle service to wait for completing the asynchronous run operation.

  • outParticipantState – Pointer for storing the final participant state (out parameter).

SilKit_ReturnCode SilKit_LifecycleService_Pause(SilKit_LifecycleService *lifecycleService, const char *reason)

Pause execution of the participant.

Switch to SilKit_ParticipantState_Paused due to the provided reason.

When a client is in state SilKit_ParticipantState_Paused, it must not be considered as unresponsive even if a health monitoring related timeout occurs.

Precondition: State() == SilKit_ParticipantState_Running

Parameters

  • lifecycleService – The lifecycle service of the simulation.

  • reason – A string describing the reason why the simulation was paused (UTF-8).

SilKit_ReturnCode SilKit_LifecycleService_Continue(SilKit_LifecycleService *lifecycleService)

Switch back to SilKit_ParticipantState_Running after having paused.

Precondition: State() == SilKit_ParticipantState_Paused

SilKit_ReturnCode SilKit_TimeSyncService_Create(SilKit_TimeSyncService **outTimeSyncService, SilKit_LifecycleService *lifecycleService)

Create a time sync service at this SIL Kit simulation participant.

The object returned must not be deallocated using free()!

Parameters

  • outTimeSyncService – Pointer that refers to the resulting time sync service (out parameter).

  • lifecycleService – The lifecyle service at which the time sync service should be created.

SilKit_ReturnCode SilKit_TimeSyncService_SetSimulationStepHandler(SilKit_TimeSyncService *timeSyncService, void *context, SilKit_TimeSyncService_SimulationStepHandler_t handler, SilKit_NanosecondsTime initialStepSize)

Set the task to be executed with each grant / tick.

Can be changed at runtime. Execution context depends on the run type.

Parameters

  • timeSyncService – The time-sync service obtained via SilKit_TimeSyncService_Create.

  • context – A user provided context accessible in the handler

  • handler – The handler to be called if the simulation task is due

  • initialStepSize – The initial size of the simulation step of this participant in nanoseconds

SilKit_ReturnCode SilKit_TimeSyncService_SetSimulationStepHandlerAsync(SilKit_TimeSyncService *timeSyncService, void *context, SilKit_TimeSyncService_SimulationStepHandler_t handler, SilKit_NanosecondsTime initialStepSize)

Set the task to be executed with each grant / tick.

Can be changed at runtime. Execution context depends on the run type.

The difference to SetSimulationStepHandler is, that after execution of the simulation task the advance in simulation time will NOT be signaled to other participants. Progress in simulation time (including all other participants) will cease. Instead, SilKit_TimeSyncService_CompleteSimulationStep must be called FROM ANY OTHER THREAD to ‘unlock’ the thread executing the simulation task, and let it execute again. Thus, a fine grained control over the whole simulation time progress can be achieved by calling CompleteSimulationStep from an application thread. Participants using ‘regular’ simulation tasks and non-blocking simulation tasks may be freely mixed.

Parameters

  • timeSyncService – The time-sync service obtained via SilKit_TimeSyncService_Create.

  • context – A user provided context accessible in the handler

  • handler – The handler to be called if the simulation task is due

  • initialStepSize – The initial size of the simulation step of this participant in nanoseconds

SilKit_ReturnCode SilKit_TimeSyncService_CompleteSimulationStep(SilKit_TimeSyncService *timeSyncService)

Complete the current step of a non-blocking simulation task.

Parameters

timeSyncService – The time sync service