Main Page   Alphabetical List   Compound List   File List   Compound Members   File Members  

GAServices Class Reference

GAServices : Global Arrays Services class. More...

#include <GAServices.h>

List of all members.

Public Methods

 GAServices ()
 Null-constructor. More...

 ~GAServices ()
 Destructor. More...

GlobalArray * createGA (int type, int ndim, int dims[], char *arrayname, int chunk[])
 Creates an ndim-dimensional array using the regular distribution model and returns integer handle representing the array. More...

GlobalArray * createGA (int type, int ndim, int dims[], char *arrayname, int block[], int maps[])
 Creates an array by following the user-specified distribution and returns integer handle representing the array. More...

GlobalArray * createGA (const GlobalArray *g_b, char *arrayname)
 Creates a new array by applying all the properties of another existing array. More...

GlobalArray * createGA (const GlobalArray &g_b)
 Creates a new array by applying all the properties of another existing array. More...

GlobalArray * createGA ()
 Creates a 10x10 global array of type "double"(default). More...

GlobalArray * createGA_Ghosts (int type, int ndim, int dims[], int width[], char *array_name, int chunk[])
 Creates an ndim-dimensional array with a layer of ghost cells around the visible data on each processor using the regular distribution model and returns an integer handle representing the array. More...

GlobalArray * createGA_Ghosts (int type, int ndim, int dims[], int width[], char *array_name, int map[], int nblock[])
 Creates an array with ghost cells by following the user-specified distribution and returns integer handle representing the array. More...

void brdcst (void *buf, int lenbuf, int root)
int clusterNnodes ()
 This functions returns the total number of nodes that the program is running on. More...

int clusterNodeid ()
 This function returns the node ID of the process. More...

int clusterNprocs (int inode)
 This function returns the number of processors available on node inode. More...

int clusterProcid (int inode, int iproc)
 This function returns the processor id associated with node inode and the local processor id iproc. More...

int createMutexes (int number)
 Creates a set containing the number of mutexes. More...

int destroyMutexes ()
 Destroys the set of mutexes created with ga_create_mutexes. More...

void dgop (double x[], int n, char *op)
int duplicate (int g_a, char *array_name)
void error (const char *message, int code)
 To be called in case of an error. More...

void fence ()
 Blocks the calling process until all the data transfers corresponding to GA operations called after ga_init_fence complete. More...

void igop (Integer x[], int n, char *op)
void initFence ()
 Initializes tracing of completion status of data movement operations. More...

size_t inquireMemory ()
 Returns amount of memory (in bytes) used in the allocated global arrays on the calling processor. More...

void lock (int mutex)
void maskSync (int first, int last)
 GA Collective calls has Sync calls at the begining and ending of of the call. More...

int memoryAvailable ()
int memoryLimited ()
 Indicates if limit is set on memory usage in Global Arrays on the calling processor. More...

int nodeid ()
 Returns the GA process id (0, ..., ga_Nnodes()-1) of the requesting compute process. More...

int nodes ()
 Returns the number of the GA compute (user) processes. More...

void printStats ()
 This non-collective (MIMD) operation prints information about:. More...

void setMemoryLimit (size_t limit)
void summarize (int verbose)
void sync ()
 Synchronize processes (a barrier) and ensure that all GA operations completed. More...

void unlock (int mutex)
int usesMA ()
 Returns "1" if memory in global arrays comes from the Memory Allocator (MA). More...

int usesFAPI ()
 Returns "1" if uses fortran API, else returns "0". More...

Detailed Description

GAServices : Global Arrays Services class.

Author: Manoj Kumar Krishnan, PNNL.

Collecting the global information: who am I, and how many processors are being used. Initialize the communication library (either MPI or TCSMSG) and Global array. Allocate momory to be used by GA by calling MA and create global arrays.

Definition at line 12 of file GAServices.h.

Constructor & Destructor Documentation

GAServices::GAServices (    ) 
 

Null-constructor.

The component won't really be 'alive' much at all until after setServices is called on it.

GAServices::~GAServices (    ) 
 

Destructor.

Member Function Documentation

GlobalArray* GAServices::createGA (  int    type,
int    ndim,
int    dims[],
char *    arrayname,
int    chunk[]
) 
 

Creates an ndim-dimensional array using the regular distribution model and returns integer handle representing the array.

The array can be distributed evenly or not. The control over the distribution is accomplished by specifying chunk (block) size for all or some of array dimensions.

For example, for a 2-dimensional array, setting chunk[0]=dim[0] gives distribution by vertical strips (chunk[0]*dims[0]); setting chunk[1]=dim[1] gives distribution by horizontal strips (chunk[1]*dims[1]). Actual chunks will be modified so that they are at least the size of the minimum and each process has either zero or one chunk. Specifying chunk[i] as <1 will cause that dimension to be distributed evenly.

As a convenience, when chunk is specified as NULL, the entire array is distributed evenly.


This is a collective operation.

Parameters:
arrayname  - a unique character string [input]
type  - data type(MT_F_DBL,MT_F_INT,MT_F_DCPL) [input]
ndim  - number of array dimensions [input]
dims  [ndim] - array of dimensions [input]
chunk  [ndim] - array of chunks, each element specifies minimum size that given dimensions should be chunked up into [input]
Returns:
Returns pointer to GlobalArray object created. Returns NULL if it fails to create a GA object.

GlobalArray* GAServices::createGA (  int    type,
int    ndim,
int    dims[],
char *    arrayname,
int    block[],
int    maps[]
) 
 

Creates an array by following the user-specified distribution and returns integer handle representing the array.

The distribution is specified as a Cartesian product of distributions for each dimension. The array indices start at 0. For example, the following figure demonstrates distribution of a 2-dimensional array 8x10 on 6 (or more) processors. nblock[2]={3,2}, the size of map array is s=5 and array map contains the following elements map={0,2,6,0,5}. The distribution is nonuniform because, P1 and P4 get 20 elements each and processors P0,P2,P3, and P5 only 10 elements each.

5 5
P0 P3 2
P1 P4 4
P2 P5 2


This is a collective operation.

Parameters:
arrayname  - a unique character string [input]
type  - MA data type (MT_F_DBL,MT_F_INT,MT_F_DCPL) [input]
ndim  - number of array dimensions [input]
dims  - array of dimension values [input]
block  [ndim] - no. of blocks each dimension is divided into [input]
maps  [s] - starting index for for each block; the size s is a sum all elements of nblock array [input]
Returns:
Returns pointer to GlobalArray object created. Returns NULL if it fails to create a GA object.

GlobalArray* GAServices::createGA (  const GlobalArray *    g_b,
char *    arrayname
) 
 

Creates a new array by applying all the properties of another existing array.


This is a collective operation.

Parameters:
arrayname  - a character string [input]
g_b  - integer handle for reference array [input]
Returns:
Returns pointer to GlobalArray object created. Returns NULL if it fails to create a GA object.

GlobalArray* GAServices::createGA (  const GlobalArray &    g_b ) 
 

Creates a new array by applying all the properties of another existing array.


This is a collective operation.

Parameters:
g_b  - integer handle for reference array [input]
Returns:
Returns pointer to GlobalArray object created. Returns NULL if it fails to create a GA object.

GlobalArray* GAServices::createGA (    ) 
 

Creates a 10x10 global array of type "double"(default).

Returns:
Returns pointer to GlobalArray object created. Returns NULL if it fails to create a GA object.

GlobalArray* GAServices::createGA_Ghosts (  int    type,
int    ndim,
int    dims[],
int    width[],
char *    array_name,
int    chunk[]
) 
 

Creates an ndim-dimensional array with a layer of ghost cells around the visible data on each processor using the regular distribution model and returns an integer handle representing the array.

The array can be distributed evenly or not evenly. The control over the distribution is accomplished by specifying chunk (block) size for all or some of the array dimensions. For example, for a 2-dimensional array, setting chunk(1)=dim(1) gives distribution by vertical strips (chunk(1)*dims(1)); setting chunk(2)=dim(2) gives distribution by horizontal strips (chunk(2)*dims(2)). Actual chunks will be modified so that they are at least the size of the minimum and each process has either zero or one chunk. Specifying chunk(i) as <1 will cause that dimension (i-th) to be distributed evenly. The width of the ghost cell layer in each dimension is specified using the array width(). The local data of the global array residing on each processor will have a layer width[n] ghosts cells wide on either side of the visible data along the dimension n.

Parameters:
array_name  - a unique character string [input]
type  - data type (MT_DBL,MT_INT,MT_DCPL) [input]
ndim  - number of array dimensions [input]
dims  [ndim] - array of dimensions [input]
width  [ndim] - array of ghost cell widths [input]
chunk  [ndim] - array of chunks, each element specifies minimum size that given dimensions should be chunked up into [input]
Returns:
Returns pointer to GlobalArray object created. Returns NULL if it fails to create a GA object.

GlobalArray* GAServices::createGA_Ghosts (  int    type,
int    ndim,
int    dims[],
int    width[],
char *    array_name,
int    map[],
int    nblock[]
) 
 

