Skip to content

Commit

Permalink
Add components documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
dimitraka committed Jun 17, 2024
1 parent 0d6a0bd commit d46a30d
Show file tree
Hide file tree
Showing 12 changed files with 141 additions and 5 deletions.
63 changes: 63 additions & 0 deletions docs/sphinx/api/public_distributed_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -177,3 +177,66 @@ Member functions
+----------------------------------------------------------+
| :cpp:func:`hpx::distributed::latch::wait` |
+----------------------------------------------------------+

``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_` |
+----------------------------------------------------------+
Original file line number Diff line number Diff line change
Expand Up @@ -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 <hpx/config.hpp>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <hpx/config.hpp>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
9 changes: 9 additions & 0 deletions libs/full/components/include/hpx/components/client.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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 <hpx/config.hpp>
Expand All @@ -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 <typename Component, typename Data = void>
class client : public client_base<client<Component, Data>, Component, Data>
{
Expand Down
11 changes: 11 additions & 0 deletions libs/full/components/include/hpx/components/client_base.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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 <hpx/config.hpp>
Expand Down Expand Up @@ -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 <typename Derived, typename Stub, typename Data>
class client_base : public detail::make_stub<Stub>::type
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <hpx/config.hpp>
Expand Down Expand Up @@ -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( \
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <hpx/config.hpp>
Expand Down Expand Up @@ -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) \
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 <hpx/config.hpp>
Expand All @@ -19,13 +23,20 @@ namespace hpx::components {
template <typename Component>
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 <typename Component>
class component;

template <typename Component, typename Derived = void>
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 <typename Component = void>
class component_base;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -66,7 +68,7 @@ namespace hpx {
/// component instance.
///
template <typename Component, typename... Ts>
<unspecified> 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.
Expand Down Expand Up @@ -110,7 +112,7 @@ namespace hpx {
/// only.
///
template <typename Component, typename... Ts>
<unspecified> local_new(Ts&&... vs);
auto local_new(Ts&&... vs);

/// \brief Create multiple new instances of the given Component type on the
/// specified locality.
Expand Down Expand Up @@ -155,7 +157,7 @@ namespace hpx {
/// components.
///
template <typename Component, typename... Ts>
<unspecified> 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.
Expand Down Expand Up @@ -194,7 +196,7 @@ namespace hpx {
/// component instance.
///
template <typename Component, typename DistPolicy, typename... Ts>
<unspecified> 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.
Expand Down Expand Up @@ -239,7 +241,7 @@ namespace hpx {
/// components.
///
template <typename Component, typename DistPolicy, typename... Ts>
<unspecified> new_(DistPolicy const& policy, std::size_t count, Ts&&... vs);
auto new_(DistPolicy const& policy, std::size_t count, Ts&&... vs);
} // namespace hpx

#else
Expand Down

0 comments on commit d46a30d

Please sign in to comment.