time-sync: add experimental external-coupling api

SilKit/IntegrationTests/Hourglass/MockCapi.cpp

@@ -658,6 +658,21 @@ extern "C"
         return globalCapi->SilKit_TimeSyncService_Now(timeSyncService, outNanosecondsTime);
     }
 
+    SilKit_ReturnCode SilKitCALL SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler(
+        SilKit_TimeSyncService* timeSyncService, void* context, SilKit_Experimental_TimeSyncExternalCouplingHandler_t handler,
+        SilKit_HandlerId* outHandlerId)
+    {
+        return globalCapi->SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler(timeSyncService, context,
+                                                                                          handler, outHandlerId);
+    }
+
+    SilKit_ReturnCode SilKitCALL SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler(
+        SilKit_TimeSyncService* timeSyncService, SilKit_HandlerId handlerId)
+    {
+        return globalCapi->SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler(timeSyncService,
+                                                                                             handlerId);
+    }
+
     // SystemMonitor
 
     SilKit_ReturnCode SilKitCALL SilKit_SystemMonitor_Create(SilKit_SystemMonitor** outSystemMonitor,

SilKit/IntegrationTests/Hourglass/MockCapi.hpp

@@ -356,6 +356,13 @@ class MockCapi
     MOCK_METHOD(SilKit_ReturnCode, SilKit_TimeSyncService_Now,
                 (SilKit_TimeSyncService * timeSyncService, SilKit_NanosecondsTime* outNanosecondsTime));
 
+    MOCK_METHOD(SilKit_ReturnCode, SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler,
+                (SilKit_TimeSyncService * timeSyncService, void* context,
+                 SilKit_Experimental_TimeSyncExternalCouplingHandler_t handler, SilKit_HandlerId* outHandlerId));
+
+    MOCK_METHOD(SilKit_ReturnCode, SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler,
+                (SilKit_TimeSyncService * timeSyncService, SilKit_HandlerId handlerId));
+
     // SystemMonitor
 
     MOCK_METHOD(SilKit_ReturnCode, SilKit_SystemMonitor_Create,

SilKit/IntegrationTests/Hourglass/Test_HourglassOrchestration.cpp

@@ -432,6 +432,39 @@ TEST_F(Test_HourglassOrchestration, SilKit_TimeSyncService_Now)
     EXPECT_EQ(timeSyncService.Now(), nanoseconds);
 }
 
+TEST_F(Test_HourglassOrchestration, SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler)
+{
+    using testing::_;
+
+    const SilKit_HandlerId cHandlerId{12345};
+    const auto cppHandlerId = static_cast<SilKit::Util::HandlerId>(cHandlerId);
+
+    SilKit::DETAIL_SILKIT_DETAIL_NAMESPACE_NAME::Impl::Services::Orchestration::TimeSyncService timeSyncService{
+        mockLifecycleService};
+
+    EXPECT_CALL(capi, SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler(mockTimeSyncService, _, _, _))
+        .WillOnce(DoAll(SetArgPointee<3>(cHandlerId), Return(SilKit_ReturnCode_SUCCESS)));
+
+    EXPECT_EQ(timeSyncService.ExperimentalAddExternalCouplingHandler([] {}), cppHandlerId);
+}
+
+TEST_F(Test_HourglassOrchestration, SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler)
+{
+    using testing::_;
+
+    const SilKit_HandlerId cHandlerId{12345};
+    const auto cppHandlerId = static_cast<SilKit::Util::HandlerId>(cHandlerId);
+
+    SilKit::DETAIL_SILKIT_DETAIL_NAMESPACE_NAME::Impl::Services::Orchestration::TimeSyncService timeSyncService{
+        mockLifecycleService};
+
+    EXPECT_CALL(capi,
+                SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler(mockTimeSyncService, cHandlerId))
+        .WillOnce(Return(SilKit_ReturnCode_SUCCESS));
+
+    timeSyncService.ExperimentalRemoveExternalCouplingHandler(cppHandlerId);
+}
+
 // SystemMonitor
 
 TEST_F(Test_HourglassOrchestration, SilKit_SystemMonitor_Create)

SilKit/include/silkit/capi/Orchestration.h

@@ -757,6 +757,31 @@ SilKitAPI SilKit_ReturnCode SilKitCALL SilKit_Experimental_SystemController_SetW
 typedef SilKit_ReturnCode(SilKitFPTR* SilKit_Experimental_SystemController_SetWorkflowConfiguration_t)(
     SilKit_Experimental_SystemController* systemController, const SilKit_WorkflowConfiguration* workflowConfiguration);
 
+/*! Callback type to indicate external simulation step coupling.
+ *  Cf., \ref SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler
+ */
+typedef void(SilKitFPTR* SilKit_Experimental_TimeSyncExternalCouplingHandler_t)(
+    void* context, SilKit_TimeSyncService* timeSyncService);
+
+/*! \brief Register a callback for external simulation step coupling
+ *
+ * \param timeSyncService The time sync. service obtained via \ref SilKit_TimeSyncService_Create.
+ * \param context The user context pointer made available to the handler.
+ * \param handler The handler to be called when completion of the current sim. step will immediately progress sim. time.
+ * \param outHandlerId The handler identifier that can be used to remove the callback.
+ */
+SilKitAPI SilKit_ReturnCode SilKitCALL SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler(
+    SilKit_TimeSyncService* timeSyncService, void* context,
+    SilKit_Experimental_TimeSyncExternalCouplingHandler_t handler, SilKit_HandlerId* outHandlerId);
+
+/*! \brief  Remove a \ref SilKit_Experimental_ExternalCouplingHandler_t by SilKit_HandlerId on this participant
+ *
+ * \param timeSyncService The time sync. service obtained via \ref SilKit_TimeSyncService_Create.
+ * \param handlerId Identifier of the callback to be removed. Obtained upon adding to respective handler.
+ */
+SilKitAPI SilKit_ReturnCode SilKitCALL SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler(
+    SilKit_TimeSyncService* timeSyncService, SilKit_HandlerId handlerId);
+
 SILKIT_END_DECLS
 
 #pragma pack(pop)

SilKit/include/silkit/detail/impl/experimental/services/orchestration/TimeSyncServiceExtensions.ipp

@@ -0,0 +1,65 @@
+/* Copyright (c) 2022 Vector Informatik GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
+
+#pragma once
+
+#include "silkit/detail/impl/services/orchestration/TimeSyncService.hpp"
+
+
+namespace SilKit {
+DETAIL_SILKIT_DETAIL_VN_NAMESPACE_BEGIN
+namespace Experimental {
+namespace Services {
+namespace Orchestration {
+
+auto AddExternalCouplingHandler(SilKit::Services::Orchestration::ITimeSyncService* cppITimeSyncService,
+                                std::function<void()> handler) -> SilKit::Util::HandlerId
+{
+    auto& cppTimeSyncService = dynamic_cast<Impl::Services::Orchestration::TimeSyncService&>(*cppITimeSyncService);
+
+    return cppTimeSyncService.ExperimentalAddExternalCouplingHandler(handler);
+}
+
+void RemoveExternalCouplingHandler(SilKit::Services::Orchestration::ITimeSyncService* cppITimeSyncService,
+                                   SilKit::Util::HandlerId handlerId)
+{
+    auto& cppTimeSyncService = dynamic_cast<Impl::Services::Orchestration::TimeSyncService&>(*cppITimeSyncService);
+
+    return cppTimeSyncService.ExperimentalRemoveExternalCouplingHandler(handlerId);
+}
+
+} // namespace Orchestration
+} // namespace Services
+} // namespace Experimental
+DETAIL_SILKIT_DETAIL_VN_NAMESPACE_CLOSE
+} // namespace SilKit
+
+
+namespace SilKit {
+namespace Experimental {
+namespace Services {
+namespace Orchestration {
+using SilKit::DETAIL_SILKIT_DETAIL_NAMESPACE_NAME::Experimental::Services::Orchestration::AddExternalCouplingHandler;
+using SilKit::DETAIL_SILKIT_DETAIL_NAMESPACE_NAME::Experimental::Services::Orchestration::RemoveExternalCouplingHandler;
+} // namespace Orchestration
+} // namespace Services
+} // namespace Experimental
+} // namespace SilKit

SilKit/include/silkit/detail/impl/services/orchestration/TimeSyncService.hpp

@@ -25,6 +25,7 @@
 
 #include "silkit/participant/exception.hpp"
 #include "silkit/services/orchestration/ITimeSyncService.hpp"
+#include "silkit/experimental/services/orchestration/TimeSyncDatatypesExtensions.hpp"
 
 
 namespace SilKit {
@@ -49,11 +50,29 @@ class TimeSyncService : public SilKit::Services::Orchestration::ITimeSyncService
 
     inline auto Now() const -> std::chrono::nanoseconds override;
 
+public:
+    inline auto ExperimentalAddExternalCouplingHandler(
+        SilKit::Experimental::Services::Orchestration::TimeSyncExternalCouplingHandler) -> SilKit::Util::HandlerId;
+
+    inline void ExperimentalRemoveExternalCouplingHandler(SilKit::Util::HandlerId handlerId);
+
+private:
+    template <typename HandlerFunction>
+    struct HandlerData
+    {
+        HandlerFunction handler{};
+    };
+
+    template <typename HandlerFunction>
+    using HandlerDataMap = std::unordered_map<SilKit::Util::HandlerId, std::unique_ptr<HandlerData<HandlerFunction>>>;
+
 private:
     SilKit_TimeSyncService* _timeSyncService{nullptr};
 
     std::unique_ptr<SimulationStepHandler> _simulationStepHandler;
     std::unique_ptr<SimulationStepHandler> _simulationStepHandlerAsync;
+    HandlerDataMap<SilKit::Experimental::Services::Orchestration::TimeSyncExternalCouplingHandler>
+        _externalCouplingHandlers;
 };
 
 } // namespace Orchestration
@@ -136,6 +155,42 @@ auto TimeSyncService::Now() const -> std::chrono::nanoseconds
     return std::chrono::nanoseconds{nanosecondsTime};
 }
 
+inline auto TimeSyncService::ExperimentalAddExternalCouplingHandler(std::function<void()> handler)
+    -> SilKit::Util::HandlerId
+{
+    const auto cHandler = [](void* context, SilKit_TimeSyncService* cTimeSyncService) {
+        SILKIT_UNUSED_ARG(cTimeSyncService);
+
+        const auto data =
+            static_cast<HandlerData<SilKit::Experimental::Services::Orchestration::TimeSyncExternalCouplingHandler>*>(
+                context);
+        data->handler();
+    };
+
+    SilKit_HandlerId handlerId;
+
+    auto handlerData =
+        std::make_unique<HandlerData<SilKit::Experimental::Services::Orchestration::TimeSyncExternalCouplingHandler>>();
+    handlerData->handler = std::move(handler);
+
+    const auto returnCode = SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler(
+        _timeSyncService, handlerData.get(), cHandler, &handlerId);
+    ThrowOnError(returnCode);
+
+    _externalCouplingHandlers.emplace(static_cast<SilKit::Util::HandlerId>(handlerId), std::move(handlerData));
+
+    return static_cast<SilKit::Services::HandlerId>(handlerId);
+}
+
+inline void TimeSyncService::ExperimentalRemoveExternalCouplingHandler(const SilKit::Util::HandlerId cppHandlerId)
+{
+    const auto cHandlerId = static_cast<SilKit_HandlerId>(cppHandlerId);
+
+    const auto returnCode =
+        SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler(_timeSyncService, cHandlerId);
+    ThrowOnError(returnCode);
+}
+
 } // namespace Orchestration
 } // namespace Services
 } // namespace Impl

SilKit/include/silkit/experimental/services/orchestration/TimeSyncDatatypesExtensions.hpp

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2023 Vector Informatik GmbH
+//
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include "silkit/services/orchestration/ITimeSyncService.hpp"
+
+namespace SilKit {
+namespace Experimental {
+namespace Services {
+namespace Orchestration {
+
+/*! Callback type to indicate external simulation step coupling.
+ *  Cf., \ref AddExternalCouplingHandler(ITimeSyncService*,TimeSyncExternalCouplingHandler);
+ */
+using TimeSyncExternalCouplingHandler = std::function<void()>;
+
+} // namespace Orchestration
+} // namespace Services
+} // namespace Experimental
+} // namespace SilKit

