Repository navigation
RDKDEV-1788: Add rtremote Documentation - #14
Open
gourivarma3 wants to merge 1 commit into
Open
gourivarma3 wants to merge 1 commit into
gourivarma3 wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Several documented protocols, resolver capabilities, lifecycle events, and configuration behaviors conflict with the implementation.
20 open findings
What changed in this PR
Adds comprehensive rtRemote component documentation covering architecture, runtime behavior, configuration, and build options.
Changes:
- Documents architecture, threading, lifecycle, and IPC flows.
- Catalogs internal modules and protocol messages.
- Describes runtime and build-time configuration.
| File | Description |
|---|---|
docs/README.md |
Adds component-level technical documentation. |
🧠 Review effort: Balanced
Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.
|
|
||
| rtRemote is a library and protocol for object-oriented inter-process communication (IPC) within the RDK middleware stack. It is built on the rt object model, which employs a dynamically typed value system. rtRemote enables any process to expose rt objects under a named identifier, and allows other processes — on the same host or across a network — to locate and interact with those objects through a transparent proxy interface. All interactions, including property reads, property writes, and method invocations, are carried out over sockets using a JSON-encoded message protocol. | ||
|
|
||
| As a middleware IPC component, rtRemote provides a transport-neutral communication layer that decouples object providers from object consumers. An application registers an object under a logical name; a client process calls a locate API to receive a proxy, and subsequently drives the remote object as if it were local. The resolver subsystem abstracts how named objects are discovered, supporting multicast UDP, unicast UDP via a name service daemon, and file-based resolution. |
| - **Property Get/Set**: Once a proxy is obtained, clients read or write named properties on the remote object using standard `Get()` and `Set()` calls; rtRemote encodes and transmits the operations as JSON messages. | ||
| - **Method Invocation**: Clients invoke methods on remote objects through the proxy interface; arguments and return values are serialized using the rtValue type system and conveyed over the established stream. | ||
| - **Pluggable Resolver Backends**: Object discovery is handled by an interchangeable resolver selected at runtime: multicast UDP (default), unicast UDP with a name service daemon, or a JSON file on disk. | ||
| - **Keep-Alive Management**: The stream layer detects inactivity and sends keep-alive messages to maintain sessions, reporting stream closure to registered state-change handlers. |
| - **Method Invocation**: Clients invoke methods on remote objects through the proxy interface; arguments and return values are serialized using the rtValue type system and conveyed over the established stream. | ||
| - **Pluggable Resolver Backends**: Object discovery is handled by an interchangeable resolver selected at runtime: multicast UDP (default), unicast UDP with a name service daemon, or a JSON file on disk. | ||
| - **Keep-Alive Management**: The stream layer detects inactivity and sends keep-alive messages to maintain sessions, reporting stream closure to registered state-change handlers. | ||
| - **Async Request Handling**: Outgoing requests return an `rtRemoteAsyncHandle` that callers can wait on, with configurable per-request timeouts and correlation-key-based response matching. |
|
|
||
| The stream I/O layer separates socket lifecycle (`rtRemoteStream`) from multiplexing (`rtRemoteStreamSelector`). Each stream owns a single file descriptor and delegates activity notifications to a callback handler. The stream selector runs a `select()`-based polling loop across all registered streams, routing readable data to the appropriate stream and triggering inactivity callbacks for keep-alive purposes. | ||
|
|
||
| The resolver layer is abstracted behind `rtRemoteIResolver`. The factory (`rtRemoteFactory`) instantiates the concrete resolver at environment startup based on the `rt.rpc.resolver.type` configuration parameter. The multicast resolver broadcasts UDP search messages and listens for locate responses; the unicast resolver connects to a dedicated name service daemon (`rtresolvd`); the file resolver reads and writes a shared JSON file on disk. |
|
|
||
| The resolver layer is abstracted behind `rtRemoteIResolver`. The factory (`rtRemoteFactory`) instantiates the concrete resolver at environment startup based on the `rt.rpc.resolver.type` configuration parameter. The multicast resolver broadcasts UDP search messages and listens for locate responses; the unicast resolver connects to a dedicated name service daemon (`rtresolvd`); the file resolver reads and writes a shared JSON file on disk. | ||
|
|
||
| Serialization of all rt-typed values is handled exclusively by `rtRemoteValueReader` and `rtRemoteValueWriter`, which convert between `rtValue` instances and JSON using the RapidJSON library. All on-wire messages carry a UUID correlation key so that responses can be matched to their originating requests even when multiple in-flight requests share the same stream. |
|
|
||
| ### Events Published | ||
|
|
||
| All inter-process communication uses the rtRemote protocol messages defined in the table below. |
| | `rt.rpc.server.unix_socket_template` | string | `/tmp/rt_remote_soc` | Path prefix for Unix-domain socket files. The server appends hostname and PID. | | ||
| | `rt.rpc.server.listen_interface` | string | `lo` (Linux) | Network interface for the RPC server to bind on when using inet sockets. | | ||
| | `rt.rpc.server.use_dispatch_thread` | bool | `false` | When `true`, spawns four worker threads for processing the work-item queue. When `false`, the caller's thread processes work items inline. | | ||
| | `rt.rpc.stream.socket_buffer_size` | int32 | `1048576` | Socket receive buffer size in bytes allocated per stream. | |
|
|
||
| Configuration is applied once at environment initialization. To use an alternate configuration, pass a custom file path to `rtEnvironmentFromFile()` before calling `rtRemoteInit()`. | ||
|
|
||
| ```bash |
| | -------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `BUILD_RTREMOTE_SHARED_LIB` | `ON` | Builds `librtRemote.so`. This is the primary deliverable consumed by other middleware components. | | ||
| | `BUILD_RTREMOTE_STATIC_LIB` | `ON` | Builds `librtRemote_s.a` for use in static-linked configurations. | | ||
| | `ENABLE_RTREMOTE_DEBUG` | `OFF` | Defines `RT_RPC_DEBUG` and `RT_DEBUG`; sets `-g -O0 -fno-inline`. Enables verbose protocol tracing. | |
| | `-O3` optimization | Yocto recipe | The recipe removes `-O1`, `-O2`, and `-Os` from `SELECTED_OPTIMIZATION` and substitutes `-O3` for all compilation units. | | ||
| | `-Wno-deprecated-declarations -Wno-maybe-uninitialized -Wno-address` | Yocto recipe | Warning suppression flags appended to `SELECTED_OPTIMIZATION` to silence deprecation, conditional-initialization, and address warnings across all compilation units. | | ||
| | `-fno-delete-null-pointer-checks` | Yocto recipe | Applied to both C and C++ compilation via `TARGET_CFLAGS` and `TARGET_CXXFLAGS` to prevent the compiler from eliminating null pointer guard checks. | | ||
| | `-Wl,--warn-unresolved-symbols` | Yocto recipe | Linker warning flag appended to `TARGET_CXXFLAGS`. Causes the linker to emit warnings for unresolved symbols rather than failing silently. | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
RDKDEV-1788
Reason for Change: To add Component Documentation for rtremote.
Fix: Added the README documentation
Test Procedure: None
I have read the CLA Document and I hereby sign the CLA
Signed-off-by: gourivarma3 gouri_varma@comcast.com