Distributed objects

Distributed object creation, registration, retrieval and destruction. More...

Collaboration diagram for Distributed objects:

Classes
class	stapl::p_object_delete< T, Deleter >
	Deletes a distributed object. More...
class	stapl::p_object
	Implements the base class for distributed objects. More...
class	stapl::rmi_handle
	Provides a registration mechanism for RMI communication. More...

Enumerations
enum	stapl::rmi_handle_flags { stapl::no_aggregation = 0x1, stapl::no_fence_information = 0x2, stapl::allow_try_rmi = 0x4 }
	Flags for registering objects. More...

Functions
template<typename T , typename... Args>
future< rmi_handle::reference >	stapl::construct (neighbor_locations_t, Args &&... args)
	Creates an object of type T in a new gang over all the locations of the current gang that are on shared memory. More...
template<typename T , typename U , typename... Args>
future< rmi_handle::reference >	stapl::construct (location_range_wrapper< U > const &r, Args &&... args)
	Creates an object of type T in a new gang over the range r of the locations of the current gang. More...
template<typename T , typename Function , typename U , typename... Args>
void	stapl::async_construct (Function &&f, location_range_wrapper< U > const &r, Args &&... args)
	Creates an object of type T in a new gang over the range r of the locations of the current gang and calls f with the object pointer. More...
template<typename T , typename... Args>
future< rmi_handle::reference >	stapl::construct (rmi_handle::const_reference const &h, all_locations_t, Args &&... args)
	Creates an object of type T in a new gang over all the locations of the gang of h. More...
template<typename T , typename Function , typename... Args>
void	stapl::async_construct (Function &&f, rmi_handle::const_reference const &h, all_locations_t, Args &&... args)
	Creates an object of type T in a new gang over all the locations of the gang of h and calls f with the object pointer. More...
template<typename T , typename U , typename... Args>
future< rmi_handle::reference >	stapl::construct (rmi_handle::const_reference const &h, location_range_wrapper< U > const &r, Args &&... args)
	Creates an object of type T in a new gang over the range r of the locations of the gang of h. More...
template<typename T , typename Function , typename U , typename... Args>
void	stapl::async_construct (Function &&f, rmi_handle::const_reference const &h, location_range_wrapper< U > const &r, Args &&... args)
	Creates an object of type T in a new gang over the range r of the locations of the gang of h and calls f with the object pointer. More...
template<typename T , typename... Args>
future< rmi_handle::reference >	stapl::construct (level const &l, Args &&... args)
	Creates an object of type T in a new gang over the level l of the hierarchy. More...
template<typename Handle , typename MemFun , typename... T>
future< typename callable_traits< MemFun >::result_type >	stapl::restore (Handle const &h, MemFun const &pmf, T &&... t)
	Restores the SPMD execution of the gang of the given object, using as the entry point the given member function. More...
template<typename T >
T const &	stapl::get_p_object (rmi_handle::const_reference const &h)
	Returns a reference to the object registered with the rmi_handle that h refers to. More...
template<typename T >
T const &	stapl::get_p_object (rmi_handle::const_light_reference const &h)
	Returns a reference to the object registered with the rmi_handle that h refers to. More...
template<typename T >
T &	stapl::get_p_object (rmi_handle::reference const &h)
	Returns a reference to the object registered with the rmi_handle that h refers to. More...
template<typename T >
T &	stapl::get_p_object (rmi_handle::light_reference const &h)
	Returns a reference to the object registered with the rmi_handle that h refers to. More...
template<typename T >
T const *	stapl::resolve_handle (rmi_handle::const_reference const &h) noexcept
	Attempts to return a pointer to the object registered with the rmi_handle that h refers to. More...
template<typename T >
T *	stapl::resolve_handle (rmi_handle::reference const &h) noexcept
	Attempts to return a pointer to the object registered with the rmi_handle that h refers to. More...
template<typename T >
T const *	stapl::resolve_handle (rmi_handle::const_light_reference const &h) noexcept
	Attempts to return a pointer to the object registered with the rmi_handle that h refers to. More...
template<typename T >
T *	stapl::resolve_handle (rmi_handle::light_reference const &h) noexcept
	Attempts to return a pointer to the object registered with the rmi_handle that h refers to. More...
int	stapl::compare_gangs (rmi_handle::const_reference const &x, rmi_handle::const_reference const &y) noexcept
	Returns if the two handles are defined over identical, similar or completely different gangs. More...

Detailed Description

Distributed object creation, registration, retrieval and destruction.

Enumeration Type Documentation

rmi_handle_flags

