diff --git a/docs/sphinx/api/public_distributed_api.rst b/docs/sphinx/api/public_distributed_api.rst index 4cfb1b931df6..a39417fe279c 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,67 @@ 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`. + +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/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