From e84404a9d140e88b04eeefd8bcc87ad39dc2a9f9 Mon Sep 17 00:00:00 2001 From: kadimitra Date: Sun, 16 Jun 2024 18:36:01 +0200 Subject: [PATCH] Add components documentation --- docs/sphinx/api/public_distributed_api.rst | 68 ++++++- docs/sphinx/examples/accumulator.rst | 171 ++++++++++++++++-- ...ching_and_configuring_hpx_applications.rst | 4 +- examples/accumulators/accumulator.hpp | 6 +- .../server/template_accumulator.hpp | 7 + .../server/template_function_accumulator.hpp | 8 + .../template_function_accumulator.cpp | 2 + .../component_commandline_base.hpp | 4 + .../component_factory_base.hpp | 4 + .../include/hpx/actions_base/basic_action.hpp | 2 + .../hpx/actions_base/component_action.hpp | 2 + .../include/hpx/components/client.hpp | 9 + .../include/hpx/components/client_base.hpp | 11 ++ .../components_base/component_commandline.hpp | 13 ++ .../component_startup_shutdown.hpp | 13 ++ .../components_base/components_base_fwd.hpp | 11 ++ .../runtime_components/component_factory.hpp | 2 + .../include/hpx/runtime_components/new.hpp | 12 +- 18 files changed, 320 insertions(+), 29 deletions(-) diff --git a/docs/sphinx/api/public_distributed_api.rst b/docs/sphinx/api/public_distributed_api.rst index 4cfb1b931df6..ac245d5afce3 100644 --- a/docs/sphinx/api/public_distributed_api.rst +++ b/docs/sphinx/api/public_distributed_api.rst @@ -181,7 +181,7 @@ Member functions .. _public_distr_api_header_async: ``hpx/async.hpp`` -=================== +================= The header :hpx-header:`libs/full/async_distributed/include,hpx/async.hpp` includes distributed implementations of :cpp:func:`hpx::async`, @@ -204,3 +204,69 @@ Functions +-------------------------------------------------------+ | :ref:`modules_hpx/async_distributed/dataflow.hpp_api` | +-------------------------------------------------------+ + +.. _public_distr_api_header_components: + +``hpx/components.hpp`` +====================== + +The header :hpx-header:`libs/full/include/include,hpx/include/components.hpp` +includes the components implementation. A component in `hpx` is a C++ class +which can be created remotely and for which its member functions can be invoked +remotely as well. More information about how components can be defined, +created, and used can be found in :ref:`components`. :ref:`examples_accumulator` +includes examples on the accumulator, template accumulator and template function +accumulator. + +Macros +------ + +.. table:: `hpx` macros of header ``hpx/components.hpp`` + + +----------------------------------------------+ + | Macro | + +==============================================+ + | :c:macro:`HPX_DEFINE_COMPONENT_ACTION` | + +----------------------------------------------+ + | :c:macro:`HPX_REGISTER_ACTION_DECLARATION` | + +----------------------------------------------+ + | :c:macro:`HPX_REGISTER_ACTION` | + +----------------------------------------------+ + | :c:macro:`HPX_REGISTER_COMMANDLINE_MODULE` | + +----------------------------------------------+ + | :c:macro:`HPX_REGISTER_COMPONENT` | + +----------------------------------------------+ + | :c:macro:`HPX_REGISTER_COMPONENT_MODULE` | + +----------------------------------------------+ + | :c:macro:`HPX_REGISTER_STARTUP_MODULE` | + +----------------------------------------------+ + +Classes +------- + +.. table:: `hpx` classes of header ``hpx/components.hpp`` + + +----------------------------------------------------------+ + | Class | + +==========================================================+ + | :cpp:class:`hpx::components::client` | + +----------------------------------------------------------+ + | :cpp:class:`hpx::components::client_base` | + +----------------------------------------------------------+ + | :cpp:class:`hpx::components::component` | + +----------------------------------------------------------+ + | :cpp:class:`hpx::components::component_base` | + +----------------------------------------------------------+ + | :cpp:class:`hpx::components::component_commandline_base` | + +----------------------------------------------------------+ + +Functions +--------- + +.. table:: `hpx` functions of header ``hpx/components.hpp`` + + +----------------------------------------------------------+ + | Function | + +==========================================================+ + | :cpp:func:`hpx::new_` | + +----------------------------------------------------------+ diff --git a/docs/sphinx/examples/accumulator.rst b/docs/sphinx/examples/accumulator.rst index 01b5ab10e5f9..55de51be6db2 100644 --- a/docs/sphinx/examples/accumulator.rst +++ b/docs/sphinx/examples/accumulator.rst @@ -13,9 +13,12 @@ Components and actions ====================== -The accumulator example demonstrates the use of components. Components are C++ +The accumulator examples demonstrate the use of components. Components are C++ classes that expose methods as a type of |hpx| action. These actions are called -component actions. +component actions. There are three examples: +- accumulator +- template accumulator +- template function accumulator Components are globally named, meaning that a component action can be called remotely (e.g., from another machine). There are two accumulator examples in @@ -31,18 +34,21 @@ Component actions, however, do not target machines. Instead, they target component instances. The instance may live on the machine that we've invoked the component action from, or it may live on another machine. -The component in this example exposes three different functions: +The components in these examples expose three different functions: * ``reset()`` - Resets the accumulator value to 0. * ``add(arg)`` - Adds ``arg`` to the accumulators value. * ``query()`` - Queries the value of the accumulator. -This example creates an instance of the accumulator, and then allows the user to -enter commands at a prompt, which subsequently invoke actions on the accumulator -instance. +These examples create an instance of the (template or template function) accumulator, +and then allow the user to enter commands at a prompt, which subsequently invoke actions +on the accumulator instance. + +Accumulator +=========== Setup -===== +----- The source code for this example can be found here: :download:`accumulator_client.cpp @@ -82,7 +88,7 @@ wait for input. An example session is given below: > quit Walkthrough -=========== +----------- Now, let's take a look at the source code of the accumulator example. This example consists of two parts: an |hpx| component library (a library that @@ -105,10 +111,10 @@ names of the two classes in accumulator are: * ``examples::accumulator`` (client class) The server class ----------------- +^^^^^^^^^^^^^^^^ -The following code is from: :download:`accumulator.hpp -<../../examples/accumulators/server/accumulator.hpp>`. +The following code is from +:hpx-header:`examples/accumulators,server/accumulator.hpp`. All |hpx| component server classes must inherit publicly from the |hpx| component base class: :cpp:class:`hpx::components::component_base` @@ -173,23 +179,22 @@ action type registration code: The code above must be placed in the global namespace. The rest of the registration code is in -:download:`accumulator.cpp <../../examples/accumulators/accumulator.cpp>` +:hpx-header:`examples/accumulators,accumulator.cpp` .. literalinclude:: ../../examples/accumulators/accumulator.cpp :language: c++ :start-after: //[accumulator_registration_definitions :end-before: //] - .. note:: The code above must be placed in the global namespace. The client class ----------------- +^^^^^^^^^^^^^^^^ -The following code is from :download:`accumulator.hpp -<../../examples/accumulators/accumulator.hpp>`. +The following code is from +:hpx-header:`examples/accumulators,accumulator.hpp` The client class is the primary interface to a component instance. Client classes are used to create components:: @@ -242,8 +247,9 @@ There are a few different ways of invoking actions: :end-before: //] * **Synchronous**: To invoke an action in a fully synchronous manner, we can - simply call :cpp:func:`hpx::async`\ ``().get()`` (i.e., create a future and - immediately wait on it to be ready). Here's an example from the accumulator + simply call :cpp:func:`hpx::sync` which is semantically equivalent to + :cpp:func:`hpx::async`\ ``().get()`` (i.e., create a future and immediately + wait on it to be ready). Here's an example from the accumulator client class: .. literalinclude:: ../../examples/accumulators/accumulator.hpp @@ -259,3 +265,132 @@ accumulator instance. in |hpx|. This type specifies the target of an action. This is the type that is returned by :cpp:func:`hpx::find_here` in which case it represents the :term:`locality` the code is running on. + + +Template accumulator +==================== + +Walkthrough +----------- + +The server class +^^^^^^^^^^^^^^^^ + +The following code is from +:hpx-header:`examples/accumulators,server/template_accumulator.hpp`. + +Similarly to the accumulator example, the component server class +inherits publicly from :cpp:class:`hpx::components::component_base` and from +:cpp:class:`hpx::components::locking_hook` ensuring thread-safe method invocations. + +.. literalinclude:: ../../examples/accumulators/server/template_accumulator.hpp + :language: c++ + :start-after: //[template_accumulator_server_inherit + :end-before: //] + +The body of the template accumulator class remains mainly the same as the accumulator with +the difference that it uses templates in the data types. + +.. literalinclude:: ../../examples/accumulators/server/template_accumulator.hpp + :language: c++ + :start-after: //[template_accumulator_server_body_class + :end-before: //] + +The last piece of code in the server class header is the declaration of the +action type registration code. `REGISTER_TEMPLATE_ACCUMULATOR_DECLARATION(type)` declares +actions for the specified type, while `REGISTER_TEMPLATE_ACCUMULATOR(type)` registers the +actions and the component for the specified type, using macros to handle boilerplate code. + +.. literalinclude:: ../../examples/accumulators/server/template_accumulator.hpp + :language: c++ + :start-after: //[template_accumulator_registration_declarations + :end-before: //] + +.. note:: + + The code above must be placed in the global namespace. + +Finally, `HPX_REGISTER_COMPONENT_MODULE()` in file +:hpx-header:`examples/accumulators,server/template_accumulator.cpp` +adds the factory registration functionality. + +The client class +^^^^^^^^^^^^^^^^ + +The client class of the template accumulator can be found in +:hpx-header:`examples/accumulators,template_accumulator.hpp` and is very similar to +the client class of the accumulator with the only difference that it uses templates +and hence can work with different types. + +Template function accumulator +============================= + +Walkthrough +----------- + +The server class +^^^^^^^^^^^^^^^^ + +The following code is from +:hpx-header:`examples/accumulators,server/template_function_accumulator.hpp`. + +The component server class inherits publicly from :cpp:class:`hpx::components::component_base`. + +.. literalinclude:: ../../examples/accumulators/server/template_function_accumulator.hpp + :language: c++ + :start-after: //[template_func_accumulator_server_inherit + :end-before: //] + +`typedef hpx::spinlock mutex_type` defines a `mutex_type` as `hpx::spinlock` for thread safety, +while the code that follows exposes the functionality of this component. + +.. literalinclude:: ../../examples/accumulators/server/template_function_accumulator.hpp + :language: c++ + :start-after: //[template_func_accumulator_server_exposed_func + :end-before: //] + + +- `reset()`: Resets the accumulator value to `0` in a thread-safe manner using + `std::lock_guard`. +- `add()`: Adds a value to the accumulator, allowing any type `T` that can be cast to double. +- `query()`: Returns the current value of the accumulator in a thread-safe manner. + +To define the actions for `reset()` and `query()` we can use the macro `HPX_DEFINE_COMPONENT_ACTION`. +However, actions with template arguments require special type definitions. Therefore, we use +`make_action()` to define `add()`. + +.. literalinclude:: ../../examples/accumulators/server/template_function_accumulator.hpp + :language: c++ + :start-after: //[template_func_accumulator_server_actions + :end-before: //] + +The last piece of code in the server class header is the action registration: + +.. literalinclude:: ../../examples/accumulators/server/template_function_accumulator.hpp + :language: c++ + :start-after: //[template_func_accumulator_registration_declarations + :end-before: //] + +.. note:: + + The code above must be placed in the global namespace. + +The rest of the registration code is in +:hpx-header:`examples/accumulators,accumulator.cpp` + +.. literalinclude:: ../../examples/accumulators/template_function_accumulator.cpp + :language: c++ + :start-after: //[template_func_accumulator_registration_definitions + :end-before: //] + +.. note:: + + The code above must be placed in the global namespace. + +The client class +^^^^^^^^^^^^^^^^ + +The client class of the template accumulator can be found in +:hpx-header:`examples/accumulators,template_function_accumulator.hpp` and is very similar +to the client class of the accumulator with the only difference that it uses templates +and hence can work with different types. diff --git a/docs/sphinx/manual/launching_and_configuring_hpx_applications.rst b/docs/sphinx/manual/launching_and_configuring_hpx_applications.rst index dd22b74cbd94..5ee086ffafab 100644 --- a/docs/sphinx/manual/launching_and_configuring_hpx_applications.rst +++ b/docs/sphinx/manual/launching_and_configuring_hpx_applications.rst @@ -158,8 +158,8 @@ The ``system`` configuration section * This is initialized to the base directory the current executable has been loaded from. -The `|hpx| configuration section -................................. +The |hpx| configuration section +............................... .. code-block:: ini diff --git a/examples/accumulators/accumulator.hpp b/examples/accumulators/accumulator.hpp index 8b1571fcb949..cb4f4067f19f 100644 --- a/examples/accumulators/accumulator.hpp +++ b/examples/accumulators/accumulator.hpp @@ -58,7 +58,7 @@ namespace examples { HPX_ASSERT(this->get_id()); typedef server::accumulator::reset_action action_type; - hpx::post(this->get_id()); + hpx::post(action_type(), this->get_id()); } //] @@ -84,7 +84,7 @@ namespace examples { HPX_ASSERT(this->get_id()); typedef server::accumulator::add_action action_type; - hpx::post(this->get_id(), arg); + hpx::post(action_type(), this->get_id(), arg); } /// Add \p arg to the accumulator's value. @@ -114,7 +114,7 @@ namespace examples { HPX_ASSERT(this->get_id()); typedef server::accumulator::query_action action_type; - return hpx::async(hpx::launch::async, this->get_id()); + return hpx::async(action_type(), this->get_id()); } //] diff --git a/examples/accumulators/server/template_accumulator.hpp b/examples/accumulators/server/template_accumulator.hpp index b54d92965abc..781544882110 100644 --- a/examples/accumulators/server/template_accumulator.hpp +++ b/examples/accumulators/server/template_accumulator.hpp @@ -41,12 +41,15 @@ namespace examples { namespace server { /// a simple component is created. /// /// This component exposes 3 different actions: reset, add and query. + //[template_accumulator_server_inherit template class template_accumulator : public hpx::components::locking_hook< hpx::components::component_base>> + //] { public: + //[template_accumulator_server_body_class typedef T argument_type; template_accumulator() @@ -85,12 +88,15 @@ namespace examples { namespace server { HPX_DEFINE_COMPONENT_ACTION(template_accumulator, reset) HPX_DEFINE_COMPONENT_ACTION(template_accumulator, add) HPX_DEFINE_COMPONENT_ACTION(template_accumulator, query) + //] private: argument_type value_; }; }} // namespace examples::server +//[template_accumulator_registration_declarations + #define REGISTER_TEMPLATE_ACCUMULATOR_DECLARATION(type) \ HPX_REGISTER_ACTION_DECLARATION( \ examples::server::template_accumulator::reset_action, \ @@ -123,5 +129,6 @@ namespace examples { namespace server { HPX_PP_CAT(__template_accumulator_, type); \ HPX_REGISTER_COMPONENT(HPX_PP_CAT(__template_accumulator_, type)) \ /**/ +//] #endif diff --git a/examples/accumulators/server/template_function_accumulator.hpp b/examples/accumulators/server/template_function_accumulator.hpp index 795260d56c7d..bff0169c5733 100644 --- a/examples/accumulators/server/template_function_accumulator.hpp +++ b/examples/accumulators/server/template_function_accumulator.hpp @@ -36,8 +36,10 @@ namespace examples { namespace server { /// component usually does not require AGAS requests. /// /// This component exposes 3 different actions: reset, add and query. + //[template_func_accumulator_server_inherit class template_function_accumulator : public hpx::components::component_base + //] { private: typedef hpx::spinlock mutex_type; @@ -48,6 +50,7 @@ namespace examples { namespace server { { } + //[template_func_accumulator_server_exposed_func /////////////////////////////////////////////////////////////////////// // Exposed functionality of this component. @@ -75,7 +78,9 @@ namespace examples { namespace server { std::lock_guard l(mtx_); return value_; } + //] + //[template_func_accumulator_server_actions /////////////////////////////////////////////////////////////////////// // Each of the exposed functions needs to be encapsulated into an // action type, generating all required boilerplate code for threads, @@ -95,6 +100,7 @@ namespace examples { namespace server { add_action>::type { }; + //] private: mutable mutex_type mtx_; @@ -102,6 +108,7 @@ namespace examples { namespace server { }; }} // namespace examples::server +//[template_func_accumulator_registration_declarations HPX_REGISTER_ACTION_DECLARATION( examples::server::template_function_accumulator::reset_action, managed_accumulator_reset_action) @@ -109,5 +116,6 @@ HPX_REGISTER_ACTION_DECLARATION( HPX_REGISTER_ACTION_DECLARATION( examples::server::template_function_accumulator::query_action, managed_accumulator_query_action) +//] #endif diff --git a/examples/accumulators/template_function_accumulator.cpp b/examples/accumulators/template_function_accumulator.cpp index dcd6f03b93b9..f6f32ecbb445 100644 --- a/examples/accumulators/template_function_accumulator.cpp +++ b/examples/accumulators/template_function_accumulator.cpp @@ -13,6 +13,7 @@ #include "server/template_function_accumulator.hpp" +//[template_func_accumulator_registration_definitions /////////////////////////////////////////////////////////////////////////////// // Add factory registration functionality. HPX_REGISTER_COMPONENT_MODULE() @@ -30,5 +31,6 @@ HPX_REGISTER_ACTION(accumulator_type::wrapped_type::reset_action, managed_accumulator_reset_action) HPX_REGISTER_ACTION(accumulator_type::wrapped_type::query_action, managed_accumulator_query_action) +//] #endif diff --git a/libs/core/runtime_configuration/include/hpx/runtime_configuration/component_commandline_base.hpp b/libs/core/runtime_configuration/include/hpx/runtime_configuration/component_commandline_base.hpp index 912dc1bd23fe..f7fd1b0d8be6 100644 --- a/libs/core/runtime_configuration/include/hpx/runtime_configuration/component_commandline_base.hpp +++ b/libs/core/runtime_configuration/include/hpx/runtime_configuration/component_commandline_base.hpp @@ -4,6 +4,10 @@ // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +/// \file component_commandline_base.hpp +/// \page hpx::components::component_commandline_base +/// \headerfile hpx/components.hpp + #pragma once #include diff --git a/libs/core/runtime_configuration/include/hpx/runtime_configuration/component_factory_base.hpp b/libs/core/runtime_configuration/include/hpx/runtime_configuration/component_factory_base.hpp index 3f213370bbe8..39b67d8b67a7 100644 --- a/libs/core/runtime_configuration/include/hpx/runtime_configuration/component_factory_base.hpp +++ b/libs/core/runtime_configuration/include/hpx/runtime_configuration/component_factory_base.hpp @@ -4,6 +4,10 @@ // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +/// \file component_commandline.hpp +/// \page HPX_REGISTER_COMPONENT_MODULE +/// \headerfile hpx/components.hpp + #pragma once #include diff --git a/libs/full/actions_base/include/hpx/actions_base/basic_action.hpp b/libs/full/actions_base/include/hpx/actions_base/basic_action.hpp index 5c216a6227e9..1383810b971e 100644 --- a/libs/full/actions_base/include/hpx/actions_base/basic_action.hpp +++ b/libs/full/actions_base/include/hpx/actions_base/basic_action.hpp @@ -7,6 +7,8 @@ // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) /// \file hpx/actions_base/basic_action.hpp +/// \page HPX_REGISTER_ACTION_DECLARATION, HPX_REGISTER_ACTION +/// \headerfile hpx/components.hpp #pragma once diff --git a/libs/full/actions_base/include/hpx/actions_base/component_action.hpp b/libs/full/actions_base/include/hpx/actions_base/component_action.hpp index 64b134247dd9..1680bc423b79 100644 --- a/libs/full/actions_base/include/hpx/actions_base/component_action.hpp +++ b/libs/full/actions_base/include/hpx/actions_base/component_action.hpp @@ -5,6 +5,8 @@ // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) /// \file component_action.hpp +/// \page HPX_DEFINE_COMPONENT_ACTION +/// \headerfile hpx/components.hpp #pragma once diff --git a/libs/full/components/include/hpx/components/client.hpp b/libs/full/components/include/hpx/components/client.hpp index 1f3dc818f1b0..af7e10d3d95b 100644 --- a/libs/full/components/include/hpx/components/client.hpp +++ b/libs/full/components/include/hpx/components/client.hpp @@ -4,6 +4,10 @@ // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +/// \file component_commandline.hpp +/// \page hpx::components::client +/// \headerfile hpx/components.hpp + #pragma once #include @@ -14,6 +18,11 @@ namespace hpx::components { + /// @brief The client class is a wrapper that manages a distributed component. + /// It extends \c client_base with specific \c Component and \c Data types. + /// + /// @tparam Component The type of the component. + /// @tparam Data The type of the data associated with the client (default is void). template class client : public client_base, Component, Data> { diff --git a/libs/full/components/include/hpx/components/client_base.hpp b/libs/full/components/include/hpx/components/client_base.hpp index 1d3117f00d86..b16c774853cf 100644 --- a/libs/full/components/include/hpx/components/client_base.hpp +++ b/libs/full/components/include/hpx/components/client_base.hpp @@ -4,6 +4,10 @@ // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +/// \file client_base.hpp +/// \page hpx::components::client_base +/// \headerfile hpx/components.hpp + #pragma once #include @@ -279,6 +283,13 @@ namespace hpx::components { } // namespace detail /////////////////////////////////////////////////////////////////////////// + /// This class template serves as a base class for client components, + /// providing common functionality such as managing shared state, ID + /// retrieval, and asynchronous operations. + /// + /// @tparam Derived The derived client component type. + /// @tparam Stub The stub type used for communication. + /// @tparam Data The extra data type used for additional information. template class client_base : public detail::make_stub::type { diff --git a/libs/full/components_base/include/hpx/components_base/component_commandline.hpp b/libs/full/components_base/include/hpx/components_base/component_commandline.hpp index 0fbaf9b3ab9d..c66c68bf0828 100644 --- a/libs/full/components_base/include/hpx/components_base/component_commandline.hpp +++ b/libs/full/components_base/include/hpx/components_base/component_commandline.hpp @@ -4,6 +4,10 @@ // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +/// \file component_commandline.hpp +/// \page HPX_REGISTER_COMMANDLINE_MODULE +/// \headerfile hpx/components.hpp + #pragma once #include @@ -53,6 +57,15 @@ namespace hpx::components { /***/ /////////////////////////////////////////////////////////////////////////////// +/** + * @brief Macro to register a command-line module with the HPX runtime. + * + * This macro facilitates the registration of a command-line module with the HPX + * runtime system. A command-line module typically provides additional command-line + * options that can be used to configure the HPX application. + * + * @param add_options_function The function that adds custom command-line options. + */ #define HPX_REGISTER_COMMANDLINE_MODULE(add_options_function) \ HPX_REGISTER_COMMANDLINE_OPTIONS() \ HPX_REGISTER_COMMANDLINE_REGISTRY( \ diff --git a/libs/full/components_base/include/hpx/components_base/component_startup_shutdown.hpp b/libs/full/components_base/include/hpx/components_base/component_startup_shutdown.hpp index 1e5916dc83b6..a1ca66fe4d22 100644 --- a/libs/full/components_base/include/hpx/components_base/component_startup_shutdown.hpp +++ b/libs/full/components_base/include/hpx/components_base/component_startup_shutdown.hpp @@ -4,6 +4,10 @@ // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +/// \file component_commandline.hpp +/// \page HPX_REGISTER_STARTUP_MODULE +/// \headerfile hpx/components.hpp + #pragma once #include @@ -119,6 +123,15 @@ namespace hpx::components { startup_shutdown) \ /**/ +/** + * @brief Macro to register a startup module with the HPX runtime. + * + * This macro facilitates the registration of a startup module with the HPX + * runtime system. A startup module typically contains initialization code + * that should be executed when the HPX runtime starts. + * + * @param startup The name of the startup function to be registered. + */ #define HPX_REGISTER_STARTUP_MODULE(startup) \ HPX_REGISTER_STARTUP_SHUTDOWN_FUNCTIONS() \ HPX_REGISTER_STARTUP_SHUTDOWN_MODULE_(startup, 0) \ diff --git a/libs/full/components_base/include/hpx/components_base/components_base_fwd.hpp b/libs/full/components_base/include/hpx/components_base/components_base_fwd.hpp index 1ad0676706f9..0c2538ecf2c6 100644 --- a/libs/full/components_base/include/hpx/components_base/components_base_fwd.hpp +++ b/libs/full/components_base/include/hpx/components_base/components_base_fwd.hpp @@ -5,6 +5,10 @@ // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +/// \file components_base_fwd.hpp +/// \page hpx::components::component, hpx::components::component_base +/// \headerfile hpx/components.hpp + #pragma once #include @@ -19,6 +23,9 @@ namespace hpx::components { template class fixed_component; + /// The \a component class wraps around a given component type, adding + /// additional type aliases and constructors. It inherits from the + /// specified component type. template class component; @@ -26,6 +33,10 @@ namespace hpx::components { class managed_component; /////////////////////////////////////////////////////////////////////// + /// \a component_base serves as a base class for components. It provides + /// common functionality needed by components, such as address and ID + /// retrieval. The template parameter \a Component specifies the + /// derived component type. template class component_base; diff --git a/libs/full/runtime_components/include/hpx/runtime_components/component_factory.hpp b/libs/full/runtime_components/include/hpx/runtime_components/component_factory.hpp index 80c72f35396b..41ecf5a1f61c 100644 --- a/libs/full/runtime_components/include/hpx/runtime_components/component_factory.hpp +++ b/libs/full/runtime_components/include/hpx/runtime_components/component_factory.hpp @@ -6,6 +6,8 @@ // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) /// \file hpx/runtime_components/component_factory.hpp +/// \page HPX_REGISTER_COMPONENT +/// \headerfile hpx/components.hpp #pragma once diff --git a/libs/full/runtime_components/include/hpx/runtime_components/new.hpp b/libs/full/runtime_components/include/hpx/runtime_components/new.hpp index 174acf3ce9ae..41c2b6e1ceeb 100644 --- a/libs/full/runtime_components/include/hpx/runtime_components/new.hpp +++ b/libs/full/runtime_components/include/hpx/runtime_components/new.hpp @@ -5,6 +5,8 @@ // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) /// \file new.hpp +/// \page hpx::new_ +/// \headerfile hpx/components.hpp #pragma once @@ -66,7 +68,7 @@ namespace hpx { /// component instance. /// template - new_(id_type const& locality, Ts&&... vs); + auto new_(id_type const& locality, Ts&&... vs); /// \brief Create one new instance of the given Component type on the /// current locality. @@ -110,7 +112,7 @@ namespace hpx { /// only. /// template - local_new(Ts&&... vs); + auto local_new(Ts&&... vs); /// \brief Create multiple new instances of the given Component type on the /// specified locality. @@ -155,7 +157,7 @@ namespace hpx { /// components. /// template - new_(id_type const& locality, std::size_t count, Ts&&... vs); + auto new_(id_type const& locality, std::size_t count, Ts&&... vs); /// \brief Create one or more new instances of the given Component type /// based on the given distribution policy. @@ -194,7 +196,7 @@ namespace hpx { /// component instance. /// template - new_(DistPolicy const& policy, Ts&&... vs); + auto new_(DistPolicy const& policy, Ts&&... vs); /// \brief Create multiple new instances of the given Component type on the /// localities as defined by the given distribution policy. @@ -239,7 +241,7 @@ namespace hpx { /// components. /// template - new_(DistPolicy const& policy, std::size_t count, Ts&&... vs); + auto new_(DistPolicy const& policy, std::size_t count, Ts&&... vs); } // namespace hpx #else