enum stapl::rmi_handle_flags

Flags for registering objects.

See also

rmi_handle, p_object

Enumerator
no_aggregation	Disables aggregation for the object.
no_fence_information	Disables fence bookkeeping for the object.
allow_try_rmi	Enables support for try_rmi().

Function Documentation

construct() [1/5]

template<typename T , typename... Args>

future<rmi_handle::reference> stapl::construct	(	neighbor_locations_t	,
		Args &&...	args
	)

Creates an object of type T in a new gang over all the locations of the current gang that are on shared memory.

Parameters

args	Arguments to pass to the constructor of T.

Returns

A future object with an rmi_handle::reference to the constructed object.

construct() [2/5]

template<typename T , typename U , typename... Args>

future<rmi_handle::reference> stapl::construct	(	location_range_wrapper< U > const &	r,
		Args &&...	args
	)

Creates an object of type T in a new gang over the range r of the locations of the current gang.

Warning

r may only contain locations of the current gang.

Parameters

r	Location id range of the current that the new gang will be created in.
args	Arguments to pass to the constructor of T.

Returns

A future object with an rmi_handle::reference to the constructed object.

async_construct() [1/3]

template<typename T , typename Function , typename U , typename... Args>

void stapl::async_construct	(	Function &&	f,
		location_range_wrapper< U > const &	r,
		Args &&...	args
	)

Creates an object of type T in a new gang over the range r of the locations of the current gang and calls f with the object pointer.

Warning

r may only contain locations of the current gang.

Parameters

f	Function to pass the pointer of the constructed object.
r	Location id range of the current that the new gang will be created in.
args	Arguments to pass to the constructor of T.

construct() [3/5]

template<typename T , typename... Args>

future<rmi_handle::reference> stapl::construct	(	rmi_handle::const_reference const &	h,
		all_locations_t	,
		Args &&...	args
	)

Creates an object of type T in a new gang over all the locations of the gang of h.

Parameters

h	Target distributed object handle.
args	Arguments to pass to the constructor of T.

Returns

A future object with an rmi_handle::reference to the constructed object.

async_construct() [2/3]

template<typename T , typename Function , typename... Args>

void stapl::async_construct	(	Function &&	f,
		rmi_handle::const_reference const &	h,
		all_locations_t	,
		Args &&...	args
	)

Creates an object of type T in a new gang over all the locations of the gang of h and calls f with the object pointer.

Parameters

f	Function to pass the pointer of the constructed object.
h	Target distributed object handle.
args	Arguments to pass to the constructor of T.

construct() [4/5]

template<typename T , typename U , typename... Args>

future<rmi_handle::reference> stapl::construct	(	rmi_handle::const_reference const &	h,
		location_range_wrapper< U > const &	r,
		Args &&...	args
	)

Creates an object of type T in a new gang over the range r of the locations of the gang of h.

Warning

r may only contain locations of the gang of the object associated with the rmi_handle::const_reference.

Parameters

h	Target distributed object handle.
r	Location id range of the gang of h that the new gang will be created in.
args	Arguments to pass to the constructor of T.

Returns

A future object with an rmi_handle::reference to the constructed object.

async_construct() [3/3]

template<typename T , typename Function , typename U , typename... Args>

void stapl::async_construct	(	Function &&	f,
		rmi_handle::const_reference const &	h,
		location_range_wrapper< U > const &	r,
		Args &&...	args
	)

Creates an object of type T in a new gang over the range r of the locations of the gang of h and calls f with the object pointer.

Warning

r may only contain locations of the gang of the object associated with the rmi_handle::const_reference.

Parameters

f	Function to pass the pointer of the constructed object.
h	Target distributed object handle.
r	Location id range of the gang of h that the new gang will be created in.
args	Arguments to pass to the constructor of T.

construct() [5/5]

template<typename T , typename... Args>

future<rmi_handle::reference> stapl::construct	(	level const &	l,
		Args &&...	args
	)

Creates an object of type T in a new gang over the level l of the hierarchy.

Parameters

l	Target hierarchy level.
args	Arguments to pass to the constructor of T.

Returns

A future object with an rmi_handle::reference to the constructed object.

restore()

template<typename Handle , typename MemFun , typename... T>

future<typename callable_traits<MemFun>::result_type> stapl::restore	(	Handle const &	h,
		MemFun const &	pmf,
		T &&...	t
	)

Restores the SPMD execution of the gang of the given object, using as the entry point the given member function.

Parameters

h	Handle to the target object.
pmf	Member function to invoke.
t	Arguments to pass to the member function.

Returns

A future object with the return value of the invoked member function from location 0.

get_p_object() [1/4]

template<typename T >

T const& stapl::get_p_object

(

rmi_handle::const_reference const &

h

)

Returns a reference to the object registered with the rmi_handle that h refers to.

This function can only return references to objects that have been registered in the same gang that the caller executes in.

Parameters

h	Reference to an rmi_handle.

Returns

A reference to the object associated with the rmi_handle.

Warning

Requesting an object that has been unregistered or was never registered is undefined behavior.

get_p_object() [2/4]

template<typename T >

T const& stapl::get_p_object

(

rmi_handle::const_light_reference const &

h

)

Returns a reference to the object registered with the rmi_handle that h refers to.

This function can only return references to objects that have been registered in the same gang that the caller executes in.

Parameters

h	Reference to an rmi_handle.

Returns

A reference to the object associated with the rmi_handle.

Warning

Requesting an object that has been unregistered or was never registered is undefined behavior.

get_p_object() [3/4]

template<typename T >

T& stapl::get_p_object

(

rmi_handle::reference const &

h

)

Returns a reference to the object registered with the rmi_handle that h refers to.

This function can only return references to objects that have been registered in the same gang that the caller executes in.

Parameters

h	Reference to an rmi_handle.

Returns

A reference to the object associated with the rmi_handle.

Warning

Requesting an object that has been unregistered or was never registered is undefined behavior.

get_p_object() [4/4]

template<typename T >

T& stapl::get_p_object

(

rmi_handle::light_reference const &

h

)

Returns a reference to the object registered with the rmi_handle that h refers to.

This function can only return references to objects that have been registered in the same gang that the caller executes in.

Parameters

h	Reference to an rmi_handle.

Returns

A reference to the object associated with the rmi_handle.

Warning

Requesting an object that has been unregistered or was never registered is undefined behavior.

resolve_handle() [1/4]

template<typename T >

T const* stapl::resolve_handle ( rmi_handle::const_reference const &  h )

noexcept

Attempts to return a pointer to the object registered with the rmi_handle that h refers to.

This function will return a pointer to the object even if the requesting code executes in a gang other than the one that the object was registered in. The only requirement is that the location the object registered in and the location that the caller executes in are scheduled on the same thread.

Warning

If h is an invalid handle, nullptr is returned instead of an error.

Parameters

h	Reference to an rmi_handle.

Returns

A pointer to the object associated with the rmi_handle.

resolve_handle() [2/4]

template<typename T >

T* stapl::resolve_handle ( rmi_handle::reference const &  h )

noexcept

Attempts to return a pointer to the object registered with the rmi_handle that h refers to.

This function will return a pointer to the object even if the requesting code executes in a gang other than the one that the object was registered in. The only requirement is that the location the object registered in and the location that the caller executes in are scheduled on the same thread.

Warning

If h is an invalid handle, nullptr is returned instead of an error.

Parameters

h	Reference to an rmi_handle.

Returns

A pointer to the object associated with the rmi_handle.

resolve_handle() [3/4]

template<typename T >

T const* stapl::resolve_handle ( rmi_handle::const_light_reference const &  h )

noexcept

Attempts to return a pointer to the object registered with the rmi_handle that h refers to.

This function will return a pointer to the object even if the requesting code executes in a gang other than the one that the object was registered in. The only requirement is that the location the object registered in and the location that the caller executes in are scheduled on the same thread.

Warning

If h is an invalid handle, nullptr is returned instead of an error.

Parameters

h	Reference to an rmi_handle.

Returns

A pointer to the object associated with the rmi_handle.

resolve_handle() [4/4]

template<typename T >

T* stapl::resolve_handle ( rmi_handle::light_reference const &  h )

noexcept

Attempts to return a pointer to the object registered with the rmi_handle that h refers to.

This function will return a pointer to the object even if the requesting code executes in a gang other than the one that the object was registered in. The only requirement is that the location the object registered in and the location that the caller executes in are scheduled on the same thread.

Warning

If h is an invalid handle, nullptr is returned instead of an error.

Parameters

h	Reference to an rmi_handle.

Returns

A pointer to the object associated with the rmi_handle.

compare_gangs()

int stapl::compare_gangs ( rmi_handle::const_reference const &  x, rmi_handle::const_reference const &  y  )

noexcept

Returns if the two handles are defined over identical, similar or completely different gangs.

Returns

0 if the gangs of the two objects are identical, 1 if the gangs are similar (they exist on the same processing elements) or -1 if the gangs are completely different or information is not enough.