SilKit/include/silkit/experimental/services/orchestration/TimeSyncServiceExtensions.hpp

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2023 Vector Informatik GmbH
+//
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#include "silkit/experimental/services/orchestration/TimeSyncDatatypesExtensions.hpp"
+#include "silkit/services/orchestration/ITimeSyncService.hpp"
+
+#include "silkit/detail/macros.hpp"
+
+namespace SilKit {
+DETAIL_SILKIT_DETAIL_VN_NAMESPACE_BEGIN
+namespace Experimental {
+namespace Services {
+namespace Orchestration {
+
+/*! \brief Add a \ref SilKit::Experimental::Services::Orchestration::ExternalCouplingHandler on a given time sync.
+ *         service for external simulation step coupling.
+ *
+ * \param timeSyncService The time sync. service.
+ * \param handler The handler to be called when completion of the current sim. step will immediately progress sim. time.
+ *
+ * \return The handler identifier that can be used to remove the callback.
+ */
+DETAIL_SILKIT_CPP_API auto AddExternalCouplingHandler(
+    SilKit::Services::Orchestration::ITimeSyncService* timeSyncService,
+    SilKit::Experimental::Services::Orchestration::TimeSyncExternalCouplingHandler handler) -> SilKit::Util::HandlerId;
+
+/*! \brief Remove a LinSlaveConfigurationHandler by HandlerId on a given controller.
+ *
+ * Requires \ref Services::Lin::LinControllerMode::Master.
+ *
+ * \param timeSyncService The time sync. service.
+ * \param handlerId Identifier of the callback to be removed. Obtained upon adding to respective handler.
+ */
+DETAIL_SILKIT_CPP_API void RemoveExternalCouplingHandler(
+    SilKit::Services::Orchestration::ITimeSyncService* timeSyncService, SilKit::Util::HandlerId handlerId);
+
+} // namespace Orchestration
+} // namespace Services
+} // namespace Experimental
+DETAIL_SILKIT_DETAIL_VN_NAMESPACE_CLOSE
+} // namespace SilKit
+
+
+//! \cond DOCUMENT_HEADER_ONLY_DETAILS
+#include "silkit/detail/impl/experimental/services/orchestration/TimeSyncServiceExtensions.ipp"
+//! \endcond

