hpx/runtime_components/new.hpp#

Defined in header hpx/runtime_components/new.hpp.

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx

Functions

template<typename Component, typename... Ts> < unspecified > new_ (id_type const &locality, Ts &&... vs)

Create one or more new instances of the given Component type on the specified locality.

This function creates one or more new instances of the given Component type on the specified locality and returns a future object for the global address which can be used to reference the new component instance.

Note

This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance: 

hpx::future<hpx::id_type> f =
   hpx::new_<some_component>(hpx::find_here(), ...);
hpx::id_type id = f.get();

Parameters

  • locality – [in] The global address of the locality where the new instance should be created on.

  • vs – [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.

Returns

The function returns different types depending on its use:

  • If the explicit template argument Component represents a component type (traits::is_component<Component>::value evaluates to true), the function will return an hpx::future object instance which can be used to retrieve the global address of the newly created component.

  • If the explicit template argument Component represents a client side object (traits::is_client<Component>::value evaluates to true), the function will return a new instance of that type which can be used to refer to the newly created component instance.

template<typename Component, typename... Ts> < unspecified > local_new (Ts &&... vs)

Create one new instance of the given Component type on the current locality.

This function creates one new instance of the given Component type on the current locality and returns a future object for the global address which can be used to reference the new component instance.

Note

This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance: 

hpx::future<hpx::id_type> f =
   hpx::local_new<some_component>(...);
hpx::id_type id = f.get();

Note

The difference of this function to hpx::new_ is that it can be used in cases where the supplied arguments are non-copyable and non-movable. All operations are guaranteed to be local only.

Parameters

vs – [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.

Returns

The function returns different types depending on its use:

  • If the explicit template argument Component represents a component type (traits::is_component<Component>::value evaluates to true), the function will return an hpx::future object instance which can be used to retrieve the global address of the newly created component. If the first argument is hpx::launch::sync the function will directly return an hpx::id_type.

  • If the explicit template argument Component represents a client side object (traits::is_client<Component>::value evaluates to true), the function will return a new instance of that type which can be used to refer to the newly created component instance.

template<typename Component, typename... Ts> < unspecified > new_ (id_type const &locality, std::size_t count, Ts &&... vs)

Create multiple new instances of the given Component type on the specified locality.

This function creates multiple new instances of the given Component type on the specified locality and returns a future object for the global address which can be used to reference the new component instance.

Note

This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance: 

hpx::future<std::vector<hpx::id_type> > f =
   hpx::new_<some_component[]>(hpx::find_here(), 10, ...);
hpx::id_type id = f.get();

Parameters

  • locality – [in] The global address of the locality where the new instance should be created on.

  • count – [in] The number of component instances to create

  • vs – [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.

Returns

The function returns different types depending on its use:

  • If the explicit template argument Component represents an array of a component type (i.e. Component[], where traits::is_component<Component>::value evaluates to true), the function will return an hpx::future object instance which holds a std::vector<hpx::id_type>, where each of the items in this vector is a global address of one of the newly created components.

  • If the explicit template argument Component represents an array of a client side object type (i.e. Component[], where traits::is_client<Component>::value evaluates to true), the function will return an hpx::future object instance which holds a std::vector<hpx::id_type>, where each of the items in this vector is a client side instance of the given type, each representing one of the newly created components.

template<typename Component, typename DistPolicy, typename... Ts> < unspecified > new_ (DistPolicy const &policy, Ts &&... vs)

Create one or more new instances of the given Component type based on the given distribution policy.

This function creates one or more new instances of the given Component type on the localities defined by the given distribution policy and returns a future object for global address which can be used to reference the new component instance(s).

Note

This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance: 

hpx::future<hpx::id_type> f =
   hpx::new_<some_component>(hpx::default_layout, ...);
hpx::id_type id = f.get();

Parameters

  • policy – [in] The distribution policy used to decide where to place the newly created.

  • vs – [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.

Returns

The function returns different types depending on its use:

  • If the explicit template argument Component represents a component type (traits::is_component<Component>::value evaluates to true), the function will return an hpx::future object instance which can be used to retrieve the global address of the newly created component.

  • If the explicit template argument Component represents a client side object (traits::is_client<Component>::value evaluates to true), the function will return a new instance of that type which can be used to refer to the newly created component instance.

template<typename Component, typename DistPolicy, typename... Ts> < unspecified > new_ (DistPolicy const &policy, std::size_t count, Ts &&... vs)

Create multiple new instances of the given Component type on the localities as defined by the given distribution policy.

This function creates multiple new instances of the given Component type on the localities defined by the given distribution policy and returns a future object for the global address which can be used to reference the new component instance.

Note

This function requires to specify an explicit template argument which will define what type of component(s) to create, for instance: 

hpx::future<std::vector<hpx::id_type> > f =
   hpx::new_<some_component[]>(hpx::default_layout, 10, ...);
hpx::id_type id = f.get();

Parameters

  • policy – [in] The distribution policy used to decide where to place the newly created.

  • count – [in] The number of component instances to create

  • vs – [in] Any number of arbitrary arguments (passed by value, by const reference or by rvalue reference) which will be forwarded to the constructor of the created component instance.

Returns

The function returns different types depending on its use:

  • If the explicit template argument Component represents an array of a component type (i.e. Component[], where traits::is_component<Component>::value evaluates to true), the function will return an hpx::future object instance which holds a std::vector<hpx::id_type>, where each of the items in this vector is a global address of one of the newly created components.

  • If the explicit template argument Component represents an array of a client side object type (i.e. Component[], where traits::is_client<Component>::value evaluates to true), the function will return an hpx::future object instance which holds a std::vector<hpx::id_type>, where each of the items in this vector is a client side instance of the given type, each representing one of the newly created components.