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/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..5bb6c5a94 100644 --- a/docs/fastddsgen/interfaces/introduction.rst +++ b/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 `_. -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 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..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 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 ` of the incoming requests. calculatorServerImpl """""""""""""""""""" diff --git a/docs/fastddsgen/rpc_server_schedule/intro.rst b/docs/fastddsgen/rpc_server_schedule/intro.rst new file mode 100644 index 000000000..01a2be16d --- /dev/null +++ b/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 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: