par::step::array< T > Class Template Reference

This class represents a distributed array. More...

#include <par_step_array.h>

Inheritance diagram for par::step::array< T >:

Inheritance graph
[legend]
Collaboration diagram for par::step::array< T >:

Collaboration graph
[legend]

List of all members.

Public Member Functions

void allocate (void)
void allocate (off_t nn)
 Allocate memory for an existing array.
 array (sys::cref< par::step::index_range > r)
 array (sys::cref< par::step::index_range > r, par::mem::chunk< T > &c)
 array (array const &other)
 Construct from another array. This is *not* copied but points to the same memory.
 array (char const *URL)
 Construct an array from a file, equivalent parts on each parXXL process.
 array (char const *URL, off_t offs, off_t len)
 Construct an array from a file.
 array (par::mem::chunk< T > const &other)
 Construct an array from another. This is *not* copied but points to the same memory.
 array (array const &other, off_t off, off_t len)
 array (par::mem::chunk< T > const &other, off_t off, off_t len)
 Construct an array from an existing chunk. This is *not* copied but points to the same memory.
 array (par::cntrl::info const &inf)
 array (void)
 array (par::cntrl::info const &inf, off_t nn)
 array (off_t nn)
 The simplest one. Construct array with local size nn and allocate memory to it.
chunk< T > & deepcopy (T *there, off_t amount)
chunk< T > & deepcopy (par::mem::chunk< Tconst > &there)
size_t deepcopy (array< T const > const &other)
 Copy an array into a new one.
chunk duplicate (chunk< Tconst > const &other)
 Let this par::mem::chunk point to exactly the same window of other.
bool extend (off_t nsize) throw (sys::error)
void force_next_round (void) const
T * get (void) const
proc_data & get_context (void) const
proc_data_p get_local (void) const
 Get more detailed information about this parXXL process.
FILE * get_out (void) const
sys::cref< index_rangeget_range (void) const
int get_round (void) const
int get_tag (void) const
Tvolatile * get_volatile (void) const
mem::chunk< void > & getRecv (proc_t w) const
 The par::mem:chunk< void > that is to be received in this superstep from process w.
mem::chunk< void > * getRecvs (void) const
Tconst * getro (void) const
Tvolatile const * getro_volatile (void) const
mem::chunk< void > & getSend (proc_t w) const
 The par::mem:chunk< void > that is to be sent in this superstep to process w.
mem::chunk< void > * getSends (void) const
off_t global_index (off_t const v) const
off_t globalSize (void) const
bool is_here (off_t const v) const
off_t Length () const
void link (char const *URL)
 Let this par::mem::chunk point to exactly the same whole object refered to by other.
off_t local_index (off_t const v) const
off_t localSize (void) const
T * map (void)
 Map the chunk writable (if not yet done) and return a pointer to the memory.
Tvolatile * map_volatile (void)
Tconst * mapro (void)
 Map the chunk readonly (if not yet done) and return a pointer to the memory.
Tvolatile const * mapro_volatile (void)
size_t mynum (void) const
 The id of this particular parXXL process.
off_t myOffset (void) const
size_t np (void) const
 The number of parXXL processes in this parXXL run.
size_t np1 (void) const
 The number of parXXL processes plus one in this parXXL run.
size_t npm1 (void) const
 The number of parXXL processes minus one in this parXXL run.
off_t Offset () const
 operator chunk< Tconst > & (void)
 operator chunk< Tconst >const & (void) const
 operator par::step::array< T const > & (void)
 Propagation to corresponding par::step::array< T const>.
 operator par::step::array< T const > const & (void) const
 operator sys::cref< par::step::index_range > (void) const
bool operator!= (chunk< oT > const &other) const
 The negation of both types of operator==.
chunk & operator<< (par::mem::chunk< Tconst > &there)
 An alias for par::mem::chunk<T>::deepcopy().
arrayoperator<< (par::step::array< T const > const &there)
 An alias for par::step::array<T>::deepcopy().
arrayoperator= (par::mem::chunk< T > const &other)
arrayoperator= (array const &other)
 Link the array to the same memory as other.
