add the fakeshm module tuning utilities and ininitial draft of its documentation and its third-party dependencies licenses

2026-07-13 20:16:03 +02:00
parent 462db47578
commit bbf98fc1ac
14 changed files with 222 additions and 0 deletions
@@ -50,3 +50,9 @@ Handbook/dist/**/* filter=lfs diff=lfs merge=lfs -text
 # LFS: sgum-packager Linux and Windows binaries
 Packager/sgum-packager filter=lfs diff=lfs merge=lfs -text
 Packager/sgum-packager.exe filter=lfs diff=lfs merge=lfs -text
+
+# LFS: sgfakeshm-connect-client abd sgfakeshm-core-client Linux and Windows binaries
+Tuning/sgfakeshm-connect-client filter=lfs diff=lfs merge=lfs -text
+Tuning/sgfakeshm-connect-client.exe filter=lfs diff=lfs merge=lfs -text
+Tuning/sgfakeshm-core-client filter=lfs diff=lfs merge=lfs -text
+Tuning/sgfakeshm-core-client.exe filter=lfs diff=lfs merge=lfs -text
@@ -25,6 +25,7 @@ Welcom to the SenseGlove Unreal Engine Handbook!
            - [Connect to Nova gloves using Blueman Bluetooth Manager](getting-started/sensecom/bluetooth-serial/gnu-linux/blueman-bluetooth-manager.md)
            - [Connect to Nova gloves using Command-line](getting-started/sensecom/bluetooth-serial/gnu-linux/command-line.md)
        - [SenseCom on Microsoft Windows](getting-started/sensecom/bluetooth-serial/microsoft-windows.md)
+    - [FakeShm Module Tuning](getting-started/sensecom/fakeshm-tuning/README.md)
 - [Enabling XR_EXT_hand_tracking on VR Headsets](getting-started/enabling-xr-ext-hand-tracking-vr-headsets/README.md)
    - [PCVR Mode](getting-started/enabling-xr-ext-hand-tracking-vr-headsets/pcvr-mode/README.md)
    - [Standalone Mode](getting-started/enabling-xr-ext-hand-tracking-vr-headsets/standalone-mode/README.md)
@@ -25,6 +25,7 @@ This minor release introduces a major IPC overhaul, significant inter-process co
 - Added `SGBuildHacks/SGInclude_Core_DeviceTypes`.
 - Added missing `ESGBackendType::AndroidStrings` enumerator.
 - Added missing SenseGlove API Blueprint function `USGLibraryKismetLibrary::GetBackendType()`.
