STAPL: stapl::rmi_handle Class Reference

Provides a registration mechanism for RMI communication. More...

Classes
class	const_light_reference
	Const light reference to an object that was registered through rmi_handle. More...

class	light_reference
	Light reference to an object that was registered through rmi_handle. More...

Public Member Functions
constexpr	rmi_handle (void) noexcept
	Constructs a new rmi_handle without registering any object.

template<typename T >
	rmi_handle (T *const t, const unsigned int flags=0)
	Constructs a new rmi_handle which registers `t` in the current gang. More...

template<typename T >
	rmi_handle (runtime::context &ctx, T *const t, const unsigned int flags=0)
	Constructs a new rmi_handle which registers `t` in the gang of the given execution context. More...

	~rmi_handle (void)
	Unregisters the object if it is not yet unregistered.

	rmi_handle (rmi_handle const &)=delete

rmi_handle &	operator= (rmi_handle const &)=delete

runtime::location_md const &	get_location_md (void) const noexcept
	Returns the metadata of the location this object registered in.

runtime::location_md &	get_location_md (void) noexcept
	Returns the metadata of the location this object registered in. noexcept More...

size_type	get_location_id (void) const noexcept
	Returns the location id this object registered in.

void	unregister_object (void)
	Unregisters the object. More...

void	advance_epoch (void)
	Advances the epoch of the object. More...

void	lock (void)
	Disable processing of incoming RMIs on this location so that local computation is guaranteed to run atomically with respect to incoming requests.

bool	try_lock (void)
	Attempt to disable processing of incoming RMIs on this location so that local computation is guaranteed to run atomically with respect to incoming requests. More...

void	unlock (void)
	Reenable processing of incoming RMIs on this location.

void	set_flags (const unsigned int flags) noexcept
	Sets the flags for this object.

constexpr unsigned int	get_flags (void) const noexcept
	Returns the flags of this object.

constexpr size_type	get_num_locations (void) const noexcept
	Returns the size of the gang this object registered in.

constexpr bool	is_valid (const size_type n) const noexcept
	Returns if the given location id is valid for the gang this object registered in.

constexpr bool	valid (void) const noexcept
	Returns `true` if this handle is associated with an object.

constexpr internal_handle_type const &	internal_handle (void) const noexcept

constexpr epoch_type	get_registration_epoch (void) const noexcept
	Returns the epoch that the object was registered in.

constexpr epoch_type	get_epoch (void) const noexcept
	Returns the epoch that the object is currently in.

constexpr gang_id	get_gang_id (void) const noexcept
	Returns the gang id of the gang this object registered in.

std::string	get_uid (void) const
	Returns a unique id of the registered object. More...

Public Types
using	const_reference = runtime::rmi_handle_base
	Const reference to an object that was registered through rmi_handle. More...

using	reference = runtime::rmi_handle_extended_base
	Reference to an object that was registered through rmi_handle. More...

using	size_type = location_id

using	internal_handle_type = object_virtual_address

using	epoch_type = logical_clock::time_type

Protected Member Functions
void	set_epoch (epoch_type e) noexcept
	Sets the epoch that the object is currently in.

Detailed Description

Provides a registration mechanism for RMI communication.

It is the user's responsibility to register an object with the handle. Trying to communicate with an unregistered object or calling any other function except rmi_handle::register_object() and rmi_handle::valid() is undefined behavior.

Registration assumes an SPMD model. Specifically, when an object, comprised of one sub-object per location, tries to register itself, the model expects each location to perform its sub-object registrations in the same order, hence allowing each corresponding sub-object to have the same id. It is a local operation.

This assumption alleviates concerns with scoping and forcing unique names for objects, and allows for faster address translation.

Unregistration is not required to be SPMD, however all the sub-objects of a registered object have to unregister before an rmi_fence().

Registration has amortized $O(1)$ time complexity whereas unregistration has $O(1)$ .

See also: p_object

Member Typedef Documentation

◆ const_reference

using stapl::rmi_handle::const_reference = runtime::rmi_handle_base

Const reference to an object that was registered through rmi_handle.

It can be constructed from any reference to rmi_handle, except rmi_handle::light_reference and rmi_handle::const_light_reference.

Once an rmi_handle::const_reference is created, one can retrieve a const reference to the object and do RMIs to const functions through it.

The size of an rmi_handle::const_reference is bigger than that of an rmi_handle::const_light_reference.

◆ reference

using stapl::rmi_handle::reference = runtime::rmi_handle_extended_base

Reference to an object that was registered through rmi_handle.

It can be constructed from any non-const reference to rmi_handle, except rmi_handle::light_reference.

Once an rmi_handle::reference is created, one can retrieve a reference to the object and do RMIs through it.

The size of an rmi_handle::reference is bigger than that of an rmi_handle::light_reference.

Constructor & Destructor Documentation

◆ rmi_handle() [1/2]

template<typename T >

stapl::rmi_handle::rmi_handle	(	T *const	t,
		const unsigned int	flags = `0`
	)

explicit

Constructs a new rmi_handle which registers t in the current gang.

Parameters

t	Object to be registered.
flags	Registration flags.

◆ rmi_handle() [2/2]

template<typename T >

stapl::rmi_handle::rmi_handle	(	runtime::context &	ctx,
		T *const	t,
		const unsigned int	flags = `0`
	)

Constructs a new rmi_handle which registers t in the gang of the given execution context.

Parameters

ctx	Execution context the registration happens in.
t	Object to be registered.
flags	Registration flags.

Member Function Documentation

◆ get_location_md()

runtime::location_md& stapl::rmi_handle::get_location_md ( void )

noexcept

Returns the metadata of the location this object registered in. noexcept

noexcept

◆ unregister_object()

void stapl::rmi_handle::unregister_object ( void )

Unregisters the object.

If valid()==true before calling this, then valid()==false after calling it. Otherwise, behavior is undefined.

◆ advance_epoch()

void stapl::rmi_handle::advance_epoch ( void )

Advances the epoch of the object.

Advancing the epoch will flush any pending RMIs. It will also increase the epoch of the current gang if the object is not a named object.

◆ try_lock()

bool stapl::rmi_handle::try_lock ( void )

Attempt to disable processing of incoming RMIs on this location so that local computation is guaranteed to run atomically with respect to incoming requests.

Returns: true if the lock was able to be acquired. false if it is already locked.

◆ get_uid()

std::string stapl::runtime::rmi_handle_info::get_uid ( void ) const

inherited

Returns a unique id of the registered object.

Warning: This should not be used to deduce locality information about a handle.

The documentation for this class was generated from the following files:

rmi_handle_fwd.hpp
rmi_handle.hpp

Classes

Public Member Functions

Public Types

Protected Member Functions