bool operator== (chunk< oT > const &other) const
 Two chunks of different type will never be considered the same.
bool operator== (chunk< T > const &other) const
 Two chunks over the same T type are the same if they point to the same heap and have same offset and length. No dynamic type checking is necessary.
void pop_state (void)
void prefetch (void)
void push_state (unsigned salt)
void reset (void)
 Reset the array to be empty.
void set_out (FILE *of=NULL)
par::mem::chunk< T > * split (size_t s, off_t const *const cnts, par::mem::chunk< T > *ret) const
 Split chunk into chunks of given sizes.
par::mem::chunk< T > * split (size_t s, off_t const *const cnts) const
 Split chunk into chunks of given sizes.
apointer< T > temp (off_t off) const
apointer< T > temp (off_t off, off_t len) const
 Create a temporary to be used in a expression that expects a T* or similar.
apointer< T > temp (void) const
bool truncate (off_t nsize) throw (sys::error)
void unmap (void)
 Unmap a chunk previously mapped with map(). Produces an error if memory is not mapped.
void unmapro (void)
 Unmap a chunk previously mapped with mapro(). Produces an error if memory is not mapped.
char const * url (void)
bool valid (long const proc) const
bool valid (ulong const proc) const
bool valid (int const proc) const
bool valid (unsigned const proc) const
bool valid (void) const
chunk window (char const *URL, off_t off, off_t len) throw (sys::error)
 Let this par::mem::chunk point to a window inside the object refered by URL.
chunk & window (chunk< Tconst > const &other, off_t off)
chunk & window (chunk< Tconst > const &other, off_t off, off_t len)
 Let this par::mem::chunk point to a window inside the window of other.
 ~array ()

Static Public Member Functions

static void static_init (void)
static void static_init (void)

Friends

req::context * req::context::generate (size_t sessionId, size_t sessionSize, size_t mynum)


Detailed Description

template<class T>
class par::step::array< T >

This class represents a distributed array.

Every parXXL process holds its share array::localSize() of the array which must not necessarily be the same size for all parXXL processes. On each parXXL process, the local part of the array is realized as a par::mem::chunk.

We maintain two ideas of indexing in such an array:

The necessary index calculations are done by the class par::step::index_range from which this class inherits. The methods index_range::local_index and index_range::global_index translate between these two different forms of indexing.

To access the (local) data that is given by the local par::mem::chunk use the class par::mem::apointer. It will ensure that the data is mapped into adress space and can then be used almost like a normal C pointer.

Definition at line 70 of file par_step_array.h.


Constructor & Destructor Documentation

template<class T>
par::step::array< T >::array ( off_t  nn  )  [inline]

The simplest one. Construct array with local size nn and allocate memory to it.

Parameters:
nn The size of the local share of the array on this parXXL process.

Definition at line 139 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( par::cntrl::info const &  inf,
off_t  nn 
) [inline]

Definition at line 147 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( void   )  [inline]

Definition at line 155 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( par::cntrl::info const &  inf  )  [inline]

Definition at line 163 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( par::mem::chunk< T > const &  other,
off_t  off,
off_t  len 
) [inline]

Construct an array from an existing chunk. This is *not* copied but points to the same memory.

Parameters:
other is a chunk from which this new one will inherit the mem::req.
off Offset from where to start the local array.
len The size of the local share of the array on this parXXL process.

Definition at line 177 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( array< T > const &  other,
off_t  off,
off_t  len 
) [inline]

Definition at line 186 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( par::mem::chunk< T > const &  other  )  [inline]

Construct an array from another. This is *not* copied but points to the same memory.

This constructor does not communicate but uses just the information that is present in ``other''.

To obtain a real copy of the data use par::step::array<T>::operator<<(par::step::array<T const> const&) as e.g in the following:

 array< int > theNewOne(other.localSize());
 theNewOne << other;

Definition at line 209 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( char const *  URL,
off_t  offs,
off_t  len 
) [inline]

Construct an array from a file.

This file is *not* copied into memory, but by some magic called mmap() the memory is identical to the file itself.

For the local initialization on this parXXL processes the same rules as for par::mem::chunk< T >::chunk(char const*, off_t, off_t) apply.