+- Added the [Microsoft Windows and GNU/Linux binary distribution of **SenseGlove FakeShm Module Tuning Utilities**](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal?path=/Tuning&version=GBmaster&_a=contents) to the SenseGlove Unreal Engine Plugin repository on Microsoft Azure repositories. These binaries are not part of the [official plugin release via the Fab Store](https://www.fab.com/listings/62bcdd2a-0bb1-4f34-b7b8-c5e7c9313099).

 ### Fixed

@@ -80,6 +81,7 @@ This minor release introduces a major IPC overhaul, significant inter-process co

 ### Documentation

+- Added the [SenseCom > FakeShm Module Tuning](../getting-started/sensecom/fakeshm-tuning/) documentation section.
 - Added [The c4core C++ Library Licence](../license/c4core-library.html) section.
 - Added [The c4project CMake Scripts Licence](../license/c4project-cmake-scripts.html) section.
 - Added [The Debug Break Library Licence](../license/debugbreak-library.html) section.
@@ -0,0 +1,135 @@
+# SenseGlove FakeShm Module Tuning
+
+```yaml
+# File name used for tweaking and tuning the FakeShm parameters.
+# When this file does not exist it will be generated by the SGConnectShm upon
+# initialization or reconfiguration and gets populated from the hardcoded values
+# below.
+# If it does indeed exist and file version matches the version supported by the
+# current release of the SenseGlove libraries, the parameters values in this
+# file will override the hardcoded values from the libraries.
+# If the file has invalid values, or the version number does not match, it will
+# be renamed to sgfakeshm-params.yml.YYYY-MM-DD-hh-mm-ss to
+# preserve the user's choosen values and a new file will be generated containing
+# the updated values or newly introduced parameters.
+#
+# NOTE: This file supports hot-reloading upon saving the file. Thus, you do
+# not have to close SenseCom or plugin's relying on SenseGlove libraries in
+# order to apply the changes. The changes will be picked up automatically
+# as soon as a file change is detected.
+
+# The current version of the the default tuning parameters configuration
+# file.
+#
+# Existing tuning configuration files are only loaded when their version
+# matches the version supported by the current FakeShm implementation.
+# Otherwise, the existing file is backed up with a timestamped filename
+# and a new file containing the current default parameters is generated.
+#
+# Please do not change this value if you want your changes to persist.
+Version: 1
+
+# If enabled, socket receive operations are performed in non-blocking
+# mode.
+# nng_recvmsg will return immediately if no message is available:
+#   - NNG_EAGAIN is returned instead of blocking
+# This improves responsiveness but may increase CPU usage due to
+# polling.
+# When disabled, SocketReceiveTimeout controls blocking behavior.
+SocketReceiveNonBlocking: true
+
+# Receive timeout for the NNG socket in milliseconds.
+# Controls how long nng_recvmsg blocks while waiting for a message.
+# If no message is received within this interval, the call returns
+# with a timeout, allowing the worker thread to wake up periodically
+# to:
+#   - send heartbeats
+#   - detect peer liveness
+#   - respond to shutdown requests
+# Lower values increase responsiveness but may slightly increase CPU
+# usage.
+# This only is taken into account when SocketReceiveNonBlocking is
+# disabled.
+SocketReceiveTimeout: 1
+
+# If enabled, socket send operations are performed in non-blocking
+# mode.
+# nng_sendmsg will return immediately if the message cannot be sent:
+#   - NNG_EAGAIN is returned instead of blocking
+# Useful for low-latency systems where blocking is undesirable.
+SocketSendNonBlocking: false
+
+# Send timeout for the NNG socket in milliseconds.
+# Controls how long nng_sendmsg blocks while attempting to send a
+# message.
+# If the message cannot be sent within this interval, the call returns
+# with a timeout error, allowing the system to avoid long blocking
+# stalls.
+# This only is taken into account when SocketSendNonBlocking is
+# disabled.
+SocketSendTimeout: 1
+
+# This is the minimum amount of time (milliseconds) to wait before
+# attempting to establish a connection after a previous attempt has
+# failed. This can be set on a socket, but it can also be overridden
+# on an individual dialer. The option is irrelevant for listeners.
+SocketReconnectTimeMin: 1
+
+# This is the maximum amount of time (milliseconds) to wait before
+# attempting to establish a connection after a previous attempt has
+# failed. If this is non-zero, then the time between successive
+# connection attempts will start at the value of
+# SocketReconnectTimeMin, and grow exponentially, until it reaches
+# this value. If this value is zero, then no exponential back-off
+# between connection attempts is done, and each attempt will wait the
+# time specified by SocketReconnectTimeMin. This can be set on a
+# socket, but it can also be overridden on an individual dialer. The
+# option is irrelevant for listeners.
+SocketReconnectTimeMax: 10
+
+# FakeShm transport worker retry interval in milliseconds.
+# Applied when:
+#   - no peer is connected
+#   - socket returns no data (timeout / EAGAIN)
+# Prevents busy-waiting loops and reduces CPU usage while idle.
+WorkerRetryInterval: 1
+
+# FakeShm transport heartbeat interval in milliseconds.
+# Determines how often heartbeat messages are sent to the peer to:
+#   - maintain connection activity
+#   - update last-seen timestamps
+# Lower values improve liveness detection but increase traffic
+# overhead.
+HeartbeatInterval: 1
+
+# FakeShm IPC and TCP transports liveness timeout in milliseconds.
+# Defines how long a peer can remain silent before being considered
+# dead.
+# Compared against the timestamp of the last received message.
+# If exceeded, the peer is treated as disconnected/unresponsive.
+LivenessTimeout: 5
+
+# Latency smoothing window in milliseconds.
+# Defines the time range over which latency samples are accumulated
+# to compute a rolling average (smoothed latency).
+# Larger values produce more stable results but react slower to
+# changes.
+LatencySmoothingWindow: 1000
+
+# Throughput smoothing window in milliseconds.
+# Defines the time range over which throughput snapshots are
+# accumulated to compute a rolling average (smoothed snapshots).
+# Larger values produce more stable results but react slower to
+# changes.
+ThroughputSmoothingWindow: 1000
+
+# The legacy Boost SharedMem heartbeat block size.
+SharedMemHeartbeatBlockSize: 1024
+
+# FakeShm SharedMem liveness timeout in milliseconds.
+# Defines how long a peer can remain silent before being considered
+# dead.
+# Compared against the timestamp of the last received message.
+# If exceeded, the peer is treated as disconnected/unresponsive.
+SharedMemLivenessTimeout: 50
+```
@@ -0,0 +1,30 @@
+# The Argh Frustration-free Command-line Processing Library Licence
+
+```
+Copyright (c) 2016, Adi Shavit 
+All rights reserved. 
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met: 
+
+ * Redistributions of source code must retain the above copyright notice, 
+   this list of conditions and the following disclaimer. 
+ * Redistributions in binary form must reproduce the above copyright 
+   notice, this list of conditions and the following disclaimer in the 
+   documentation and/or other materials provided with the distribution. 
+ * Neither the name of  nor the names of its contributors may be used to 
+   endorse or promote products derived from this software without specific 
+   prior written permission. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
+POSSIBILITY OF SUCH DAMAGE. 
+```
@@ -0,0 +1,25 @@
+# The FTXUI Functional Terminal (X) User Interface Library Licence
+
+```
+The MIT License
+
+Copyright (c) 2019 Arthur Sonzogni.
+
+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.
+```
@@ -6,6 +6,7 @@ The following third-party software are used and shipped with the SenseGlove Unre

 - [The SenseGlove SDK (a.k.a. SenseGlove Backend Libraries, or SenseGlove Core Libraries)](senseglove-sdk.md)
 - [SGBLE and SGBLExx Rust Dependencies](sgble-sgblexx-rust-dependencies.md)
+- [The Argh Frustration-free Command-line Processing Library](argh-command-line-processing-library.md)
 - [The Boost C++ Libraries](boost-cpp-libraries.md)
 - [The c4core C++ Library](c4core-library.md)
 - [The c4project CMake Scripts](c4project-cmake-scripts.md)
@@ -13,9 +14,12 @@ The following third-party software are used and shipped with the SenseGlove Unre
 - [The fast_float Number Parsing Library](fast-float-number-parsing-library.md)
 - [The FlatBuffers Memory Efficient Serialization Library](flatbuffers-serialization-library.md)
 - [The {fmt} Formatting Library](fmt-formatting-library.md)
+- [The FTXUI Functional Terminal (X) User Interface Library](ftxui-functional-tui-library.md)
 - [The Loguru Logging Library](loguru-logging-library.md)
 - [The nanomsg-next-generation Lightweight Brokerless Messaging Library](nng-messaging-library.md)
 - [The Rapid YAML Parsing and Emitting Library](rapidyaml-parsing-emitting-library.md)
 - [The Serial Communication Library](serial-communication-library.md)

+__NOTE__: **FTXUI** and **Argh** are only used by [the SenseGlove FakeShm Module Tuning Utilities, `sgfakeshm-connect-client` and `sgfakeshm-core-client`](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal?path=/Tuning&version=GBmaster&_a=contents) distributed as separate binaries via [the SenseGlove Unreal Engine Plugin Microsoft Azure DevOps repository](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal). Since these utilities are not part of [the official release of the SenseGlove Unreal Engine Plugin via the Fab Store](https://www.fab.com/listings/62bcdd2a-0bb1-4f34-b7b8-c5e7c9313099), their respective licensing terms won't apply to the SenseGlove SDK or the UE plugin.
+
 For more information consult their own respective open-source licenses, please.
@@ -21,6 +21,7 @@ This section covers the basics of the SenseGlove Unreal Engine Plugin:
            - [Connect to Nova gloves using Blueman Bluetooth Manager](../getting-started/sensecom/bluetooth-serial/gnu-linux/blueman-bluetooth-manager.md)
            - [Connect to Nova gloves using Command-line](../getting-started/sensecom/bluetooth-serial/gnu-linux/command-line.md)
        - [SenseCom on Microsoft Windows](../getting-started/sensecom/bluetooth-serial/microsoft-windows.md)
+    - [FakeShm Module Tuning](../getting-started/sensecom/fakeshm-tuning/)
 - [Enabling XR_EXT_hand_tracking on VR Headsets](../getting-started/enabling-xr-ext-hand-tracking-vr-headsets/)
    - [PCVR Mode](../getting-started/enabling-xr-ext-hand-tracking-vr-headsets/pcvr-mode/)
    - [Standalone Mode](../getting-started/enabling-xr-ext-hand-tracking-vr-headsets/standalone-mode/)
@@ -57,6 +57,7 @@ Deploy:
    - Handbook
    - Packager
    - README.md
+    - Tuning


 Git:
@@ -0,0 +1,5 @@
+# SenseGlove FakeShm Module Tuning Utilities
+
+The `sgfakeshm-connect-client` and `sgfakeshm-core-client` benchmarking and tuning utilities are only distributed via [the SenseGlove Unreal Engine Plugin Microsoft Azure DevOps repository](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal) and is not part of [the official release on the Fab Store](https://www.fab.com/listings/62bcdd2a-0bb1-4f34-b7b8-c5e7c9313099).
+
+Pleasee see the [relevant documentation section](../Handbook/src/getting-started/sensecom/fakeshm-tuning/README.md) and [licensing terms](../Handbook/src/license/third-party.md) for more information.