Creates an array with ghost cells by following the user-specified distribution and returns integer handle representing the array.

The distribution is specified as a Cartesian product of distributions for each dimension. For example, the following figure demonstrates distribution of a 2-dimensional array 8x10 on 6 (or more) processors. nblock(2)={3,2}, the size of map array is s=5 and array map contains the following elements map={1,3,7, 1, 6}. The distribution is nonuniform because, P1 and P4 get 20 elements each and processors P0,P2,P3, and P5 only 10 elements each.

5 5
P0 P3 2
P1 P4 4
P2 P5 2

The array width[] is used to control the width of the ghost cell boundary around the visible data on each processor. The local data of the global array residing on each processor will have a layer width[n] ghosts cells wide on either side of the visible data along the dimension n.

Parameters:
array_name  - a unique character string [input]
type  - data type (MT_DBL,MT_INT,MT_DCPL) [input]
ndim  - number of array dimensions [input]
dims  [ndim] - array of dimensions [input]
width  [ndim] - array of ghost cell widths [input]
nblock  [ndim] - no. of blocks each dimension is divided into[input]
map  [s] - starting index for for each block; the size s is a sum of all elements of nblock array[input]
Returns:
Returns pointer to GlobalArray object created. Returns NULL if it fails to create a GA object.
This is a collective operation.

void GAServices::brdcst (  void *    buf,
int    lenbuf,
int    root
) 
 

Parameters:
lenbuf  - length of buffer [input]
buf  [lenbuf] - data [input/output]
root  - root process [input]
Broadcast from process root to all other processes a message of length lenbuf. This is operation is provided only for convenience purposes: it is available regardless of the message-passing library that GA is running with.
This is a collective operation.

int GAServices::clusterNnodes (    ) 
 

This functions returns the total number of nodes that the program is running on.

On SMP architectures, this will be less than or equal to the total number of processors.
This is a local operation.

int GAServices::clusterNodeid (    ) 
 

This function returns the node ID of the process.

On SMP architectures with more than one processor per node, several processes may return the same node id.
This is a local operation.

int GAServices::clusterNprocs (  int    inode ) 
 

This function returns the number of processors available on node inode.


This is a local operation.

Parameters:
inode  [input]

int GAServices::clusterProcid (  int    inode,
int    iproc
) 
 

This function returns the processor id associated with node inode and the local processor id iproc.

If node inode has N processors, then the value of iproc lies between 0 and N-1.

Parameters:
inode,iproc  [input]
This is a local operation.

int GAServices::createMutexes (  int    number ) 
 

Creates a set containing the number of mutexes.

Returns 0 if the opereation succeeded or 1 when failed. Mutex is a simple synchronization object used to protect Critical Sections. Only one set of mutexes can exist at a time. Array of mutexes can be created and destroyed as many times as needed. Mutexes are numbered: 0, ..., number -1.
This is a collective operation.

Parameters:
number  - number of mutexes in mutex array [input]

int GAServices::destroyMutexes (    ) 
 

Destroys the set of mutexes created with ga_create_mutexes.

Returns 0 if the operation succeeded or 1 when failed.
This is a collective operation.

void GAServices::dgop (  double    x[],
int    n,
char *    op
) 
 

Parameters:
n  - number of elements [input]
x  [n] - array of elements [input/output]
op  - operator [input]
Double Global OPeration.

X(1:N) is a vector present on each process. DGOP 'sums' elements of X accross all nodes using the commutative operator OP. The result is broadcast to all nodes. Supported operations include '+', '*', 'max', 'min', 'absmax', 'absmin'. The use of lowerecase for operators is necessary. This is operation is provided only for convenience purposes: it is available regardless of the message-passing library that GA is running with.
This is a collective operation.

int GAServices::duplicate (  int    g_a,
char *    array_name
) 
 

Parameters:
array_name  - a character string [input]
g_a  - integer handle for reference array [input]
Creates a new array by applying all the properties of another existing array. It returns array handle. Return value: a non-zero array handle means the call was succesful.
This is a collective operation.

void GAServices::error (  const char *    message,
int    code
) 
 

To be called in case of an error.

Print an error message and an integer value that represents error code. Releases some system resources. This is the required way of aborting the program execution. This operation is local.

Parameters:
message  - string to print [input]
code  - code to print [input]

void GAServices::fence (    ) 
 

Blocks the calling process until all the data transfers corresponding to GA operations called after ga_init_fence complete.

For example, since ga_put might return before the data reaches the final destination, ga_init_fence and ga_fence allow process to wait until the data tranfer is fully completed:

