class BoxLayout

A not-necessarily disjoint collective of boxes

Inheritance:

BoxLayout


public members:

BoxLayout()
BoxLayout(const Vector <Box>& a_boxes, const Vector <int>& a_procIDs)
virtual ~BoxLayout()
BoxLayout& operator=(const BoxLayout& a_rhs)
refcounted assignment
virtual void define(const Vector <Box>& a_boxes, const Vector <int>& a_procIDs)
const Box& operator[](const LayoutIndex& it) const
Box& operator[](const LayoutIndex& it)
inline bool operator==(const BoxLayout& rhs) const
DataIndex addBox(const Box& box , int procID )
virtual void close()
virtual void deepCopy(const BoxLayout& a_source)
Box get(const LayoutIndex& it) const
bool isSorted() const
DataIterator dataIterator() const
LayoutIterator layoutIterator() const
ifndef WRAPPER void print() const
invokes cout<<*this; pretty-print dump of BoxLayout
unsigned int procID(const LayoutIndex& a_index) const
int numBoxes(const int procID ) const
void setProcID(const LayoutIndex& a_index, unsigned int a_procID)
inline unsigned int size() const
void sort()
friend void coarsen(BoxLayout& output, const BoxLayout& input, int refinement)
friend void refine(BoxLayout& output, const BoxLayout& input, int refinement)

Documentation

A BoxLayout is a collection of Box objects that are assigned to a process number. Each box is associated with only one process. processes are numbered from 0 to n-1 (for an n process parallel job)

BoxLayout can be either open or closed. null construction or deepcopy creates an open BoxLayout. Boxes may be added to an open BoxLayout. non-const operations may be performed on the boxes existing in an open BoxLayout. closed BoxLayouts are sorted. Many uses of BoxLayouts require a closed BoxLayout. A closed BoxLayout cannot be modified.

Ref-counting ------------ BoxLayout is an explicitly ref-counted object.

Assignment and copy are compiler generated. They increment the refcount on the contained data members. They perform shallow, ref-counted operations.

Refcounting is a process whereby multiple instaniations make use of a single implementation of that object and keep a tally of how many instantiations are sharing. Thus

  BoxLayout b1(boxes, procIDs);

            b1  ----> refcount = 1
                ---->  m_boxes
                ---->  m_processors

  BoxLayout b2(b1)

            b1  ----> refcount = 2  <---- b2
                ---->  m_boxes      <----
                ---->  m_processors <----

  BoxLayout b3;
  b3 = b2;

            b1  ----> refcount = 3  <---- b2
                ---->  m_boxes      <----
                ---->  m_processors <----
                        ^^^
                        |||
                         b3
  
BoxLayout (const Vector <Box>& a_boxes, const Vector <int>& a_procIDs)
Construct from a Vector of Boxes and a Vector of processor assignments. On exit, the BoxLayout will be closed.

virtual ~BoxLayout ()
Ref-counted destruction. Once the last reference to the implementation of this class is destroyed, the data members are cleaned up

BoxLayout& operator= (const BoxLayout& a_rhs)

virtual void define (const Vector <Box>& a_boxes, const Vector <int>& a_procIDs)
Define this BoxLayout from a Vector of Boxes and a Vector of processor assignments. Any pre-existing layout will be lost (ref-count dropped by one). The processor assignment Vector must be the same length as the Box Vector. On exit, the BoxLayout will be closed.

const Box& operator[] (const LayoutIndex& it) const
const accessor operator. see also get(const DataIndex&)

inline bool operator== (const BoxLayout& rhs) const
Refcounted pointer check. True if these two objects share the same implementation.

DataIndex addBox (const Box& box , int procID )
add a box to this BoxLayout. Takes the processor assignment. The input 'box' is copied. BoxLayout must be 'open' for this operation, otherwise a runtime error will occur.

virtual void close ()
Mark this BoxLayout as complete and unchangeable.

virtual void deepCopy (const BoxLayout& a_source)
Actual deep copy operation. New object created with copied data. This object disassociates itself with original implementation safely. This object now is considered 'open' and can be non-const modified. There is no assurance that the order in which this BoxLayout is indexed corresponds to the indexing of a_source.

BoxLayout b1(boxes, procIDs);

            b1  ----> refcount = 1
                ---->  m_boxes
                ---->  m_processors

       BoxLayout b2(b1)

            b1  ----> refcount = 2  <---- b2
                ---->  m_boxes      <----
                ---->  m_processors <----

       BoxLayout b3;
       b3.deepCopy(b2);
            b1  ----> refcount = 2  <---- b2  b3 ----> refcount = 1 
                ---->  m_boxes      <----        ---->  m_boxes
                ---->  m_processors <----        ---->  m_processors

Box get (const LayoutIndex& it) const
As a consquence of the C++ compiler being free to choose which version of operator[] when the object is technically non-const, we very often get 'BoxLayout closed' errors. This is a non-overloaded get method. return true if close() has been called. closed BoxLayout is always sorted.

bool isSorted () const
return true if sort() has been called

LayoutIterator layoutIterator () const
If BoxLayout is closed, then LayoutIterator will return the Box's in sorted order. Processes through ALL the boxes in a BoxLayout

unsigned int procID (const LayoutIndex& a_index) const
Returns the processor to which this box has been assigned. Not a user function, at least, not a new user function. It can be used safely at anytime, closed or open. A person needing this level of knowledge of the processor assignment should have non-trivial needs, like writing your own load balancer or such. Most user level parallel coding needs can be addressed using the DataIterator class.

void setProcID (const LayoutIndex& a_index, unsigned int a_procID)
Assign a Box in the BoxLayout to a processor. Requires the BoxLayout to be open.

void sort ()
Sort the boxes.

friend void coarsen (BoxLayout& output, const BoxLayout& input, int refinement)
'output' must be open, 'input' must be closed, 'refinement' must be a positive non-zero integer. 'output' and 'input' do not share an implementation. 'output' is first deepcopy'ed from 'input', then coarsen(refinement) is called on each box of 'output'. 'output' returns from this function closed. LayoutIterators from 'input' and 'output' can perform interchangeably.

friend void refine (BoxLayout& output, const BoxLayout& input, int refinement)
see 'coarsen(BoxLayout& output, const BoxLayout& input, int refinement) ' and substitute the word "refine" for "coarsen"


this class has no child classes.

alphabetic index hierarchy of classes


Chombo

Copyright Notice

This software is copyright (C) by the Lawrence Berkeley National Laboratory. Permission is granted to reproduce this software for non-commercial purposes provided that this notice is left intact.

It is acknowledged that the U.S. Government has rights to this software under Contract DE-AC03-765F00098 between the U.S. Department of Energy and the University of California.

This software is provided as a professional and academic contribution for joint exchange. Thus it is experimental, is provided ``as is'', with no warranties of any kind whatsoever, no support, no promise of updates, or printed documentation. By using this software, you acknowledge that the Lawrence Berkeley National Laboratory and Regents of the University of California shall have no liability with respect to the infringement of other copyrights by any part of this software.