Definition at line 225 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( char const *  URL  )  [inline]

Construct an array from a file, equivalent parts on each parXXL process.

In fact, the parts on the parXXL processes may not be exactly the same. We are rounding down to multiples of the pagesize.

Warning:
This is not yet tested.

Definition at line 241 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( array< T > const &  other  )  [inline]

Construct from another array. This is *not* copied but points to the same memory.

Definition at line 259 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( sys::cref< par::step::index_range r,
par::mem::chunk< T > &  c 
) [inline]

Definition at line 267 of file par_step_array.h.

template<class T>
par::step::array< T >::array ( sys::cref< par::step::index_range r  )  [inline]

Definition at line 277 of file par_step_array.h.

template<class T>
par::step::array< T >::~array (  )  [inline]

Definition at line 325 of file par_step_array.h.


Member Function Documentation

template<class T>
void par::step::array< T >::allocate ( void   )  [inline]

Definition at line 315 of file par_step_array.h.

template<class T>
void par::step::array< T >::allocate ( off_t  nn  )  [inline]

Allocate memory for an existing array.

Warning:
All parXXL processes have to call this simultaneously since this is inherently a superstep (for the communication of the sizes).

Definition at line 308 of file par_step_array.h.

chunk<T >& par::mem::chunk< T >::deepcopy ( T *  there,
off_t  amount 
) [inline, inherited]

Definition at line 535 of file par_mem_chunk.h.

chunk<T >& par::mem::chunk< T >::deepcopy ( par::mem::chunk< T const > &  there  )  [inline, inherited]

Definition at line 528 of file par_mem_chunk.h.

template<class T>
size_t par::step::array< T >::deepcopy ( array< T const > const &  other  )  [inline]

Copy an array into a new one.

This copies the data and doesn't simply link it. Use it to re-distribute your array in a different way on the parXXL processes. As an example here we redistribute the ellements of an array equally among the parXXL processes.

 par::step::array< double > A( something );

 do_a_lot_of_things_with_A


 par::step::array< double > B(
        par::cntrl::mynum() != par::cntrl::np1()
        ? A.globalSize()/par::cntrl::np()
        : A.globalSize() - (A.globalSize()/par::cntrl::np())*np1()
        );

 B << A;

Think of the arrays as virtual global arrays where the chunks of the individual parXXL processes are ordered according to the parXXL process numbers. The size of these virtual arrays must be the same. The copy operation is done such the relative ordering in the virtual source is respected and found in exactly the same ordering of the target array.

Eg suppose we have three parXXL processes and the respective sizes of other on the different parXXL processes is 5 10 and 11, the size of (*this) is 7 13 and 6. Then all the 5 elements from parXXL process 0, and the first 2 elements from parXXL process 1 are found in the target array on parXXL process 0. The next 8 elements of parXXL process 1 and the first 5 elements from parXXL process 2 are copied to the target array on parXXL process 1. The remaining 6 elements of parXXL process 2 are copied to the target array on the same parXXL process.

      ///    proc 0            proc 1                   proc 2
      /// |a|b|c|d|e|   |f|g|h|i|j|k|l|m|n|o|   |p|q|r|s|t|u|v|w|x|y|z|      other
      ///  | | | | |     / / | | | | | | | |    / / / / /  | | | | | |
      ///  | | | | |    / /  | | | | | | | |   / / / / /   | | | | | |
      ///  | | | | |   / /   | | | | | | | |  / / / / /    | | | | | |
      /// |a|b|c|d|e|f|g|   |h|i|j|k|l|m|n|o|p|q|r|s|t|   |u|v|w|x|y|z|      (*this)
      ///      proc 0                   proc 1                proc 2
      /// 
Precondition:
The global size of the source array must be smaller or equal to the size of the target array. In case that it is smaller the exceeding part of the target array is left untouched.
Returns:
The size locally received on this proc.

Definition at line 427 of file par_step_array.h.

chunk par::mem::chunk< T >::duplicate ( chunk< T const > const &  other  )  [inline, inherited]

Let this par::mem::chunk point to exactly the same window of other.

