DataItems

Data Items

Each data structure managed by AllScale provides four components:

• A facade implementing the interface to the data structure as seen by the domain expert when utilizing it within an application
• A region type providing means to addressing parts of the data structure
• A fragment type capable of maintaining regions of the overall data structure within a single address space of a device.
• A shared data segment type containing read-only information shared among all fragments of a data item instance

The specification of the facade component depends on the data structure. The next three sections capture the specification of the other three components.

Region

Each region class provides the following member functions:

Member function	Description
static Region merge(const Region& a, const Region& b)	Union of the regions a and b
static Region intersect(const Region& a, const Region& b)	Intersection of the regions a and b
bool empty()	Tests whether the region is empty
static Region load(ArchiveReader& reader)	Loads a region from the reader
void store(ArchiveWriter& writer) const	Stores the region to a writer

A concrete implementation of a region class is the GridRegion of the Grid data structure. The following code provides some examples on how the region class can be utilized.

using Region = GridRegion<2>;

Region a({0,0},{2,2});
Region b({2,0},{4,2});

Region ab = Region::merge(a, b);
assert_eq("{[[0,0] - [4,2]]}", toString(ab));

Region a_intersect_b = Region::intersect(a, b);
assert_true(a_intersect_b.empty());

Region ab_intersect_b = Region::intersect(ab, b);
assert_false(ab_intersect_b.empty());
assert_eq(b, ab_intersect_b);

Fragment

Each fragment class provides the following member functions:

Member function	Description
Fragment(const SharedData& shared_data, const Region& size)	A constructor to create a fragment using the given shared data information and covering at least the specified region
void resize(const Region& size)	Resize the cover at least the specified size
Data mask()	Provides access to the data stored within the specified fragment
void extract(ArchiveWriter& writer, const Region& region) const	Extract the specified region of the the fragment and write it to the writer
void insert(ArchiveReader& reader)	Import data into the fragment

The following examples use the GridFragment which is the fragment class of the Grid data structure.

using Point = GridPoint<2>;
using Region = GridRegion<2>;
using Fragment = GridFragment<int,2>;
using SharedData = GridSharedData<2>;

Point size = { 500, 500 };

SharedData shared { size };

// upper half
Region partA({0,0},{250,500});
// lower half
Region partB({250,0},{500,500});

// create fragments
Fragment fA(shared,partA);
Fragment fB(shared,partB);

// initialize
fA.mask().forEach([](auto& p) { p = 1; });
fB.mask().forEach([](auto& p) { p = 2; });

// third region
Region full({0,125},{500,375});

Fragment fC(shared,full);

// insert values of fA and fB
fC.insert(fA,Region::intersect(full,partA));
fC.insert(fB,Region::intersect(full,partB));

auto grid = fC.mask();
for(int i = 0; i < 500; i++) {
    for(int j = 125; j < 375; j++) {
        if(i < 250) {
            // inserted from fA
            assert_eq((grid[{i, j}]), 1);
        }
        else {
            // inserted from fB
            assert_eq((grid[{i, j}]), 2);
        }
    }
}

Shared Data Segments

Each shared data class provides the following member functions:

Member function	Description
void store(ArchiveWriter& writer) const	Write the shared data to the writer
static SharedData load(ArchiveReader& reader)	Load the shared data from the reader

The shared data segment implementation of the Grid data structure is the GridSharedData class. It can be passed as an argument of the GridFragment constructor.

GridPoint<1> size = 50;

GridRegion<1> full(0,50);
GridRegion<1> a(5,10);
GridRegion<1> b(8,14);

GridSharedData<1> shared { size };
GridFragment<int,1> src(shared);
GridFragment<int,1> dst1(shared);
GridFragment<int,1> dst2(shared);

// fix some sizes
src.resize(full);
dst1.resize(a);
dst2.resize(b);