Add socom as SOME/IP abstraction

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
       - id: check-executables-have-shebangs
       - id: check-added-large-files
         args: [--maxkb=50, --enforce-all] # increase or add git lfs if too strict
-        exclude: MODULE.bazel.lock|tests/benchmarks/benchmarks_analysis.md
+        exclude: MODULE.bazel.lock|tests/benchmarks/benchmarks_analysis.md|src/socom/test/unit/runtime_tests.cpp
 
   - repo: https://github.com/jumanjihouse/pre-commit-hooks
     rev: 38980559e3a605691d6579f96222c30778e5a69e # 3.0.0

MODULE.bazel

@@ -158,7 +158,7 @@ register_toolchains(
 # ============================================================================
 # Tooling & Development
 # ============================================================================
-bazel_dep(name = "score_tooling", version = "1.0.4", dev_dependency = True)
+bazel_dep(name = "score_tooling", version = "1.1.2", dev_dependency = True)
 bazel_dep(name = "aspect_rules_lint", version = "2.3.0", dev_dependency = True)
 bazel_dep(name = "buildifier_prebuilt", version = "8.5.1", dev_dependency = True)
 

src/socom/BUILD

@@ -0,0 +1,54 @@
+# *******************************************************************************
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+load("@rules_cc//cc:cc_library.bzl", "cc_library")
+load("@score_baselibs//score/language/safecpp:toolchain_features.bzl", "COMPILER_WARNING_FEATURES")
+
+filegroup(
+    name = "headers",
+    srcs = glob(include = ["include/**"]),
+)
+
+cc_library(
+    name = "socom",
+    srcs = glob(include = ["src/**"]),
+    hdrs = [":headers"],
+    defines = [
+        "WITH_SOCOM_DEADLOCK_DETECTION=1",
+    ],
+    features = COMPILER_WARNING_FEATURES,
+    includes = [
+        "include",
+        "src/socom/include",
+    ],
+    visibility = ["//visibility:public"],
+    deps = [
+        "@score_baselibs//score/result",
+    ],
+)
+
+filegroup(
+    name = "mock_headers",
+    srcs = glob(include = ["mock/**"]),
+)
+
+cc_library(
+    name = "mock",
+    hdrs = [":mock_headers"],
+    includes = ["mock"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":socom",
+        "@googletest//:gtest_for_library",
+    ],
+)

src/socom/README.adoc

@@ -0,0 +1,36 @@
+// *******************************************************************************
+// Copyright (c) 2025 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache License Version 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: Apache-2.0
+// *******************************************************************************
+
+= Service Oriented Communication (SOCom)
+:description: SOCom
+:docinfo: shared
+:diagramdir: models
+:imagesdir: images
+:toc: left
+:iconsdir: images
+:icons: font
+:sectnums:
+:sectnumlevels: 5
+
+The bundle service oriented communication (SOCom) implements components for client/server pattern based communication for the following communication paradigms:
+
+* remote procedure call;
+* publish/subscribe (event communication).
+
+SOCom provides interfaces which enable the implementation of service gateways (bridges).
+This allows users to independently implement service bridges for different communication protocols (e.g. IPC, SOME/IP, …).
+SOCom provides intra-process client/server communication only.
+
+== Design
+
+See <<doc/design/README.adoc#,design/>> for a high level design.

src/socom/doc/design/30_structural_view.adoc

@@ -0,0 +1,81 @@
+// *******************************************************************************
+// Copyright (c) 2025 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache License Version 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: Apache-2.0
+// *******************************************************************************
+
+////
+Every asciidoc file in this document starts with the section level 0, i.e. a section like
+....
+= Title
+....
+
+When the file is included from another file within the document, the levels must be adjusted with the `leveloffset` attribute to the `include` directive at the point of inclusion, e.g.
+....
+include::file.adoc[leveloffset=+1]
+....
+////
+
+= Structural View
+
+The bundle service oriented communication (SOCom) implements components for client/server pattern based communication for the following communication paradigms:
+
+* remote procedure call;
+* publish/subscribe (event communication).
+
+SOCom provides interfaces which enable the implementation of service gateways (bridges).
+This allows users to independently implement service bridges for different communication protocols (e.g. IPC, SOME/IP, …).
+SOCom provides intra-process client/server communication only.
+
+.Component diagram of SOCom
+[plantuml, svg, align="center"]
+....
+include::models/component_diagram_socom.puml[]
+....
+
+.Software elements
+
+* <<runtime_component>>;
+* <<client_connector_component>>;
+* <<server_connector_component>>;
+
+[#runtime_component]
+== Runtime
+
+The Runtime creates and connects Client_connectors and Server_connectors.
+In addition to that it has a plugin interface for adding bridges to cross IPC or network boundaries.
+The Runtime must outlive all created Client_connectors and Server_connectors.
+
+[#client_connector_component]
+== Client connector
+
+A client application owns and uses this component to join client/server pattern based service oriented communication (SOCom).
+The client connector interacts with the server connector in order perform the supported communication primitives.
+The client connector API provides the following features:
+
+* service instance state change indications
+* asynchronous remote procedure call
+
+** with method reply
+** without method reply (fire and forget)
+
+* event subscription
+
+** with optional initial value request (required for fields)
+
+* event subscription acknowledge indication
+* event update indication
+* requested event update indication
+
+[#server_connector_component]
+== Server connector
+
+The Server_connector represents a service, which is used by a Client_connector.
+It can send event updates and respond to method calls.

src/socom/doc/design/40_behavioral_view.adoc

@@ -0,0 +1,172 @@
+// *******************************************************************************
+// Copyright (c) 2025 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache License Version 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: Apache-2.0
+// *******************************************************************************
+
+////
+Every asciidoc file in this document starts with the section level 0, i.e. a section like
+....
+= Title
+....
+
+When the file is included from another file within the document, the levels must be adjusted with the `leveloffset` attribute to the `include` directive at the point of inclusion, e.g.
+....
+include::file.adoc[leveloffset=+1]
+....
+////
+
+= Behavioral View
+
+This component implements the following state machines:
+
+* <<event_subscription_state_machine, event subscription state>>;
+* <<service_state_machine, service state>>.
+
+== Runtime
+
+The runtime is a (process internal) service instance broker.
+Client connectors and server connectors are created using the runtime (factory), which keeps track of their existence and state.
+Depending on the existence and state of the communication partners, the runtime takes care for connecting/disconnecting service interface and service instance compatible client and server connectors.
+Additionally, it provides a service instance find interface.
+
+== Server connector
+
+A server application owns and uses this component to join client/server pattern based service oriented communication (SOCom).
+The server connector interacts with the client connector in order perform the supported communication primitives.
+The server connector API provides the following features:
+
+* remote procedure called indication;
+* event subscription state changed indication:
+
+** on first subscriber;
+** on last unsubscriber.
+
+* event update request indication;
+* event mode getter (event with/without initial update);
+* update event;
+* update requested event;
+* acknowledge event subscription.
+
+== Method Communication
+
+Methods calls are routed 1:1 from client to server application.
+If a method reply is requested, the calling client is served with the related reply.
+Independent method calls share no state.
+
+.Interaction diagram: Method communication
+[plantuml, svg, align="center"]
+....
+include::models/interaction_diagram_method_communication.puml[]
+....
+
+== Event Communication
+
+The client subscribes to an event.
+On the subscription, SOCom informs the server using the request for events.
+If no client is subscribed to an event, the server will not send any event updates.
+
+After unsubscription of the subscriber, SOCom informs the server that an event is not subscribed anymore.
+SOCom keeps track of subscription states and related clients.
+
+.Interaction diagram: Event communication
+[plantuml, svg, align="center"]
+....
+include::models/interaction_diagram_event_communication.puml[]
+....
+
+== Field Notification Communication
+
+A field notification is implemented as an event with event update on subscription.
+
+NOTE: Additional behavior compared to field communication:
+since SOCom does not save the current event values, SOCom requests an event update from the server for each new subscriber.
+
+Servers answer this request with update_requested_event().
+Those updates are indicated to the client which is subscribed and has an initial event update pending.
+
+Regular update_event() calls update for the events of the subscriber and also fulfills the initial event update use-case.
+Consequently, update_event() satisfies the event update request implicitly.
+
+.Interaction diagram: Field notification communication
+[plantuml, svg, align="center"]
+....
+include::models/interaction_diagram_field_notification_communication.puml[]
+....
+
+== Service Gateway - find service
+
+The creation of client connectors is forwarded to bridges as request_service() calls.
+Service bridges look up the required service instance within their domain.
+If available, they connect to the remote counterpart and locally create a proxy server connector (forwarding all communication).
+
+.Interaction diagram: Service Gateway - find service
+[plantuml, svg, align="center"]
+....
+include::models/interaction_diagram_service_gateway_find_service.puml[]
+....
+
+== Service Gateway - require service
+
+The creation of client connectors is forwarded to bridges as request_service() calls.
+Service bridges look up the required service instance within their domain.
+If available, they connect to the remote counterpart and locally create a proxy server connector (forwarding all communication).
+
+.Interaction diagram: Service Gateway - require service
+[plantuml, svg, align="center"]
+....
+include::models/interaction_diagram_service_gateway_require_service.puml[]
+....
+
+== Service Gateway - provide service
+
+The creation of server connectors is found by service bridges using the SOCom subscribe_find_service() API.
+Service bridges provide this information within their domain.
+If any domain partner requests the service instance, the service bridge creates a proxy client connector (forwarding all communication).
+
+.Interaction diagram: Service Gateway - provide service
+[plantuml, svg, align="center"]
+....
+include::models/interaction_diagram_service_gateway_provide_service.puml[]
+....
+
+== Deadlock detection
+
+In order to facilitate deadlock detection, before a callback is called by a Client_connector or
+Server_connector the thread id of the caller is saved.
+After the callback returns, the previously saved thread id is removed.
+If the calling object is destructed prematurely the deadlock is detected by checking if the thread
+id is still present, issuing a warning log and terminating the application.
+
+== Client_connector deadlocks
+
+When a running callback destroys the calling Client_connector a deadlock will happen, which will cause the application to be terminated.
+
+The deadlock is caused because the Client_connector destructor waits for the callback to return.
+The callback on the other hand waits for the destructor to return.
+
+.Interaction diagram: Client_connector deadlocks
+[plantuml, svg, align="center"]
+....
+include::models/interaction_diagram_client_connector_deadlocks.puml[]
+....
+
+== Server_connector deadlocks
+
+When a running callback destroys the calling Server_connector a deadlock will happen, which will cause the application to be terminated.
+
+The deadlock is caused because the Server_connector destructor waits for the callback to return.
+The callback on the other hand waits for the destructor to return.
+
+.Interaction diagram: Server_connector deadlocks
+[plantuml, svg, align="center"]
+....
+include::models/interaction_diagram_server_connector_deadlocks.puml[]
+....