Returns a reference to the calling object, to be compatible with par::mem::duplicate.

Definition at line 241 of file par_mem_chunk.h.

bool par::mem::chunk< T >::extend ( off_t  nsize  )  throw (sys::error) [inline, inherited]

Extend the size of the underlying object if possible.

Use with care and always check the return value.

Precondition:
  • This chunk must have write access to the object.
  • The object must not be mapped by this chunk.
  • The chunk must link to the entire object, i.e Offset() must be zero and Length() must be the length of the object.
Warning:
Any lock that might be held by somebody external to parXXL (eg. if the object is a file) may block this parXXL process.
Returns:
value of true means the call is on error.
Any other chunk that was previously refering to the entire object, will not do so after a successful call to extend. So such a chunk by consequence will loose the capacity to call truncate or extend successfully. On the other hand mappings that such a chunk had previously should be unaffected and continue to be valid.

This call might systematically fail for certain types of objects. E.g for types that are not extensible without copying the whole data, in particular for par::sys::heap, or for those where a possible strategy is not yet implemented.

Parameters:
addon The new amount of items of type T.

Definition at line 384 of file par_mem_chunk.h.

T * par::mem::chunk< T >::get ( void   )  const [inline, inherited]

Reimplemented in par::mem::apointer< T >.

Definition at line 445 of file par_mem_chunk.h.

template<class T>
sys::cref< index_range > par::step::array< T >::get_range ( void   )  const [inline]

Definition at line 78 of file par_step_array.h.

T volatile* par::mem::chunk< T >::get_volatile ( void   )  const [inline, inherited]

Definition at line 481 of file par_mem_chunk.h.

T const* par::mem::chunk< T >::getro ( void   )  const [inline, inherited]

Definition at line 469 of file par_mem_chunk.h.

T volatile const* par::mem::chunk< T >::getro_volatile ( void   )  const [inline, inherited]

Definition at line 475 of file par_mem_chunk.h.

template<class T>
off_t par::step::array< T >::global_index ( off_t const   v  )  const [inline]

Definition at line 100 of file par_step_array.h.

template<class T>
off_t par::step::array< T >::globalSize ( void   )  const [inline]

Definition at line 84 of file par_step_array.h.

template<class T>
bool par::step::array< T >::is_here ( off_t const   v  )  const [inline]

Definition at line 105 of file par_step_array.h.

off_t par::mem::chunk< T >::Length ( void   )  const [inline, inherited]

Reimplemented in par::mem::apointer< T >.

Definition at line 392 of file par_mem_chunk.h.

void par::mem::chunk< T >::link ( char const *  URL  )  [inline, inherited]

Let this par::mem::chunk point to exactly the same whole object refered to by other.

If T has the const attribute, the object is accessed read-only. If in that case URL does not exist, it is not created but an empty par::mem::chunk is returned. Test for such a situation with Length().

Definition at line 253 of file par_mem_chunk.h.

template<class T>
off_t par::step::array< T >::local_index ( off_t const   v  )  const [inline]

Definition at line 95 of file par_step_array.h.

template<class T>
off_t par::step::array< T >::localSize ( void   )  const [inline]

Definition at line 80 of file par_step_array.h.

T * par::mem::chunk< T >::map ( void   )  [inline, inherited]

Map the chunk writable (if not yet done) and return a pointer to the memory.

Definition at line 426 of file par_mem_chunk.h.

T volatile* par::mem::chunk< T >::map_volatile ( void   )  [inline, inherited]

Definition at line 478 of file par_mem_chunk.h.

T const* par::mem::chunk< T >::mapro ( void   )  [inline, inherited]

Map the chunk readonly (if not yet done) and return a pointer to the memory.

Definition at line 466 of file par_mem_chunk.h.

T volatile const* par::mem::chunk< T >::mapro_volatile ( void   )  [inline, inherited]

Definition at line 472 of file par_mem_chunk.h.

template<class T>
size_t par::step::array< T >::mynum ( void   )  const [inline]

The id of this particular parXXL process.

Reimplemented from par::cntrl::info.

Definition at line 118 of file par_step_array.h.

template<class T>
off_t par::step::array< T >::myOffset ( void   )  const [inline]

Definition at line 109 of file par_step_array.h.

template<class T>
size_t par::step::array< T >::np ( void   )  const [inline]

The number of parXXL processes in this parXXL run.

Reimplemented from par::cntrl::info.

Definition at line 114 of file par_step_array.h.

template<class T>
size_t par::step::array< T >::np1 ( void   )  const [inline]

The number of parXXL processes plus one in this parXXL run.

Reimplemented from par::cntrl::info.

Definition at line 122 of file par_step_array.h.

template<class T>
size_t par::step::array< T >::npm1 ( void   )  const [inline]

The number of parXXL processes minus one in this parXXL run.

Reimplemented from par::cntrl::info.

Definition at line 126 of file par_step_array.h.

off_t par::mem::chunk< T >::Offset (  )  const [inline, inherited]

Definition at line 393 of file par_mem_chunk.h.

par::mem::chunk< T >::operator chunk< T const > & ( void   )  [inherited]

Const casting a chunk.

The weakness of C++ as a language make it necessary to define this operator. It ensure that a chunk< T > can be used everywhere a chunk< T const > is requested. E.g the copy operator chunk<T>& chunk<T>::operator<<(chunk< T const >&) needs a writable chunk on the left hand side but it may have a readonly or writable on the right.

par::mem::chunk< T >::operator chunk< T const >const & ( void   )  const [inherited]

template<class T >
par::step::array< T >::operator par::step::array< T const > & ( void   )  [inline]

Propagation to corresponding par::step::array< T const>.

Definition at line 412 of file par_step_array.h.

template<class T >
par::step::array< T >::operator par::step::array< T const > const & ( void   )  const [inline]

Definition at line 418 of file par_step_array.h.

template<class T>
par::step::array< T >::operator sys::cref< par::step::index_range > ( void   )  const [inline]

Definition at line 130 of file par_step_array.h.

bool par::mem::chunk< T >::operator!= ( chunk< oT > const &  other  )  const [inline, inherited]

The negation of both types of operator==.

Definition at line 522 of file par_mem_chunk.h.

chunk& par::mem::chunk< T >::operator<< ( par::mem::chunk< T const > &  there  )  [inline, inherited]

An alias for par::mem::chunk<T>::deepcopy().

Definition at line 544 of file par_mem_chunk.h.

template<class T>
array& par::step::array< T >::operator<< ( par::step::array< T const > const &  there  )  [inline]

An alias for par::step::array<T>::deepcopy().

Definition at line 402 of file par_step_array.h.

template<class T>
array& par::step::array< T >::operator= ( par::mem::chunk< T > const &  other  )  [inline]

Reimplemented from par::mem::chunk< T >.

Definition at line 340 of file par_step_array.h.

template<class T>
array& par::step::array< T >::operator= ( array< T > const &  other  )  [inline]

Link the array to the same memory as other.

Data is not copied. To copy the array, use operator<< instead.

Definition at line 332 of file par_step_array.h.

bool par::mem::chunk< T >::operator== ( chunk< oT > const &  other  )  const [inline, inherited]

Two chunks of different type will never be considered the same.

Definition at line 515 of file par_mem_chunk.h.

bool par::mem::chunk< T >::operator== ( chunk< T > const &  other  )  const [inline, inherited]

Two chunks over the same T type are the same if they point to the same heap and have same offset and length. No dynamic type checking is necessary.

Definition at line 507 of file par_mem_chunk.h.

void par::mem::chunk< T >::prefetch ( void   )  [inline, inherited]

Definition at line 395 of file par_mem_chunk.h.

template<class T>
void par::step::array< T >::reset ( void   )  [inline]

Reset the array to be empty.

You have to call allocate before being able to use this array again.

Warning:
All parXXL processes have to call this simultaneously since invalidates the array.

Definition at line 298 of file par_step_array.h.

par::mem::chunk< T >* par::mem::chunk< T >::split ( size_t  s,
off_t const *const  cnts,
par::mem::chunk< T > *  ret 
) const [inline, inherited]

Split chunk into chunks of given sizes.

