par::step::bulk< E > Class Template Reference
[Dispatching large amounts of information]

Bulk communication from a source array to a target array. More...

#include <par_step_bulk.h>

Inheritance diagram for par::step::bulk< E >:

Inheritance graph
[legend]
Collaboration diagram for par::step::bulk< E >:

Collaboration graph
[legend]

List of all members.

Public Types

typedef E::S S
 The source type of the bulk communication.
typedef E::T T
 The target type of the bulk communication.

Public Member Functions

void count (void)
template<class iterator >
void count (iterator &act)
void distribute (void)
void extraction (mem::chunk< T > *&buf)
template<class iterator >
void extraction (iterator &act, mem::chunk< T > *&buf)
void force_next_round (void) const
proc_data & get_context (void) const
proc_data_p get_local (void) const
 Get more detailed information about this parXXL process.
off_t get_messageLength () const
FILE * get_out (void) const
off_t get_receivLength () const
int get_round (void) const
int get_tag (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
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
par::cntrl::proc_t mynum (void) const
 The id of this particular parXXL process.
par::cntrl::proc_t np (void) const
 The number of parXXL processes in this parXXL run.
par::cntrl::proc_t np1 (void) const
 The number of parXXL processes plus one in this parXXL run.
par::cntrl::proc_t npm1 (void) const
 The number of parXXL processes minus one in this parXXL run.
void pop_state (void)
void push_state (unsigned salt)
void set_out (FILE *of=NULL)
bool valid (long const proc) const
bool valid (ulong const proc) const
bool valid (int const proc) const
bool valid (unsigned const proc) const
virtual ~bulk (void)
Setting and getting target array.
After a call to bulk::set_recvarray() the target array will not be destructed upon the destruction of this bulk. Have a look into sorting::redistribute to see how this function can be used.

If the target array is constructed implicitly and you use bulk::get_recvarray() to receive its address, this reference is only valid as long as the bulk is not destructed.

void allocate ()
 Force allocation and dimensioning of the target array.
array< T > * get_recvarray (void) const
mem::chunk< T > & get_recvchunk (par::cntrl::proc_t whom)
void set_recvarray (array< T > &ra)
void set_recvarray (array< T > *ra=NULL)
Constructors that use array< S >.
 bulk (bulk_generic const &other, array< S > &gga, E &extr)
 bulk (bulk_generic const &other, array< S > &gga)
 bulk (array< S > &gga, E &extr)
Allocation
More sofisticated user interfaces.

Allocate and deallocate the received buffer This will depend on the model of parallelism that we use.

void deallocate (void)
void deallocate_data (void)
 this will not be done automatically on destruction
The primary user interfaces
template<class iterator >
void exchange (iterator &act, bool delsource=false)
void exchange (bool delsource=false)
 Do the real exchange of the data.
template<class iterator >
void finish (iterator &act)
void finish (void)
 do eventual clean up.
template<class iterator >
void initiate (iterator &act)
void initiate (void)
 Initialize the buffers.

Static Public Member Functions

static void static_init (void)

Public Attributes

iterator active
par::step::array< S > & datarray
 The source array of the bulk communication.
E & extractor
 specify the kind of communication.
off_t global
off_t *const total

Protected Attributes

cntrl::matrix< off_texch
off_t *const messageNo
off_t messageSize
off_t const nb_elts
bool own_recv
 Whether recvarray has been allocated by this bulk.
par::mem::chunk< T > * rchunks
 A table of received chunks per source processor.
par::cntrl::proc_t receive_expected
par::cntrl::proc_t receive_expected_here
off_t receiveSize
off_t *const receivNo
par::step::array< T > * recvarray
 The array that receives the data.


Detailed Description

template<class E>
class par::step::bulk< E >

Bulk communication from a source array to a target array.

The source will be par::step::array of base type E::S to a target par::step::array of base type E::T.

par::step::bulk is appropriate for communication of big chunks of data, but where each item of your source array might go to an arbitrary destination parXXL process. If you have whole ranges of your data all going to the same parXXL process consider using par::step::array::deepcopy instead.

For an example of the usage look into the code for par::step::sorting::redistribute.

The source array is usually given upon construction. The target array can either be constructed on the fly when needed (default) and accessed via get_recvarray() or provided by set_recvarray(). In the first case the target is destructed upon destruction of the par::step::bulk, in the later it survives destruction.

Extraction is done by template paramter E which has to provide us with several interfaces. First of all it must provides with the two derived types E::S and E:T. Then it must provide two methods, E::identify and E::extract. A good example for such data type is par::step::sorting_extraction.

  1. int identify(size_t i, S d, size_t nb);
    will provide us with the information of where to send the message corresponding to the data given at position i, assuming that the total amout of data to be send is nb.
  2. void extract(size_t i, int proc, S d, T& m );
    will transform the given data d of type S at position i into the data m of type T to be send to parXXL process proc.

For both methods the parameter d might be given as reference or value depending on how efficient a copy operation of E::S might be implemented.

There are basically two possibilities for extraction classes.

  1. Extraction can be done with the parameters that are passed to identify and extract, resp. Then the definition of the extraction type should not contain any data fields and it should not be necessary to create instances of this class at all. In that case you should definitively declare the methods indentify and extract to be so-called static members, that is methods that are globally available to that class and that do not need any instance of the class to be called. Declarations of the methods would then look like
    static int identify(size_t i, S d, size_t nb);
    static extract(size_t i, int proc, S d, T& m );
  2. Extraction needs more information than the parameters passed to the methods. Then you should have all data present as members of the class and create instances of it. Clearly that then identify and extract *must* *not* be declared static. In such a case you must* creat an object of your E before the creation of a bulk object. Please don't try to create such an object with new, but always make it an ordinary variable, such that its scope contains your variable of type bulk. This is to ensure that your E variable is destructed when not need any more and that this destruction takes place after the one of the variable of bulk type.
    1. The external information your extraction needs is not changed during the process of extraction. Then a call to one of the two methods should not change the object of E and so it should be declared as being a const member
      int identify(size_t i, S d, size_t nb)const;
      extract(size_t i, int proc, S d, T& m )const;
    2. Only under rare circumstances it should be necessary that one of the methods also changes the object of E. Then use
      int identify(size_t i, S d, size_t nb);
      extract(size_t i, int proc, S d, T& m );
      for the declaration.

See also:
par::step::identification() for cases where an item should be send to several parXXL processes.

Definition at line 114 of file par_step_bulk.h.


Member Typedef Documentation

template<class E>
typedef E::S par::step::bulk< E >::S

The source type of the bulk communication.

Reimplemented in par::step::query_reply< E >.

Definition at line 116 of file par_step_bulk.h.

template<class E>
typedef E::T par::step::bulk< E >::T

The target type of the bulk communication.

Reimplemented in par::step::query_reply< E >.

Definition at line 117 of file par_step_bulk.h.


Constructor & Destructor Documentation

template<class E>
par::step::bulk< E >::bulk ( array< S > &  gga,
E &  extr 
) [inline]

Definition at line 150 of file par_step_bulk.h.

template<class E>
par::step::bulk< E >::bulk ( bulk_generic const &  other,
array< S > &  gga 
) [inline]

Definition at line 158 of file par_step_bulk.h.

template<class E>
par::step::bulk< E >::bulk ( bulk_generic const &  other,
array< S > &  gga,
E &  extr 
) [inline]

Definition at line 165 of file par_step_bulk.h.

template<class E >
par::step::bulk< E >::~bulk ( void   )  [inline, virtual]

Definition at line 166 of file par_step_bulk.cc.


Member Function Documentation

template<class E>
void par::step::bulk< E >::allocate ( void   )  [inline]

Force allocation and dimensioning of the target array.

As a result the local part of the is at the correct length and the target array knows about the lengths on the other processors.

Definition at line 210 of file par_step_bulk.h.

template<class E>
void par::step::bulk< E >::count ( void   )  [inline]

Definition at line 138 of file par_step_bulk.h.

template<class E >
template<class iterator >
template void par::step::bulk< E >::count< iterator > ( iterator act  )  [inline]

Definition at line 35 of file par_step_bulk.cc.

template<class E >
void par::step::bulk< E >::deallocate ( void   )  [inline]

Definition at line 142 of file par_step_bulk.cc.

template<class E >
void par::step::bulk< E >::deallocate_data ( void   )  [inline]

this will not be done automatically on destruction

Definition at line 159 of file par_step_bulk.cc.

void par::step::bulk_generic::distribute ( void   )  [inherited]

propagate and collect the number of elements that we will send form each to each other parXXL process.

Definition at line 32 of file par_step_bulk_generic.cc.

template<class E >
template<class iterator >
template void par::step::bulk< E >::exchange< iterator > ( iterator act,
bool  delsource = false 
) [inline]

Definition at line 128 of file par_step_bulk.cc.

template<class E>
void par::step::bulk< E >::exchange ( bool  delsource = false  )  [inline]

Do the real exchange of the data.

Parameters:
delsource if means that the source array may be deleted as soon as the data savely sits in some buffer or has arrived at the other side.

Definition at line 245 of file par_step_bulk.h.

template<class E>
void par::step::bulk< E >::extraction ( mem::chunk< T > *&  buf  )  [inline]

Definition at line 143 of file par_step_bulk.h.

template<class E >
template<class iterator >
template void par::step::bulk< E >::extraction< iterator > ( iterator act,
mem::chunk< T > *&  buf 
) [inline]

Definition at line 69 of file par_step_bulk.cc.

template<class E >
template<class iterator >
template void par::step::bulk< E >::finish< iterator > ( iterator act  )  [inline]

Reimplemented in par::step::query_reply< E >.

Definition at line 163 of file par_step_bulk.cc.

template<class E>
void par::step::bulk< E >::finish ( void   )  [inline]

do eventual clean up.

Reimplemented in par::step::query_reply< E >.

Definition at line 238 of file par_step_bulk.h.

off_t par::step::bulk_generic::get_messageLength (  )  const [inline, inherited]

Definition at line 109 of file par_step_bulk_generic.h.

off_t par::step::bulk_generic::get_receivLength (  )  const [inline, inherited]

Definition at line 110 of file par_step_bulk_generic.h.

template<class E>
array< T >* par::step::bulk< E >::get_recvarray ( void   )  const [inline]

Definition at line 196 of file par_step_bulk.h.

template<class E>
mem::chunk< T >& par::step::bulk< E >::get_recvchunk ( par::cntrl::proc_t  whom  )  [inline]

Definition at line 200 of file par_step_bulk.h.

template<class E >
template<class iterator >
template void par::step::bulk< E >::initiate< iterator > ( iterator act  )  [inline]

Definition at line 120 of file par_step_bulk.cc.

template<class E>
void par::step::bulk< E >::initiate ( void   )  [inline]

Initialize the buffers.

Definition at line 234 of file par_step_bulk.h.

template<class E>
void par::step::bulk< E >::set_recvarray ( array< T > &  ra  )  [inline]

Definition at line 194 of file par_step_bulk.h.

template<class E>
void par::step::bulk< E >::set_recvarray ( array< T > *  ra = NULL  )  [inline]

Definition at line 189 of file par_step_bulk.h.

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


Member Data Documentation

Definition at line 103 of file par_step_bulk_generic.h.

template<class E>
par::step::array< S >& par::step::bulk< E >::datarray

The source array of the bulk communication.

Definition at line 128 of file par_step_bulk.h.

Definition at line 81 of file par_step_bulk_generic.h.

template<class E>
E& par::step::bulk< E >::extractor

specify the kind of communication.

The extractor that allows the programmer to

Definition at line 119 of file par_step_bulk.h.

Definition at line 101 of file par_step_bulk_generic.h.

off_t* const par::step::bulk_generic::messageNo [protected, inherited]

bulk will count the amount of messages to be send to each parXXL process. The result will be reflected in an array of size np() named messageNo. individual parXXL process.

Definition at line 79 of file par_step_bulk_generic.h.

Definition at line 80 of file par_step_bulk_generic.h.

off_t const par::step::bulk_generic::nb_elts [protected, inherited]

Definition at line 93 of file par_step_bulk_generic.h.

template<class E>
bool par::step::bulk< E >::own_recv [protected]

Whether recvarray has been allocated by this bulk.

Definition at line 124 of file par_step_bulk.h.

template<class E>
par::mem::chunk< T >* par::step::bulk< E >::rchunks [protected]

A table of received chunks per source processor.

Definition at line 125 of file par_step_bulk.h.

Definition at line 94 of file par_step_bulk_generic.h.

Definition at line 95 of file par_step_bulk_generic.h.

Definition at line 92 of file par_step_bulk_generic.h.

off_t* const par::step::bulk_generic::receivNo [protected, inherited]

Definition at line 91 of file par_step_bulk_generic.h.

template<class E>
par::step::array< T >* par::step::bulk< E >::recvarray [protected]

The array that receives the data.

Definition at line 123 of file par_step_bulk.h.

This table can be used to propagate controling information to all other parXXL processes.

Definition at line 100 of file par_step_bulk_generic.h.


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

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