components¶

The contents of this module can be included with the header hpx/modules/components.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/components.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

namespace hpx

Functions

template<typename Client> std::vector<Client> find_all_from_basename(std::string base_name, std::size_t num_ids)¶

Return all registered clients from all localities from the given base name.

This function locates all ids which were registered with the given base name. It returns a list of futures representing those ids.

Return all registered ids from all localities from the given base name.

Return

A list of futures representing the ids which were registered using the given base name.

Note

The futures embedded in the returned client objects will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.

Template Parameters

Client: The client type to return

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
num_ids: [in] The number of registered ids to expect.

This function locates all ids which were registered with the given base name. It returns a list of futures representing those ids.

Return

A list of futures representing the ids which were registered using the given base name.

Note

The futures will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
num_ids: [in] The number of registered ids to expect.

template<typename Client> std::vector<Client> find_from_basename(std::string base_name, std::vector<std::size_t> const &ids)¶

Return registered clients from the given base name and sequence numbers.

This function locates the ids which were registered with the given base name and the given sequence numbers. It returns a list of futures representing those ids.

Return registered ids from the given base name and sequence numbers.

Return

A list of futures representing the ids which were registered using the given base name and sequence numbers.

Note

The futures embedded in the returned client objects will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.

Template Parameters

Client: The client type to return

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
ids: [in] The sequence numbers of the registered ids.

This function locates the ids which were registered with the given base name and the given sequence numbers. It returns a list of futures representing those ids.

Return

A list of futures representing the ids which were registered using the given base name and sequence numbers.

Note

The futures will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
ids: [in] The sequence numbers of the registered ids.

template<typename Client> Client find_from_basename(std::string base_name, std::size_t sequence_nr)¶

Return registered id from the given base name and sequence number.

This function locates the id which was registered with the given base name and the given sequence number. It returns a future representing those id.

Return

A representing the id which was registered using the given base name and sequence numbers.

Note

The future embedded in the returned client object will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.

Template Parameters

Client: The client type to return

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
sequence_nr: [in] The sequence number of the registered id.

Return

A representing the id which was registered using the given base name and sequence numbers.

Note

The future will become ready even if the event (for instance, binding the name to an id) has already happened in the past. This is important in order to reliably retrieve ids from a name, even if the name was already registered.

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
sequence_nr: [in] The sequence number of the registered id.

template<typename Client, typename Stub> hpx::future<bool> register_with_basename(std::string base_name, components::client_base<Client, Stub> &client, std::size_t sequence_nr)¶

Register the id wrapped in the given client using the given base name.

The function registers the object the given client refers to using the provided base name.

Return

A future representing the result of the registration operation itself.

Note

The operation will fail if the given sequence number is not unique.

Template Parameters

Client: The client type to register

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
client: [in] The client which should be registered using the given base name.
sequence_nr: [in, optional] The sequential number to use for the registration of the id. This number has to be unique system wide for each registration using the same base name. The default is the current locality identifier. Also, the sequence numbers have to be consecutive starting from zero.

template<typename Client> Client unregister_with_basename(std::string base_name, std::size_t sequence_nr)¶

Unregister the given id using the given base name.

Unregister the given base name.

The function unregisters the given ids using the provided base name.

Return

A future representing the result of the un-registration operation itself.

Template Parameters

Client: The client type to return

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
sequence_nr: [in, optional] The sequential number to use for the un-registration. This number has to be the same as has been used with register_with_basename before.

Return

A future representing the result of the un-registration operation itself.

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
sequence_nr: [in, optional] The sequential number to use for the un-registration. This number has to be the same as has been used with register_with_basename before.

namespace hpx

Functions

hpx::future<bool> register_with_basename(std::string base_name, hpx::id_type id, std::size_t sequence_nr = ~static_cast<std::size_t>(0))¶

Register the given id using the given base name.

The function registers the given ids using the provided base name.

Return

A future representing the result of the registration operation itself.

Note

The operation will fail if the given sequence number is not unique.

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
id: [in] The id to register using the given base name.
sequence_nr: [in, optional] The sequential number to use for the registration of the id. This number has to be unique system wide for each registration using the same base name. The default is the current locality identifier. Also, the sequence numbers have to be consecutive starting from zero.

hpx::future<bool> register_with_basename(std::string base_name, hpx::future<hpx::id_type> f, std::size_t sequence_nr = ~static_cast<std::size_t>(0))¶

Register the id wrapped in the given future using the given base name.

The function registers the object the given future refers to using the provided base name.

Return

A future representing the result of the registration operation itself.

Note

The operation will fail if the given sequence number is not unique.

Parameters

base_name: [in] The base name for which to retrieve the registered ids.
f: [in] The future which should be registered using the given base name.
sequence_nr: [in, optional] The sequential number to use for the registration of the id. This number has to be unique system wide for each registration using the same base name. The default is the current locality identifier. Also, the sequence numbers have to be consecutive starting from zero.

namespace hpx

namespace components

template<typename Component> class client : public hpx::components::client_base<client<Component>, Component>¶

Public Functions

client()¶

client(naming::id_type const &id)¶

client(naming::id_type &&id)¶

client(future_type const &f)¶

client(future_type &&f)¶

client(future<naming::id_type> &&f)¶

client(future<client> &&c)¶

client(client const &rhs)¶

client(client &&rhs)¶

client &operator=(naming::id_type const &id)¶

client &operator=(naming::id_type &&id)¶

client &operator=(future_type const &f)¶

client &operator=(future_type &&f)¶

client &operator=(future<naming::id_type> &&f)¶

client &operator=(client const &rhs)¶

client &operator=(client &&rhs)¶

Private Types

template<> using base_type = client_base<client<Component>, Component>¶

template<> using future_type = typename base_type::future_type¶

namespace hpx

namespace components

Functions

template<typename Derived, typename Stub> bool operator==(client_base<Derived, Stub> const &lhs, client_base<Derived, Stub> const &rhs)¶

template<typename Derived, typename Stub> bool operator<(client_base<Derived, Stub> const &lhs, client_base<Derived, Stub> const &rhs)¶

template<typename Derived, typename Stub> class client_base : public detail::make_stub::type<Stub>¶

Public Types

template<> using stub_argument_type = Stub¶

template<> using server_component_type = typename detail::make_stub::server_component_type¶

template<> using is_client_tag = void¶

Public Functions

client_base()¶

client_base(id_type const &id)¶

client_base(id_type &&id)¶

client_base(shared_future<id_type> const &f)¶

client_base(shared_future<id_type> &&f)¶

client_base(future<id_type> &&f)¶

client_base(client_base const &rhs)¶

client_base(client_base &&rhs)¶

client_base(future<Derived> &&d)¶

~client_base()¶

client_base &operator=(id_type const &id)¶

client_base &operator=(id_type &&id)¶

client_base &operator=(shared_future<id_type> const &f)¶

client_base &operator=(shared_future<id_type> &&f)¶

client_base &operator=(future<id_type> &&f)¶

client_base &operator=(client_base const &rhs)¶

client_base &operator=(client_base &&rhs)¶

bool valid() const¶

operator bool() const¶

void free()¶

id_type const &get_id() const¶

naming::gid_type const &get_raw_gid() const¶

shared_future<id_type> detach()¶

shared_future<id_type> share() const¶

void reset(id_type const &id)¶

void reset(id_type &&id)¶

void reset(shared_future<id_type> &&rhs)¶

id_type const &get() const¶

bool is_ready() const¶

bool has_value() const¶

bool has_exception() const¶

void wait() const¶

std::exception_ptr get_exception_ptr() const¶

template<typename F> hpx::traits::future_then_result_t<Derived, F> then(launch l, F &&f)¶

template<typename F> hpx::traits::future_then_result_t<Derived, F> then(F &&f)¶

future<bool> register_as(std::string symbolic_name, bool manage_lifetime = true)¶

void connect_to(std::string const &symbolic_name)¶

std::string const &registered_name() const¶

Protected Types

template<> using stub_type = typename detail::make_stub<Stub>::type¶

template<> using shared_state_type = lcos::detail::future_data_base<id_type>¶

template<> using future_type = shared_future<id_type>¶

Protected Functions

client_base(hpx::intrusive_ptr<shared_state_type> const &state)¶

client_base(hpx::intrusive_ptr<shared_state_type> &&state)¶

Protected Attributes

hpx::intrusive_ptr<shared_state_type> shared_state_¶

Private Static Functions

template<typename F> static hpx::traits::future_then_result<Derived, F>::cont_result on_ready(shared_future<id_type> &&fut, F f)¶

static bool register_as_helper(client_base const &f, std::string symbolic_name, bool manage_lifetime)¶

namespace serialization

Functions

template<typename Archive, typename Derived, typename Stub> void serialize(Archive &ar, ::hpx::components::client_base<Derived, Stub> &f, unsigned version)¶

namespace hpx

namespace components

template<typename Executor, typename BaseComponent> struct executor_component : public BaseComponent ¶

Public Functions

template<typename ...Arg> executor_component(executor_type const &exec, Arg&&... arg)¶

Public Static Functions

static void execute(hpx::threads::thread_function_type const &f)¶

template<typename Executor_ = Executor> static void schedule_thread(hpx::naming::address::address_type lva, naming::address::component_type, hpx::threads::thread_init_data &data, hpx::threads::thread_schedule_state)¶: This is the default hook implementation for schedule_thread which forwards to the executor instance associated with this component.