Parameters:
s The number of chunks to split into.
cnts A vector of the s different sizes of these chunks.
ret A vector of chunks of size s. These chunks will be completely reininialized.

Definition at line 576 of file par_mem_chunk.h.

par::mem::chunk< T >* par::mem::chunk< T >::split ( size_t  s,
off_t const *const  cnts 
) const [inline, inherited]

Split chunk into chunks of given sizes.

Parameters:
s The number of chunks to split into.
cnts A vector of the s different sizes of these chunks.
Returns:
freshly allocated (with new) vector of chunks. Should be freed with delete[] before this chunk ceases existing.

Definition at line 562 of file par_mem_chunk.h.

static void par::mem::chunk< T >::static_init ( void   )  [static, inherited]

static void par::cntrl::info::static_init ( void   )  [static, inherited]

apointer< T > par::mem::chunk< T >::temp ( off_t  off  )  const [inherited]

apointer< T > par::mem::chunk< T >::temp ( off_t  off,
off_t  len 
) const [inherited]

Create a temporary to be used in a expression that expects a T* or similar.

If used in an expression that expects a T* the effect will be to map the chunk and provide the address of the data in question. Usually you should not use this to access individual items in the par::mem::chunk, since this would be very inefficient.

apointer< T > par::mem::chunk< T >::temp ( void   )  const [inherited]

bool par::mem::chunk< T >::truncate ( off_t  nsize  )  throw (sys::error) [inline, inherited]

Change the size of the underlying object.

Only use this if you realy need to.

See also:
par::mem::req::truncate() for a description of the mechanism.
Precondition:
  • This chunk must have write access to the object.
  • The underlying object must be uniquely linked by this chunk.
  • The object must not be mapped.
  • The chunk must link to the entire object, i.e Offset() must be zero and Length() must be the length of the object.
Warning:
Any lock that might be held by somebody external to parXXL (eg. if the object is a file) may block this parXXL process.
Postcondition:
On success, a lock was obtained for the memory object. This lock is released before returning from this call.
Returns:
value of true means the call is on error.

Parameters:
nsize The new size of the object counted in items of type T.

Definition at line 374 of file par_mem_chunk.h.

void par::mem::chunk< T >::unmap ( void   )  [inline, inherited]

Unmap a chunk previously mapped with map(). Produces an error if memory is not mapped.

Definition at line 486 of file par_mem_chunk.h.

void par::mem::chunk< T >::unmapro ( void   )  [inline, inherited]

Unmap a chunk previously mapped with mapro(). Produces an error if memory is not mapped.

Definition at line 500 of file par_mem_chunk.h.

char const* par::mem::chunk< T >::url ( void   )  [inline, inherited]

Definition at line 592 of file par_mem_chunk.h.

template<class T>
bool par::step::array< T >::valid ( void   )  const [inline]

Definition at line 88 of file par_step_array.h.

chunk par::mem::chunk< T >::window ( char const *  URL,
off_t  off,
off_t  len 
) throw (sys::error) [inline, inherited]

Let this par::mem::chunk point to a window inside the object refered by URL.

If T has the const attribute, the object is accessed read-only. If in that case URL does not exist, it is not created but an empty par::mem::chunk is returned. Test for such a situation with Length().

Returns a reference to the calling object, to be compatible with par::mem::window.

Definition at line 226 of file par_mem_chunk.h.

chunk& par::mem::chunk< T >::window ( chunk< T const > const &  other,
off_t  off 
) [inline, inherited]

Definition at line 207 of file par_mem_chunk.h.

chunk& par::mem::chunk< T >::window ( chunk< T const > const &  other,
off_t  off,
off_t  len 
) [inline, inherited]

Let this par::mem::chunk point to a window inside the window of other.

Returns a reference to the calling object, to be compatible with par::mem::window.

Definition at line 199 of file par_mem_chunk.h.


Friends And Related Function Documentation

req::context* req::context::generate ( size_t  sessionId,
size_t  sessionSize,
size_t  mynum 
) [friend, inherited]


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

Generated on Tue Oct 13 22:04:21 2009 for parXXL by  doxygen 1.5.8