diff --git a/score/message_passing/dependability/software_unit_design/BUILD b/score/message_passing/dependability/software_unit_design/BUILD index a22834333..a2a540fa1 100644 --- a/score/message_passing/dependability/software_unit_design/BUILD +++ b/score/message_passing/dependability/software_unit_design/BUILD @@ -13,17 +13,32 @@ load("@score_tooling//bazel/rules/rules_score:rules_score.bzl", "unit_design") +# Class diagrams are passed through directly to Sphinx (sphinxcontrib-plantuml +# renders them at doc-build time). The RST wrapper references the .puml file +# via '.. uml::' so both must be listed together in 'static'. unit_design( name = "client_connection_unit_design", + static = [ + "client_connection_class_diagram.puml", + "client_connection_design.rst", + ], visibility = ["//score/message_passing:__pkg__"], ) unit_design( name = "unix_domain_unit_design", + static = [ + "unix_domain_class_diagram.puml", + "unix_domain_design.rst", + ], visibility = ["//score/message_passing:__pkg__"], ) unit_design( name = "qnx_dispatch_unit_design", + static = [ + "qnx_dispatch_class_diagram.puml", + "qnx_dispatch_design.rst", + ], visibility = ["//score/message_passing:__pkg__"], ) diff --git a/score/message_passing/dependability/software_unit_design/client_connection_class_diagram.puml b/score/message_passing/dependability/software_unit_design/client_connection_class_diagram.puml new file mode 100644 index 000000000..92689a0f1 --- /dev/null +++ b/score/message_passing/dependability/software_unit_design/client_connection_class_diagram.puml @@ -0,0 +1,119 @@ +' ******************************************************************************* +' Copyright (c) 2026 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 +' ******************************************************************************* + +' Unit design (static view) for the Client Connection unit. +' Derived from the existing message-passing design in score/mw/com/design, +' mapped onto the new score::message_passing units. The old mw::com roles are +' shown as <> stereotypes to keep the design traceable. + +@startuml client_connection_class_diagram + +namespace score::message_passing { + + ' Old: mw::com::message_passing::SenderFactory + MessagePassingControl::GetMessagePassingSender + interface IClientFactory <> { + + Create(protocol_config : ServiceProtocolConfig, client_config : ClientConfig) : IClientConnection + } + + ' Old: mw::com::message_passing::ISender (Send) plus the client-side + ' request/result-message + callback pairing (subscribeEventResultCallbacks) + ' and the NotifyEventHandler notification callback, unified in one endpoint. + interface IClientConnection <> { + + Send(message) : expected + + SendWaitReply(message, reply) : expected + + SendWithCallback(message, ReplyCallback) : expected + + Start(StateCallback, NotifyCallback) : void + + Stop() : void + + Restart() : void + + GetState() : State + + GetStopReason() : StopReason + } + + enum State { + kStarting + kReady + kStopping + kStopped + } + + enum StopReason { + kNone + kInit + kUserRequested + kPermission + kClosedByPeer + kIoError + kShutdown + } + + ' Old: the fixed ShortMessage / MediumMessage split was dropped (premature + ' optimization); a per-service protocol now carries the max message sizes. + struct ServiceProtocolConfig <> { + + identifier + + max_send_size + + max_reply_size + + max_notify_size + } + + ' Nested as IClientFactory::ClientConfig. + struct ClientConfig { + + max_async_replies + + max_queued_sends + + fully_ordered + + truly_async + + sync_first_connect + } + + ' Old: lola::messaging::MessagePassingControl owned the senders map, the + ' send queue and the node identifier. Now a shared transport engine owns + ' the background thread and the OS-specific channels. + interface ISharedResourceEngine <> { + + TryOpenClientConnection(identifier) : fd + + SendProtocolMessage(fd, code, message) : expected + + ReceiveProtocolMessage(fd, code) : message + + RegisterPosixEndpoint(endpoint) : void + + EnqueueCommand(entry, until, callback, owner) : void + } + +} + +namespace score::message_passing::detail { + + ' The unit: encapsulates the connection state machine and the + ' (pre-allocated) asynchronous send queue. + class ClientConnection <> { + + Send(message) : expected + + SendWaitReply(message, reply) : expected + + SendWithCallback(message, ReplyCallback) : expected + + Start(StateCallback, NotifyCallback) : void + + Stop() : void + + Restart() : void + + GetState() : State + + GetStopReason() : StopReason + } + +} + +ClientConnection ..|> IClientConnection +ClientConnection o--> ISharedResourceEngine : shares transport & thread +ClientConnection ..> ServiceProtocolConfig : bounded by +ClientConnection ..> ClientConfig : configured by +IClientConnection ..> State : reports +IClientConnection ..> StopReason : reports +IClientFactory ..> IClientConnection : creates +IClientFactory *-- ClientConfig : nested config +IClientFactory ..> ServiceProtocolConfig : uses + +note "Blend of mw/com: Send == old ISender::Send; old request + Result-message + callback becomes SendWaitReply / SendWithCallback; old per-ElementFqId notifications become NotifyCallback." as N1 + +@enduml diff --git a/score/message_passing/dependability/software_unit_design/qnx_dispatch_class_diagram.puml b/score/message_passing/dependability/software_unit_design/qnx_dispatch_class_diagram.puml new file mode 100644 index 000000000..f678e0d57 --- /dev/null +++ b/score/message_passing/dependability/software_unit_design/qnx_dispatch_class_diagram.puml @@ -0,0 +1,130 @@ +' ******************************************************************************* +' Copyright (c) 2026 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 +' ******************************************************************************* + +' Unit design (static view) for the QNX Dispatch dispatch/transport unit. +' Derived from the existing message-passing design in score/mw/com/design, +' mapped onto the new score::message_passing units. The old mw::com roles are +' shown as <> stereotypes to keep the design traceable. + +@startuml qnx_dispatch_class_diagram + +namespace score::message_passing { + + interface IClientFactory <> { + + Create(protocol_config, client_config) : IClientConnection + } + + ' Old: mw::com::message_passing::ReceiverFactory + interface IServerFactory <> { + + Create(protocol_config, server_config) : IServer + } + + ' Old: mw::com::message_passing::IReceiver (StartListening + Register handlers). + interface IServer <> { + + StartListening(ConnectCallback, DisconnectCallback, sent : MessageCallback, sentWithReply : MessageCallback) : expected + + StopListening() : void + } + + ' Old: the server-side message dispatch performed inside MessagePassingFacade. + interface IServerConnection <> { + + GetClientIdentity() : ClientIdentity + + GetUserData() : UserData + + Reply(message) : expected + + Notify(message) : expected + + RequestDisconnect() : void + } + + ' Old: the user-provided handlers the facade dispatched to. + interface IConnectionHandler <> { + + OnMessageSent(connection, message) : expected + + OnMessageSentWithReply(connection, message) : expected + + OnDisconnect(connection) : void + } + + interface ISharedResourceEngine <> { + + TryOpenClientConnection(identifier) : fd + + SendProtocolMessage(fd, code, message) : expected + + ReceiveProtocolMessage(fd, code) : message + + RegisterPosixEndpoint(endpoint) : void + } + + ' Old: the OS-specific ISender/IReceiver implementation ("OS specific IPC, + ' QNX pulse"). Realized here by native QNX messaging via a resource manager + ' and a single shared dispatch loop (ASIL-qualified transport). + class QnxDispatchEngine <> { + + GetOsResources() : OsResources& + } + + ' Resource-manager base classes hosted by the engine and reused by the + ' server and its connections (native QNX dispatch framework). + class ResourceManagerServer <> { + + Start(path) : expected + + Stop() : void + } + + class ResourceManagerConnection <> { + + GetServer() : ResourceManagerServer& + } + + class QnxDispatchClientFactory <> { + + Create(protocol_config, client_config) : IClientConnection + + GetEngine() : QnxDispatchEngine + } + + class QnxDispatchServerFactory <> { + + Create(protocol_config, server_config) : IServer + + GetEngine() : QnxDispatchEngine + } + +} + +namespace score::message_passing::detail { + + class QnxDispatchServer <> { + + StartListening(ConnectCallback, DisconnectCallback, sent, sentWithReply) : expected + + StopListening() : void + } + + ' Nested class of QnxDispatchServer; one endpoint per accepted client; + ' dispatches incoming messages to the server callbacks or to the user + ' IConnectionHandler. + class ServerConnection <> { + + GetClientIdentity() : ClientIdentity + + GetUserData() : UserData + + Reply(message) : expected + + Notify(message) : expected + + RequestDisconnect() : void + } + +} + +QnxDispatchEngine ..|> ISharedResourceEngine +QnxDispatchClientFactory ..|> IClientFactory +QnxDispatchServerFactory ..|> IServerFactory +QnxDispatchServer ..|> IServer +QnxDispatchServer --|> ResourceManagerServer +ServerConnection ..|> IServerConnection +ServerConnection --|> ResourceManagerConnection + +QnxDispatchClientFactory o--> QnxDispatchEngine : shared transport +QnxDispatchServerFactory o--> QnxDispatchEngine : shared transport +QnxDispatchEngine ..> ResourceManagerServer : hosts +QnxDispatchEngine ..> ResourceManagerConnection : hosts +ResourceManagerConnection --> ResourceManagerServer : belongs to +QnxDispatchServerFactory ..> QnxDispatchServer : creates +QnxDispatchServer *--> ServerConnection : owns per client +ServerConnection ..> IConnectionHandler : dispatches to + +note "Blend of mw/com: old ReceiverFactory/IReceiver + OS-specific ISender (QNX pulse) become a native QNX messaging engine shared by both factories; the facade message dispatch becomes ServerConnection + IConnectionHandler." as N1 + +@enduml diff --git a/score/message_passing/dependability/software_unit_design/unix_domain_class_diagram.puml b/score/message_passing/dependability/software_unit_design/unix_domain_class_diagram.puml new file mode 100644 index 000000000..ace6a64d2 --- /dev/null +++ b/score/message_passing/dependability/software_unit_design/unix_domain_class_diagram.puml @@ -0,0 +1,116 @@ +' ******************************************************************************* +' Copyright (c) 2026 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 +' ******************************************************************************* + +' Unit design (static view) for the Unix Domain dispatch/transport unit. +' Derived from the existing message-passing design in score/mw/com/design, +' mapped onto the new score::message_passing units. The old mw::com roles are +' shown as <> stereotypes to keep the design traceable. + +@startuml unix_domain_class_diagram + +namespace score::message_passing { + + interface IClientFactory <> { + + Create(protocol_config, client_config) : IClientConnection + } + + ' Old: mw::com::message_passing::ReceiverFactory + interface IServerFactory <> { + + Create(protocol_config, server_config) : IServer + } + + ' Old: mw::com::message_passing::IReceiver (StartListening + Register handlers). + ' The per-message handler registration is now expressed as typed callbacks. + interface IServer <> { + + StartListening(ConnectCallback, DisconnectCallback, sent : MessageCallback, sentWithReply : MessageCallback) : expected + + StopListening() : void + } + + ' Old: the server-side message dispatch performed inside MessagePassingFacade. + interface IServerConnection <> { + + GetClientIdentity() : ClientIdentity + + GetUserData() : UserData + + Reply(message) : expected + + Notify(message) : expected + + RequestDisconnect() : void + } + + ' Old: the user-provided handlers the facade dispatched to. + interface IConnectionHandler <> { + + OnMessageSent(connection, message) : expected + + OnMessageSentWithReply(connection, message) : expected + + OnDisconnect(connection) : void + } + + interface ISharedResourceEngine <> { + + TryOpenClientConnection(identifier) : fd + + SendProtocolMessage(fd, code, message) : expected + + ReceiveProtocolMessage(fd, code) : message + + RegisterPosixEndpoint(endpoint) : void + } + + ' Old: the OS-specific ISender/IReceiver implementation ("OS specific IPC, + ' Posix MQ"). Replaced here by Unix Domain Sockets (SOCK_SEQPACKET) and a + ' single shared poll() loop serving all connections. + class UnixDomainEngine <> { + + GetOsResources() : OsResources& + } + + class UnixDomainClientFactory <> { + + Create(protocol_config, client_config) : IClientConnection + + GetEngine() : UnixDomainEngine + } + + class UnixDomainServerFactory <> { + + Create(protocol_config, server_config) : IServer + + GetEngine() : UnixDomainEngine + } + +} + +namespace score::message_passing::detail { + + class UnixDomainServer <> { + + StartListening(ConnectCallback, DisconnectCallback, sent, sentWithReply) : expected + + StopListening() : void + } + + ' Nested class of UnixDomainServer; one endpoint per accepted client; + ' dispatches incoming messages to the server callbacks or to the user + ' IConnectionHandler. + class ServerConnection <> { + + GetClientIdentity() : ClientIdentity + + GetUserData() : UserData + + Reply(message) : expected + + Notify(message) : expected + + RequestDisconnect() : void + } + +} + +UnixDomainEngine ..|> ISharedResourceEngine +UnixDomainClientFactory ..|> IClientFactory +UnixDomainServerFactory ..|> IServerFactory +UnixDomainServer ..|> IServer +ServerConnection ..|> IServerConnection + +UnixDomainClientFactory o--> UnixDomainEngine : shared transport +UnixDomainServerFactory o--> UnixDomainEngine : shared transport +UnixDomainServer o--> UnixDomainEngine : shared transport +UnixDomainServerFactory ..> UnixDomainServer : creates +UnixDomainServer *--> ServerConnection : owns per client +ServerConnection ..> IConnectionHandler : dispatches to + +note "Blend of mw/com: old ReceiverFactory/IReceiver + OS-specific ISender (Posix MQ) become a Unix Domain Socket engine shared by both factories; the facade message dispatch becomes ServerConnection + IConnectionHandler." as N1 + +@enduml