[23271] Add documentation for custom request scheduling

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<eprosima::fastdds::dds::rpc::RpcRequest>& request,
+                const std::shared_ptr<eprosima::fastdds::dds::rpc::RpcServer>& server) override
+        {
+            server->execute_request(request);
+        }
+
+        void server_stopped(
+                const std::shared_ptr<eprosima::fastdds::dds::rpc::RpcServer>& server) override
+        {
+            static_cast<void>(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<eprosima::fastdds::dds::rpc::RpcRequest>& request,
+                const std::shared_ptr<eprosima::fastdds::dds::rpc::RpcServer>& server) override
+        {
+            std::thread([server, request](){server->execute_request(request);}).detach();
+        }
+
+        void server_stopped(
+                const std::shared_ptr<eprosima::fastdds::dds::rpc::RpcServer>& server) override
+        {
+            static_cast<void>(server);
+        }
+    };
+    //!--
+}
+
 int main(
         int argc,
         const char** argv)

docs/fastddsgen/interfaces/includes/exceptions.rst → 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,

docs/fastddsgen/interfaces/includes/interfaces.rst → 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 <https://www.omg.org/spec/IDL/4.2/PDF>`_ 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:
 

docs/fastddsgen/interfaces/introduction.rst

@@ -11,8 +11,15 @@ 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 <https://www.omg.org/spec/IDL/4.2/PDF>`_.
 
-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
+   /fastddsgen/rpc_server_schedule/intro

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 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 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 function are created, allowing the user to
+:ref:`customize the scheduling <fastddsgen_rpc_server_schedule_intro>` of the incoming requests.
 
 calculatorServerImpl
 """"""""""""""""""""

docs/fastddsgen/rpc_server_schedule/intro.rst

@@ -0,0 +1,37 @@
+.. 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

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: