From 48c36d10bd6f9121d385fae3a0c9d956f643c07a Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Fri, 13 Jun 2025 13:38:02 +0200 Subject: [PATCH 1/5] Refs #23271. Refactor index. Signed-off-by: Miguel Company --- .../interfaces/{includes => }/exceptions.rst | 2 +- .../interfaces/{includes => }/interfaces.rst | 8 ++++---- docs/fastddsgen/interfaces/introduction.rst | 14 ++++++++++---- docs/index.rst | 2 -- 4 files changed, 15 insertions(+), 11 deletions(-) rename docs/fastddsgen/interfaces/{includes => }/exceptions.rst (99%) rename docs/fastddsgen/interfaces/{includes => }/interfaces.rst (98%) diff --git a/docs/fastddsgen/interfaces/includes/exceptions.rst b/docs/fastddsgen/interfaces/exceptions.rst similarity index 99% rename from docs/fastddsgen/interfaces/includes/exceptions.rst rename to docs/fastddsgen/interfaces/exceptions.rst index c4c953180..2f7d82cca 100644 --- a/docs/fastddsgen/interfaces/includes/exceptions.rst +++ b/docs/fastddsgen/interfaces/exceptions.rst @@ -1,7 +1,7 @@ .. _fastddsgen_interfaces_exceptions: Exceptions ----------- +========== Exceptions are user-defined structures that can be raised by members of an interface. They are declared similarly to ``struct`` types; using the ``exception`` keyword, diff --git a/docs/fastddsgen/interfaces/includes/interfaces.rst b/docs/fastddsgen/interfaces/interfaces.rst similarity index 98% rename from docs/fastddsgen/interfaces/includes/interfaces.rst rename to docs/fastddsgen/interfaces/interfaces.rst index 7437e6e0f..777b1a482 100644 --- a/docs/fastddsgen/interfaces/includes/interfaces.rst +++ b/docs/fastddsgen/interfaces/interfaces.rst @@ -1,7 +1,7 @@ .. _fastddsgen_interfaces_definition: Defining an IDL interface -------------------------- +========================= *eProsima Fast DDS-Gen* allows the generation of the code required by both the client and the server to use the *Fast DDS* Request-Reply internal API (see :ref:`request_reply_api_intro`), @@ -10,7 +10,7 @@ The following subsections will describe how to define an IDL interface for simpl and data streaming. IDL specification overview -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- The `OMG IDL specification `_ defines interfaces that client and server objects may use, for example, in the context of a *Remote Procedure Calls* communication @@ -45,7 +45,7 @@ Interfaces can also be forward declared, for example :code:`interface MyInterfac .. _fastddsgen_interfaces_data_streaming: Defining data streaming operations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------- *eProsima Fast DDS-Gen* allows to generate code for data streaming in each use case described in :ref:`rpc_data_streaming_intro`, using the ``@feed`` builtin annotation in operations: @@ -67,7 +67,7 @@ with ``@feed`` annotations input parameters, return types or both, respectively. Example -^^^^^^^ +------- The following example shows how to define an interfaces, addressing the cases described before: diff --git a/docs/fastddsgen/interfaces/introduction.rst b/docs/fastddsgen/interfaces/introduction.rst index 16c75c201..a1fbdd215 100644 --- a/docs/fastddsgen/interfaces/introduction.rst +++ b/docs/fastddsgen/interfaces/introduction.rst @@ -11,8 +11,14 @@ from an IDL file. The IDL file must contain the operation that can be called on and the parameters that can be passed to them. These operations are specified using the concept of interfaces defined in the OMG IDL `specification `_. -The next subsections serves as a guide to how to define your own IDL interface and -how to define exceptions for its operations. +The next subsections serves as a guide to how to define your own IDL interface, how to define exceptions for its operations, +and how to develop RPC Client/Server applications. -.. include:: includes/interfaces.rst -.. include:: includes/exceptions.rst + +.. toctree:: + :maxdepth: 2 + + /fastddsgen/interfaces/interfaces + /fastddsgen/interfaces/exceptions + /fastddsgen/rpc_calculator_basic_app/intro + /fastddsgen/rpc_calculator_feed_app/intro diff --git a/docs/index.rst b/docs/index.rst index c19b251ef..77d98bfff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -72,8 +72,6 @@ /fastddsgen/python_bindings/python_bindings /fastddsgen/dataTypes/dataTypes /fastddsgen/interfaces/introduction - /fastddsgen/rpc_calculator_basic_app/intro - /fastddsgen/rpc_calculator_feed_app/intro .. _index_cli: From bbffdf744e464e1cd1617c9a9bae6954ad320f33 Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Mon, 16 Jun 2025 11:37:30 +0200 Subject: [PATCH 2/5] Refs #23271. Add chapter for RPC server request scheduling. Signed-off-by: Miguel Company --- code/DDSCodeTester.cpp | 40 +++++++++++++++++++ docs/fastddsgen/interfaces/introduction.rst | 1 + docs/fastddsgen/rpc_server_schedule/intro.rst | 33 +++++++++++++++ 3 files changed, 74 insertions(+) create mode 100644 docs/fastddsgen/rpc_server_schedule/intro.rst diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 9c3e18a06..f33138730 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -8145,6 +8145,46 @@ void rpcdds_internal_api_examples() } } +void rpcdds_custom_scheduling_examples() +{ + //!--RPC_CUSTOM_SCHEDULING_EXAMPLES + // A scheduling strategy where requests are processed in the same thread where they are received. + // Should not be used in servers with feed operations. + struct DirectRequestScheduling : public eprosima::fastdds::dds::rpc::RpcServerSchedulingStrategy + { + void schedule_request( + const std::shared_ptr& request, + const std::shared_ptr& server) override + { + server->execute_request(request); + } + + void server_stopped( + const std::shared_ptr& server) override + { + static_cast(server); + } + }; + + // A scheduling strategy where each request is processed in a detached thread. + struct DetachedThreadRequestScheduling : public eprosima::fastdds::dds::rpc::RpcServerSchedulingStrategy + { + void schedule_request( + const std::shared_ptr& request, + const std::shared_ptr& server) override + { + std::thread([server, request](){server->execute_request(request);}).detach(); + } + + void server_stopped( + const std::shared_ptr& server) override + { + static_cast(server); + } + }; + //!-- +} + int main( int argc, const char** argv) diff --git a/docs/fastddsgen/interfaces/introduction.rst b/docs/fastddsgen/interfaces/introduction.rst index a1fbdd215..6aa04285a 100644 --- a/docs/fastddsgen/interfaces/introduction.rst +++ b/docs/fastddsgen/interfaces/introduction.rst @@ -22,3 +22,4 @@ and how to develop RPC Client/Server applications. /fastddsgen/interfaces/exceptions /fastddsgen/rpc_calculator_basic_app/intro /fastddsgen/rpc_calculator_feed_app/intro + /fastddsgen/rpc_server_schedule/intro diff --git a/docs/fastddsgen/rpc_server_schedule/intro.rst b/docs/fastddsgen/rpc_server_schedule/intro.rst new file mode 100644 index 000000000..eff543e21 --- /dev/null +++ b/docs/fastddsgen/rpc_server_schedule/intro.rst @@ -0,0 +1,33 @@ +.. include:: ../../03-exports/aliases-api.include +.. include:: ../../03-exports/roles.include + +.. _fastddsgen_rpc_server_schedule_intro: + +Customizing RPC Server request scheduling +========================================= + +When processing an interface inside an IDL file, *Fast DDS-Gen* generates two method overloads for the creation of a server. + +The first overload creates a server with a request scheduling based on a thread pool. +Each request will be processed in a separate thread. +The number of threads in the pool is specified in the ``thread_pool_size`` argument of the method. + +The second overload allows the user to inject a custom scheduling strategy for the created server. +This is done by creating a custom class implementing the |RpcServerSchedulingStrategy-api| interface. +A shared pointer to the custom class is then passed in the ``scheduler`` argument of the method. + +Special care must be taken when implementing a custom scheduling strategy. +Calls to |RpcServerSchedulingStrategy::schedule_request-api| will be performed from the thread executing the server's |RpcServer::run-api| method. +This means that incoming messages will not be processed until the execution of |RpcServerSchedulingStrategy::schedule_request-api| finishes. +This becomes particularly important for operations that have input feed parameters, since values for input feeds will not be processed while inside that method. + +Example +""""""" + +The following code snippet shows two examples of custom RPC server scheduling strategies: + +.. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //!--RPC_CUSTOM_SCHEDULING_EXAMPLES + :end-before: //!-- + :dedent: 4 From f66697be507a24fc0c4c48e754b83e4ceb086d89 Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Mon, 16 Jun 2025 12:59:45 +0200 Subject: [PATCH 3/5] Refs #23271. Update calculatorServer documentation. Signed-off-by: Miguel Company --- .../rpc_calculator_basic_app/includes/code_generation.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst b/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst index ea1e02432..7ea34d39d 100644 --- a/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst +++ b/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst @@ -138,11 +138,11 @@ the client sends a new request using its internal Requester and waits for the re calculatorServer """""""""""""""" -Contains the ``CalculatorServerLogic`` class, which implements the server for the calculator interface and -can be instantiated by the user calling ``create_CalculatorServer`` function. +Contains the ``CalculatorServerLogic`` class which implements the generic |RpcServer-api| interface, representing the public API of the server. +User can run or a stop a server calling |RpcServer::run-api| or |RpcServer::stop-api| methods, respectively. -``CalculatorServer`` struct represents the public API of the server. User can run or a stop a server calling -``CalculatorServer::run()`` or ``CalculatorServer::stop()`` methods, respectively. +The generated class can be instantiated by the user calling ``create_CalculatorServer`` function. +Two overloads of this funcion are created, allowing the user to :ref:`customize the scheduling <_fastddsgen_rpc_server_schedule_intro>` of the incoming requests. calculatorServerImpl """""""""""""""""""" From 61a1902a2184b1bf087f6da619a3c9c93c469f0c Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Tue, 17 Jun 2025 12:30:40 +0200 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Carlos Espinoza Curto <148376273+Carlosespicur@users.noreply.github.com> Signed-off-by: Miguel Company --- .../rpc_calculator_basic_app/includes/code_generation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst b/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst index 7ea34d39d..2c3c13e32 100644 --- a/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst +++ b/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst @@ -139,10 +139,10 @@ calculatorServer """""""""""""""" Contains the ``CalculatorServerLogic`` class which implements the generic |RpcServer-api| interface, representing the public API of the server. -User can run or a stop a server calling |RpcServer::run-api| or |RpcServer::stop-api| methods, respectively. +User can run or stop a server calling |RpcServer::run-api| or |RpcServer::stop-api| methods, respectively. The generated class can be instantiated by the user calling ``create_CalculatorServer`` function. -Two overloads of this funcion are created, allowing the user to :ref:`customize the scheduling <_fastddsgen_rpc_server_schedule_intro>` of the incoming requests. +Two overloads of this funcion are created, allowing the user to :ref:`customize the scheduling ` of the incoming requests. calculatorServerImpl """""""""""""""""""" From 486ecf7f51547cd4ffceee95f52146d0701d5cda Mon Sep 17 00:00:00 2001 From: Miguel Company Date: Tue, 17 Jun 2025 20:22:04 +0200 Subject: [PATCH 5/5] Refs #23271. Fix line lengths and spelling. Signed-off-by: Miguel Company --- docs/fastddsgen/interfaces/introduction.rst | 4 ++-- .../includes/code_generation.rst | 6 ++++-- docs/fastddsgen/rpc_server_schedule/intro.rst | 12 ++++++++---- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/fastddsgen/interfaces/introduction.rst b/docs/fastddsgen/interfaces/introduction.rst index 6aa04285a..5bb6c5a94 100644 --- a/docs/fastddsgen/interfaces/introduction.rst +++ b/docs/fastddsgen/interfaces/introduction.rst @@ -11,8 +11,8 @@ from an IDL file. The IDL file must contain the operation that can be called on and the parameters that can be passed to them. These operations are specified using the concept of interfaces defined in the OMG IDL `specification `_. -The next subsections serves as a guide to how to define your own IDL interface, how to define exceptions for its operations, -and how to develop RPC Client/Server applications. +The next subsections serves as a guide to how to define your own IDL interface, how to define exceptions for its +operations, and how to develop RPC Client/Server applications. .. toctree:: diff --git a/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst b/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst index 2c3c13e32..7a4d168ea 100644 --- a/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst +++ b/docs/fastddsgen/rpc_calculator_basic_app/includes/code_generation.rst @@ -138,11 +138,13 @@ the client sends a new request using its internal Requester and waits for the re calculatorServer """""""""""""""" -Contains the ``CalculatorServerLogic`` class which implements the generic |RpcServer-api| interface, representing the public API of the server. +Contains the ``CalculatorServerLogic`` class which implements the generic |RpcServer-api| interface, representing +the public API of the server. User can run or stop a server calling |RpcServer::run-api| or |RpcServer::stop-api| methods, respectively. The generated class can be instantiated by the user calling ``create_CalculatorServer`` function. -Two overloads of this funcion are created, allowing the user to :ref:`customize the scheduling ` of the incoming requests. +Two overloads of this function are created, allowing the user to +:ref:`customize the scheduling ` of the incoming requests. calculatorServerImpl """""""""""""""""""" diff --git a/docs/fastddsgen/rpc_server_schedule/intro.rst b/docs/fastddsgen/rpc_server_schedule/intro.rst index eff543e21..01a2be16d 100644 --- a/docs/fastddsgen/rpc_server_schedule/intro.rst +++ b/docs/fastddsgen/rpc_server_schedule/intro.rst @@ -6,7 +6,8 @@ Customizing RPC Server request scheduling ========================================= -When processing an interface inside an IDL file, *Fast DDS-Gen* generates two method overloads for the creation of a server. +When processing an interface inside an IDL file, *Fast DDS-Gen* generates two method overloads for the creation of a +server. The first overload creates a server with a request scheduling based on a thread pool. Each request will be processed in a separate thread. @@ -17,9 +18,12 @@ This is done by creating a custom class implementing the |RpcServerSchedulingStr A shared pointer to the custom class is then passed in the ``scheduler`` argument of the method. Special care must be taken when implementing a custom scheduling strategy. -Calls to |RpcServerSchedulingStrategy::schedule_request-api| will be performed from the thread executing the server's |RpcServer::run-api| method. -This means that incoming messages will not be processed until the execution of |RpcServerSchedulingStrategy::schedule_request-api| finishes. -This becomes particularly important for operations that have input feed parameters, since values for input feeds will not be processed while inside that method. +Calls to |RpcServerSchedulingStrategy::schedule_request-api| will be performed from the thread executing the server's +|RpcServer::run-api| method. +This means that incoming messages will not be processed until the execution of +|RpcServerSchedulingStrategy::schedule_request-api| finishes. +This becomes particularly important for operations that have input feed parameters, since values for input feeds will +not be processed while inside that method. Example """""""