PGAS-Specific Methods and Types

Enumerations
enum	cd::PGASUsageT { cd::kShared = 0, cd::kPotentiallyShared, cd::kPrivatized, cd::kPrivate }
	Different types of PGAS memory behavior for relaxed CDs. More...

Functions
CDErrT	cd::CDHandle::SetPGASUsage (void *data_ptr, uint64_t len, PGASUsageT region_type=kShared)
	Declare how a region of memory behaves within this CD (for Relaxed CDs) More...
CDErrT	cd::CDHandle::SetPGASOwnerWrites (void *data_ptruint64_t len, bool owner_writes=true)
	Simplify optimization of discarding relaxed CD log entries. More...

Detailed Description

Enumeration Type Documentation

enum cd::PGASUsageT

Different types of PGAS memory behavior for relaxed CDs.

Please see the CD semantics document at http://lph.ece.utexas.edu/public/CDs for a full description of PGAS semantics. In brief, because of the logging/tracking requirements of relaxed CDs, it is important to identify which memory accesses may be for communication between relaxed CDs vs. memory accesses that are private (or temporarily privatized) within this CD.

Enumerator
kShared	Definitely shared for actual communication.
kPotentiallyShared	CD, essentially equivalent to kShared for CDs. Perhaps used for communication by this
kPrivatized	communication during this CD. Shared in general, but not used for any
kPrivate	Entirely private to this CD.

Function Documentation

CDErrT cd::CDHandle::SetPGASOwnerWrites	(	void *data_ptruint64_t	len,
		bool	owner_writes = true
	)

Simplify optimization of discarding relaxed CD log entries.

When using relaxed CDs, the CD runtime may log all communication with tasks that are in a different CD context. While privatizing some accesses reduces logging volume, all logged entries must still be propagated and preserved up the CD tree for distributed recovery. Log entries may be discarded when both the task that produced the data and the task that logged it are in the same CD (after descendant CDs complete and "merge"). This can always be guaranteed when the least-common strict ancestor is reached, but may happen sooner. In order to identify the earliest opportunity to discard a log entry, the CD runtime must track producers, which is impractical in general. In the specific and common scenario of "owner computes", however, it is possible to track the producer with low overhead. The SetPGASOwnerWrites() method i used to indicate this behavior.

Returns

kOK on success.

Parameters

[in]	len	pointer to data to be "Typed"; __currently must be in same address space as calling task, but will extend to PGAS fat pointers later [in] Length of preserved data (Bytes)
[in]	owner_writes	Is the current CD the only CD in which this address range is written (until strict ancestor is reached)?

CDErrT cd::CDHandle::SetPGASUsage	(	void *	data_ptr,
		uint64_t	len,
		PGASUsageT	region_type = kShared
	)

Declare how a region of memory behaves within this CD (for Relaxed CDs)

Declare the behavior of a region of PGAS/GAS memory within this CD to minimize logging/tracking overhead. Ideally, only those memory accesses that really are used to communicate between this relaxed CD and another relaxed CD are logged/tracked.

Warning

For now, we are using an address to mark the type, but it is quite possible that using actual types and casting is better. Unfortunately types cannot be done through an API interface and require a change to the language. It is not clear how much overhead will be saved through just this API technique and we will explore language changes (see discussion below).

In the UPC++ implementation, this API call should not be used, and a cast from shared_array to privatized_array (or shared_var to privatized_var) is preferred. UPC++ implementation should be quite straight-forward

Todo:

Do we want to expose explicit logging functions?

Discussion on 3/11/2014:

Just in UPC runtime, perhaps cram a field that says log vs. unlogged into the pointer representation (steal one bit). That we can perhaps do just in the runtime. A problem is that all pointer operations (e.g., comparisons) need to know about this bit.

If adding to the compiler, then should be done at same point as strict and relaxed are done.

There is also a pragma that can be used for changing the default behavior from shared to privatized (assuming that all or at least vast majority of accesses) within a code block are such. This might be easier than casting.

Parameters

[in]	data_ptr	pointer to data to be "Typed"; __currently must be in same address space as calling task, but will extend to PGAS fat pointers later
[in]	len	Length of preserved data (Bytes)
[in]	region_type	How is this memory range used (shared for comm or not?)