SilKit/source/capi/CapiOrchestration.cpp

@@ -29,6 +29,8 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
 #include "CapiImpl.hpp"
 #include "TypeConversion.hpp"
 
+#include "services/orchestration/TimeSyncServiceExtensionsImpl.hpp"
+
 #include <memory>
 #include <map>
 #include <mutex>
@@ -726,3 +728,41 @@ try
     return SilKit_ReturnCode_SUCCESS;
 }
 CAPI_CATCH_EXCEPTIONS
+
+
+SilKit_ReturnCode SilKitCALL SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler(
+    SilKit_TimeSyncService* cTimeSyncService, void* context, SilKit_Experimental_TimeSyncExternalCouplingHandler_t handler,
+    SilKit_HandlerId* outHandlerId)
+try
+{
+    ASSERT_VALID_POINTER_PARAMETER(cTimeSyncService);
+    ASSERT_VALID_HANDLER_PARAMETER(handler);
+    ASSERT_VALID_OUT_PARAMETER(outHandlerId);
+
+    auto* cppITimeSyncService = reinterpret_cast<SilKit::Services::Orchestration::ITimeSyncService*>(cTimeSyncService);
+
+    auto cppHandlerId = SilKit::Experimental::Services::Orchestration::AddExternalCouplingHandler(
+        cppITimeSyncService, [handler, context, cTimeSyncService]() { handler(context, cTimeSyncService); });
+
+    *outHandlerId = static_cast<SilKit_HandlerId>(cppHandlerId);
+
+    return SilKit_ReturnCode_SUCCESS;
+}
+CAPI_CATCH_EXCEPTIONS
+
+
+SilKit_ReturnCode SilKitCALL SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler(
+    SilKit_TimeSyncService* cTimeSyncService, SilKit_HandlerId cHandlerId)
+try
+{
+    ASSERT_VALID_POINTER_PARAMETER(cTimeSyncService);
+
+    const auto cppITimeSyncService =
+        reinterpret_cast<SilKit::Services::Orchestration::ITimeSyncService*>(cTimeSyncService);
+    const auto cppHandlerId = static_cast<SilKit::Util::HandlerId>(cHandlerId);
+
+    SilKit::Experimental::Services::Orchestration::RemoveExternalCouplingHandler(cppITimeSyncService, cppHandlerId);
+
+    return SilKit_ReturnCode_SUCCESS;
+}
+CAPI_CATCH_EXCEPTIONS

SilKit/source/capi/Test_CapiSymbols.cpp

@@ -114,6 +114,8 @@ TEST(Test_CapiSymbols, DISABLED_link_all_public_symbols)
     (void)SilKit_TimeSyncService_SetSimulationStepHandler(nullptr, nullptr, nullptr, 0);
     (void)SilKit_TimeSyncService_SetSimulationStepHandlerAsync(nullptr, nullptr, nullptr, 0);
     (void)SilKit_TimeSyncService_CompleteSimulationStep(nullptr);
+    (void)SilKit_Experimental_TimeSyncService_AddExternalCouplingHandler(nullptr, nullptr, nullptr, nullptr);
+    (void)SilKit_Experimental_TimeSyncService_RemoveExternalCouplingHandler(nullptr, 0);
     (void)SilKit_LifecycleService_Pause(nullptr, "");
     (void)SilKit_LifecycleService_Continue(nullptr);
     (void)SilKit_LifecycleService_Stop(nullptr, "");