ga_init_fence(); ga_put(g_a, ...); ga_fence();

ga_fence must be called after ga_init_fence. A barrier, ga_sync, assures completion of all data transfers and implicitly cancels all outstanding ga_init_fence calls. ga_init_fence and ga_fence must be used in pairs, multiple calls to ga_fence require the same number of corresponding ga_init_fence calls. ga_init_fence/ga_fence pairs can be nested.

ga_fence works for multiple GA operations. For example:

ga_init_fence(); ga_put(g_a, ...); ga_scatter(g_a, ...); ga_put(g_b, ...); ga_fence();

The calling process will be blocked until data movements initiated by two calls to ga_put and one ga_scatter complete.

void GAServices::igop (  Integer    x[],
int    n,
char *    op
) 
 

Parameters:
n  - number of elements [input]
x  [n] - array of elements [input/output]
op  - operator [input]
Integer Global OPeration. The integer (more precisely long) version of ga_dgop described above, also include the bitwise OR operation. This is operation is provided only for convenience purposes: it is available regardless of the message-passing library that GA is running with.
This is a collective operation.

void GAServices::initFence (    ) 
 

Initializes tracing of completion status of data movement operations.

This operation is local.

size_t GAServices::inquireMemory (    ) 
 

Returns amount of memory (in bytes) used in the allocated global arrays on the calling processor.

This operation is local.

void GAServices::lock (  int    mutex ) 
 

Parameters:
mutex  - mutex object id [input]
Locks a mutex object identified by the mutex number. It is a fatal error for a process to attempt to lock a mutex which was already locked by this process.

void GAServices::maskSync (  int    first,
int    last
) 
 

GA Collective calls has Sync calls at the begining and ending of of the call.

Sometimes there may be some redundacy in sync calls, which can be avoided by masking the sync operations. @ param first - masks the sync at the begining of the collective call. @ param last - masks the sync at the end of the collective call. setting the parameters as zero will mask (disable) the call. Any non-zero value will enable the call. Initially these params are set to non-zero value.

int GAServices::memoryAvailable (    ) 
 

Returns:
Returns amount of memory (in bytes) left for allocation of new global arrays on the calling processor.
Note:
If GA_uses_ma returns true, then GA_Memory_avail returns the lesser of the amount available under the GA limit and the amount available from MA (according to ma_inquire_avail operation). If no GA limit has been set, it returns what MA says is available. If ( ! GA_Uses_ma() && ! GA_Memory_limited() ) returns < 0, indicating that the bound on currently available memory cannot be determined. This operation is local.

int GAServices::memoryLimited (    ) 
 

Indicates if limit is set on memory usage in Global Arrays on the calling processor.

"1" means "yes", "0" means "no". This operation is local.

int GAServices::nodeid (    ) 
 

Returns the GA process id (0, ..., ga_Nnodes()-1) of the requesting compute process.

This operation is local.

int GAServices::nodes (    ) 
 

Returns the number of the GA compute (user) processes.

This operation is local.

void GAServices::printStats (    ) 
 

This non-collective (MIMD) operation prints information about:.

number of calls to the GA create/duplicate, destroy, get, put, scatter, gather, and read_and_inc operations total amount of data moved in the GA primitive operations amount of data moved in GA primitive operations to logicaly remote locations maximum memory consumption in global arrays, and number of requests serviced in the interrupt-driven implementations by the calling process. This operation is local.

void GAServices::setMemoryLimit (  size_t    limit ) 
 

Parameters:
limit  - the amount of memory in bytes per process [input]
Sets the amount of memory to be used (in bytes) per process.
This is a local operation.

void GAServices::summarize (  int    verbose ) 
 

Parameters:
verbose  - If true print distribution info [input] Prints info about allocated arrays.

void GAServices::sync (    ) 
 

Synchronize processes (a barrier) and ensure that all GA operations completed.


This is a collective operation.

void GAServices::unlock (  int    mutex ) 
 

Parameters:
mutex  - mutex object id [input]
Unlocks a mutex object identified by the mutex number. It is a fatal error for a process to attempt to unlock a mutex which has not been locked by this process.

int GAServices::usesMA (    ) 
 

Returns "1" if memory in global arrays comes from the Memory Allocator (MA).

"0"means that memory comes from another source, for example System V shared memory is used. This operation is local.

int GAServices::usesFAPI (    ) 
 

Returns "1" if uses fortran API, else returns "0".

The documentation for this class was generated from the following file:
Generated on Wed Oct 9 23:41:49 2002 for GA++ by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002