Protected Attributes

executor_type exec_¶

Private Types

typedef BaseComponent base_type¶

typedef Executor executor_type¶

typedef base_type::this_component_type this_component_type¶

namespace hpx

Functions

template<typename Component> hpx::future<std::shared_ptr<Component>> get_ptr(naming::id_type const &id)¶

Returns a future referring to the pointer to the underlying memory of a component.

The function hpx::get_ptr can be used to extract a future referring to the pointer to the underlying memory of a given component.

Return

This function returns a future representing the pointer to the underlying memory for the component instance with the given id.

Note

This function will successfully return the requested result only if the given component is currently located on the calling locality. Otherwise the function will raise an error.

Note

The component instance the returned pointer refers to can not be migrated as long as there is at least one copy of the returned shared_ptr alive.

Parameters

id: [in] The global id of the component for which the pointer to the underlying memory should be retrieved.

Template Parameters

The: only template parameter has to be the type of the server side component.

template<typename Derived, typename Stub> hpx::future<std::shared_ptr<typename components::client_base<Derived, Stub>::server_component_type>> get_ptr(components::client_base<Derived, Stub> const &c)¶

Returns a future referring to the pointer to the underlying memory of a component.

The function hpx::get_ptr can be used to extract a future referring to the pointer to the underlying memory of a given component.

Return

This function returns a future representing the pointer to the underlying memory for the component instance with the given id.

Note

This function will successfully return the requested result only if the given component is currently located on the calling locality. Otherwise the function will raise an error.

Note

The component instance the returned pointer refers to can not be migrated as long as there is at least one copy of the returned shared_ptr alive.

Parameters

c: [in] A client side representation of the component for which the pointer to the underlying memory should be retrieved.

template<typename Component> std::shared_ptr<Component> get_ptr(launch::sync_policy p, naming::id_type const &id, error_code &ec = throws)¶

Returns the pointer to the underlying memory of a component.

The function hpx::get_ptr_sync can be used to extract the pointer to the underlying memory of a given component.

Return

This function returns the pointer to the underlying memory for the component instance with the given id.

Note

This function will successfully return the requested result only if the given component is currently located on the requesting locality. Otherwise the function will raise and error.

Note

The component instance the returned pointer refers to can not be migrated as long as there is at least one copy of the returned shared_ptr alive.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Parameters

p: [in] The parameter p represents a placeholder type to turn make the call synchronous.
id: [in] The global id of the component for which the pointer to the underlying memory should be retrieved.
ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

Template Parameters

The: only template parameter has to be the type of the server side component.

template<typename Derived, typename Stub> std::shared_ptr<typename components::client_base<Derived, Stub>::server_component_type> get_ptr(launch::sync_policy p, components::client_base<Derived, Stub> const &c, error_code &ec = throws)¶

Returns the pointer to the underlying memory of a component.

The function hpx::get_ptr_sync can be used to extract the pointer to the underlying memory of a given component.

Return

This function returns the pointer to the underlying memory for the component instance with the given id.

Note

This function will successfully return the requested result only if the given component is currently located on the requesting locality. Otherwise the function will raise and error.

Note

The component instance the returned pointer refers to can not be migrated as long as there is at least one copy of the returned shared_ptr alive.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Parameters

p: [in] The parameter p represents a placeholder type to turn make the call synchronous.
c: [in] A client side representation of the component for which the pointer to the underlying memory should be retrieved.
ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

namespace hpx

namespace components

Functions

template<typename Client> std::enable_if<traits::is_client<Client>::value, Client>::type make_client(hpx::id_type const &id)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, Client>::type make_client(hpx::id_type &&id)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, Client>::type make_client(hpx::future<hpx::id_type> const &id)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, Client>::type make_client(hpx::future<hpx::id_type> &&id)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, Client>::type make_client(hpx::shared_future<hpx::id_type> const &id)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, Client>::type make_client(hpx::shared_future<hpx::id_type> &&id)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, std::vector<Client>>::type make_clients(std::vector<hpx::id_type> const &ids)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, std::vector<Client>>::type make_clients(std::vector<hpx::id_type> &&ids)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, std::vector<Client>>::type make_clients(std::vector<hpx::future<hpx::id_type>> const &ids)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, std::vector<Client>>::type make_clients(std::vector<hpx::future<hpx::id_type>> &&ids)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, std::vector<Client>>::type make_clients(std::vector<hpx::shared_future<hpx::id_type>> const &ids)¶

template<typename Client> std::enable_if<traits::is_client<Client>::value, std::vector<Client>>::type make_clients(std::vector<hpx::shared_future<hpx::id_type>> &&ids)¶