gp_api.tex

\documentclass[12pt]{article}
\include{preamble/preamble}
\begin{document}


\apih{ACCESS ELEMENT}{Obtain a pointer to a locally held GP element}

\begin{capi}
\begin{ccode}
void GP_Access_element(int g_p, int *subscript, void *ptr, int *size)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{subscript}{indices of array element}
\outarg{void*}{ptr}{pointer to locally held element}
\outarg{int*}{size}{size in bytes of locally held element}
\end{funcargs}
\end{capi}

\local

\begin{desc}

This function returns a pointer to the data element element represented by the
array subscript. The suscript must be local to the processor, which means that
it must be within the bounds returned by the GP\_Distribution function for the
calling process. It is an error if the subscript values represent an element
on a different processor.

\end{desc}

\seealso{DISTRIBUTION,RELEASE ELEMENT,RELEASE UPDATE ELEMENT}

\apih{ALLOCATE}{Allocate resources for a new GP array}

\begin{capi}
\begin{ccode}
int GP_Allocate(int g_p)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\end{funcargs}
\end{capi}

\wcoll

\begin{desc}

This function is called after a new array handle has been created and its
attributes have been set. This function actually allocates resources for the GP
array and allows it to be used by the program to store data.

\end{desc}

\seealso{CREATE HANDLE,SET DIMENSIONS}

\apih{ASSIGN LOCAL ELEMENT}{Assign a pointer to local data}

\begin{capi}
\begin{ccode}
void GP_Assign_local_element(int g_p, int *subscript, void *ptr, int size)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{subscript}{indices of array element}
\inarg{void*}{ptr}{pointer to local data}
\inarg{int}{size}{size in bytes of local data}
\end{funcargs}
\end{capi}

\local

\begin{desc}

This function is used to associate a GP array element located locally on the
process with a memory segment. The memory must be allocated using the GP\_Malloc
function and the size argument used in this call must correspond to the size
argument in the GP\_Malloc call. It is an error if the subscript indices fall
outside the range of values returned by the GP\_Distribution call for the calling
process. 

\end{desc}

\seealso{DISTRIBUTION,MALLOC}

\apih{CREATE HANDLE}{Create a GP handle}

\begin{capi}
\begin{ccode}
int GP_Create_handle()
\end{ccode}
\end{capi}

\wcoll

\begin{desc}

This function creates a new GP handle and returns it to the user. Calling this
function is the first step in creating a new GP array.

\end{desc}

\seealso{ALLOCATE}

\apih{DESTROY}{Remove a GP array from the system and free up resources}

\begin{capi}
\begin{ccode}
int GP_Destroy(int g_p)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\end{funcargs}
\end{capi}

\wcoll

\begin{desc}

Destroy a GP array and free up the associated resources. Not that this function
does not remove individual array elements. These should be removed first by a
call to GP\_Free\_local\_element and GP\_Free. The first call returns the pointer to
a local element and sets the corresponding pointer and size in the GP to zero
and the second actually removes the local memory segment. The complete code for
properly destroying a hypothetical 2-dimensional GP array is

\begin{verbatim}
   GP_Distribution(g_p, me, lo, hi);
   for (i = lo[0]; i<=hi[0]; i++) {
     subscript[0] = i;
     for (j = lo[1]; j<=hi[1]; j++) {
       subscript[1] = j;
       GP_Free(GP_Free_local_element(g_p, subscript);
     }
   }
   GP_Destroy(g_p);
\end{verbatim}

\end{desc}

\seealso{FREE,FREE LOCAL ELEMENT}

\apih{DISTRIBUTION}{Report array bounds for elements held locally on specified processor}

\begin{capi}
\begin{ccode}
void GP_Distribution(int g_p, int proc, int *lo, int *hi)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int}{proc}{requested processor}
\outarg{int*}{lo}{lower indices of locally held data}
\outarg{int*}{hi}{upper indices of locally held data}
\end{funcargs}
\end{capi}

\local

\begin{desc}

Return the bounding indices of the data held locally on processor proc. For the
calling processor, this data can usually be accessed much more quickly than data
on remote processors.

\end{desc}

\apih{FREE}{Free up memory allocated using GP\_Malloc}

\begin{capi}
\begin{ccode}
void GP_Free(void *ptr)
\end{ccode}
\begin{funcargs}
\inarg{void*}{ptr}{pointer to local memory segment}
\end{funcargs}
\end{capi}

\local

\begin{desc}

This function is used to free up local memory segments allocated using
GP\_Malloc. Note that it should not be using on segments allocated using ordinary
malloc.

\end{desc}

\seealso{MALLOC,DESTROY,FREE LOCAL ELEMENT}

\apih{FREE LOCAL ELEMENT}{Remove association between local memory segment and GP array}

\begin{capi}
\begin{ccode}
void* GP_Free_local_element(int g_p, int *subscript)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{subscript}{subscript to local array element}
\end{funcargs}
\end{capi}

\local

\begin{desc}

This function removes the association between a local memory segment and the
corresponding local GP array element and returns a pointer to the local memory
segment. Future requests for that array element
will return a null pointer and zero size. Note that this does not remove the
memory segment itself, which must be done by a separate call to GP\_Free.

\end{desc}

\seealso{FREE,DESTROY}

\apih{GATHER SIZE}{Determine the size of a random selection of GP array elements}

\begin{capi}
\begin{ccode}
void GP_Gather_size(int g_p, int nv, int *subscript, int *size)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int}{nv}{number of array elements in subscript array}
\inarg{int*}{subscript}{list of array element indices}
\outarg{int*}{size}{total size of array elements (in bytes)}
\end{funcargs}
\end{capi}

\ncoll

\begin{desc}

This function can be used to determine the size of list of array elements that
will be copied to a local buffer in a GP\_Gather call. This allows users to
allocate a buffer of the correct size before requesting the actual data. The
total number of elements to be gathered is nv and the
subscript array contains ndim*nv elements where ndim is the dimension of the GP
array. The first ndim elements of subscript correspond to the indices of the first
array element, the next ndim subscript entries are for the second array element,
etc.

\end{desc}

\seealso{GATHER}

\apih{GATHER}{Copy a random selection of GP array elements to a local buffer}

\begin{capi}
\begin{ccode}
void GP_Gather(int g_p, int nv, int *subscript, void *buf,
               void **buf_ptr, int *buf_size, int *size, int setbuf)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int}{nv}{number of array elements in subscript array}
\inarg{int*}{subscript}{list of array element indices}
\inarg{void*}{buf}{pointer to local memory that contains data}
\outarg{void**}{buf_ptr}{array of pointers to individual elements}
\outarg{int*}{buf_size}{array containing sizes of array elements}
\outarg{int*}{size}{total size of array elements (in bytes)}
\inarg{int}{setbuf}{flag for using contents buf_ptr and buf_size arrays}
\end{funcargs}
\end{capi}

\ncoll

\begin{desc}

This function can be used to copy an arbitrary collection of GP array elements
into a local buffer. The pointer buf corresponds to a local memory segment that
is large enough to contain the requested data. The size of this buffer can be
determined beforehand by a call to GP\_Gather\_size. The data is packed into
this data contiguously, but it may not be easy for users to access it. The
pointer array buf\_ptr provides users pointers to the individual array elements
and corresponds to the list of subscripts. The array buf\_size provides users
with the sizes of individual array elements. The total size of the request is
returned in the variable size.

If the setbuf parameter is set to 0
then it is assumed that there is no useful information in the buf\_ptr and
buf\_size arrays and the call computes this information. If setbuf is not 0,
then the call assumes that buf\_size already contains the correct sizes of the
requested elements and buf\_ptr already points to memory locations that can
receive the requested data. In this case, buf is ignored. This call can be used
to increase performance, if applicable, or to copy the contents of one GP array
into another GP array.

\end{desc}

\seealso{GATHER SIZE}

\apih{GET SIZE}{Determine size of a block of data in a GP array}

\begin{capi}
\begin{ccode}
void GP_Get_size(int g_p, int *lo, int *hi, int *size)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{lo}{lower indices of array block}
\inarg{int*}{hi}{upper indices of array block}
\outarg{int*}{size}{total size of array block (in bytes)}
\end{funcargs}
\end{capi}

\ncoll

\begin{desc}

This function can be used to determine the size of the data contained in a block
of GP array elements. The block is defined by the lower indices in the array lo
and the upper indices in the array hi. The total size of the data is returned in
bytes. This allows users to allocate a buffer of the correct size before
requesting the actual data using a GP\_Get call.

\end{desc}

\seealso{GET}

\apih{GET}{Request a block of data from a GP array}

\begin{capi}
\begin{ccode}
void GP_Get(int g_p, int *lo, int *hi, void *buf, void **buf_ptr, int *ld,
             void *buf_size, int *ld_size, int *size, int setbuf)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{lo}{lower indices of array block}
\inarg{int*}{hi}{upper indices of array block}
\inarg{void*}{buf}{pointer to local memory that contains data}
\outarg{void**}{buf_ptr}{array of pointers to individual elements}
\inarg{int*}{ld}{stride array for buf_ptr array}
\outarg{int*}{buf_size}{array containing sizes of array elements}
\inarg{int*}{ld_sz}{stride array for buf_size array}
\outarg{int*}{size}{total size of array block (in bytes)}
\inarg{int}{setbuf}{flag for using contents buf_ptr and buf_size arrays}
\end{funcargs}
\end{capi}

\ncoll

\begin{desc}

This function retrieves a block of data from a GP array and copies it to a local
buffer.  The block is defined by the lower indices in the array lo
and the upper indices in the array hi. The size of the local buffer can be
determined prior to using this call by using the function GP\_Get\_size. The
data is placed contiguously in the buffer designated by the void pointer buf.
Pointers to the individual array elements can be retrieved from the pointer
array buf\_ptr. This array is layed out using the stride array ld. Similarly,
the size of individual array elements is stored in the array buf\_size, which is
layed out using the stride array ld\_sz. If the setbuf parameter is set to 0
then it is assumed that there is no useful information in the buf\_ptr and
buf\_size arrays and the call computes this information. If setbuf is not 0,
then the call assumes that buf\_size already contains the correct sizes of the
requested elements and buf\_ptr already points to memory locations that can
receive the requested data. In this case, buf is ignored. This call can be used
to increase performance, if applicable, or to copy the contents of one GP array
into another GP array.

\end{desc}

\seealso{GET SIZE}

\apih{INITIALIZE}{Initialize the GP toolkit}

\begin{capi}
\begin{ccode}
void GP_Initialize()
\end{ccode}
\end{capi}

\wcoll

\begin{desc}

This function initializes the GP toolkit and sets up internal data structures
that are used by the remaining GP functions. It should be called after the GA
initialize function has been called.

\end{desc}

\seealso{TERMINATE}

\apih{MALLOC}{Allocate memory for GP array elements}

\begin{capi}
\begin{ccode}
void GP_Malloc(size_t size)
\end{ccode}
\begin{funcargs}
\inarg{size_t}{size}{size (in bytes) of allocated segment}
\end{funcargs}
\end{capi}

\local

\begin{desc}

This function is used to allocate memory segments that will be associated with
GP array elements. Note that this function \emph{must} be used instead of
ordinary malloc since it internally registers network addresses that are used by
the GP toolkit.

\end{desc}

\seealso{FREE,ASSIGN LOCAL ELEMENT}

\apih{MEMZERO}{Zero all bytes in a GP array}

\begin{capi}
\begin{ccode}
void GP_Memzero(int g_p)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\end{funcargs}
\end{capi}

\wcoll

\begin{desc}

This function function can be used to set all the individual bytes
contained in a GP array to zero.

\end{desc}

\apih{PUT}{Copy a block of data to a GP array}

\begin{capi}
\begin{ccode}
void GP_Put(int g_p, int *lo, int *hi, void **buf_ptr, int *ld,
             void *buf_size, int *ld_size, int *size, int checksize)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{lo}{lower indices of array block}
\inarg{int*}{hi}{upper indices of array block}
\inarg{void**}{buf_ptr}{array of pointers to individual elements}
\inarg{int*}{ld}{stride array for buf_ptr array}
\inarg{int*}{buf_size}{array containing sizes of array elements}
\inarg{int*}{ld_sz}{stride array for buf_size array}
\outarg{int*}{size}{total size of array block (in bytes)}
\inarg{int}{checksize}{optional size verification}
\end{funcargs}
\end{capi}

\ncoll

\begin{desc}

This function copies local data to a block of GP array elements.
and copies it to a local
buffer. The block is defined by the lower indices in the array lo
and the upper indices in the array hi. The size of the local buffer can be
determined prior to using this call by using the function GP\_Get\_size. The
data is placed contiguously in the buffer designated by the void pointer buf.
Pointers to the individual array elements can be retrieved from the pointer
array buf\_ptr. buf\_ptr array is layed out using the stride array ld. Similarly,
the size of individual array elements is stored in the array buf\_size, which is
layed out using the stride array ld\_sz. The checksize variable can be used to
optionally compare the element size values in buf\_size with the values stored in
the GP array. If they are different, the code throws an error. This is useful
for debugging but adds more communication overhead to the put call. The size of
the data transfer is returned in size.

\end{desc}

\apih{RELEASE ELEMENT}{Release access after reading from GP array element}

\begin{capi}
\begin{ccode}
void GP_Release_element(int g_p, int *subscript)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{subscript}{indices of GP array element}
\end{funcargs}
\end{capi}

\local

\begin{desc}

Release access to a GP array element after reading from it. This should always
be used in conjunction with GP\_Access\_element.

\end{desc}

\seealso{ACCESS ELEMENT,RELEASE UPDATE ELEMENT}

\apih{RELEASE UPDATE ELEMENT}{Release access after modifying a GP array element}

\begin{capi}
\begin{ccode}
void GP_Release_update_element(int g_p, int *subscript)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{subscript}{indices of GP array element}
\end{funcargs}
\end{capi}

\local

\begin{desc}

Release access to a GP array element after modifying it. This should always be
used in conjunction with GP\_Access\_element.

\end{desc}

\seealso{ACCESS ELEMENT,RELEASE ELEMENT}

\apih{SCATTER}{Copy local data to a random selection of GP array elements}

\begin{capi}
\begin{ccode}
void GP_Scatter(int g_p, int nv, int *subscript, void **buf_ptr,
                int *buf_size, int *size, int checksize)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int}{nv}{number of array elements in subscript array}
\inarg{int*}{subscript}{list of array element indices}
\inarg{void*}{buf}{pointer to local memory that contains data}
\outarg{void**}{buf_ptr}{array of pointers to individual elements}
\outarg{int*}{buf_size}{array containing sizes of array elements}
\outarg{int*}{size}{total size of array elements (in bytes)}
\end{funcargs}
\end{capi}

\ncoll

\begin{desc}

This function can be used to scatter an arbitrary collection of local elements
into a GP array. The number of elements that will be scattered to the GP array
is nv and the subscripts of these elements are in the nv*ndim sized subscript
array. The subscripts are ordered such that the first ndim entries correspond
to the indices of the first element, the next ndim entries are the subsrcript of
the second element, and so on. The pointer array buf\_ptr is a list of pointers
to the local data that will be scattered to the GP array elements
and corresponds to the list of subscripts. The array buf\_size represents the
size of each of the elements. The checksize variable allows users to make an
optional check that compares the sizes in the buf\_size array with the sizes
stored in the GP array and throws an error if they are different. This is
useful for debugging but adds more communication overhead to the scatter call.
The total size of the request is returned in the variable size.

\end{desc}

\apih{SET CHUNK}{Set minimum chunking size on each processor}

\begin{capi}
\begin{ccode}
void GP_Set_chunk(int g_p, int *chunk)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{chunk}{minimun chunk sizes in each dimension}
\end{funcargs}
\end{capi}

\wcoll

\begin{desc}

This is a crude way of controlling the partitioning of GP arrays across
processors by setting the minimum size for each dimension a local
block of a GP array. If the value of the chunk array for a particular dimension
is less than or equal to 0, then partitioning is left completely to the GP
library. The chunk array is particularly useful for blocking the partitioning of
an array along certain axes by setting chunk[n]=dims[n]. More control of the
data distribution can be achieved using the GP\_Set\_irreg\_distr function.

\end{desc}

\seealso{CREATE HANDLE,SET IRREG DISTR}

\apih{SET DIMENSIONS}{Set dimensions of GP array}

\begin{capi}
\begin{ccode}
void GP_Set_dimensions(int g_p, int ndim, int *dims)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int}{ndim}{dimension of GP array}
\inarg{int*}{dims}{size of array axes}
\end{funcargs}
\end{capi}

\wcoll

\begin{desc}

This function sets the dimension and size of GP array. Note that these are the
global dimensions of the array, not the size of the array held locally.

\end{desc}

\seealso{CREATE HANDLE}

\apih{SET IRREG DISTR}{Specify partitioning of GP array}

\begin{capi}
\begin{ccode}
void GP_Set_irreg_distr(int g_p, int *mapc, int *nblock)
\end{ccode}
\begin{funcargs}
\inarg{int}{g_p}{pointer array handle}
\inarg{int*}{mapc}{starting indices of partitions}
\inarg{int*}{nblock}{processor grid}
\end{funcargs}
\end{capi}

\wcoll

\begin{desc}

This function can be used to completely partition the GP array among the
available processors. All details of the partition must be supplied by the user.
The first component of the partitions is to choose how many blocks each axis
will be divided into. This information is supplied in the nblock array. The
product of the values for each axis in nblock must equal the total number of
processors in the system. The mapc array contains the initial indices of each
block along the axes directions. The first nblock[0] entries are the starting
indices for blocks along the first axis direction, the next nblock[1] entries
are the starting indices for the blocks along the second axis directions, and so
on.

\end{desc}

\seealso{CREATE HANDLE}

\apih{SYNC}{Synchronize across all processors}

\begin{capi}
\begin{ccode}
void GP_Sync()
\end{ccode}
\end{capi}

\wcoll

\begin{desc}

This function synchronizes the system across all processors and flushes out all
outstanding communication in the system. It is the primary mechanism for
insuring data consistency. This function is equivalent to GA\_sync and they can
be used interchangeably.

\end{desc}

\apih{TERMINATE}{Terminate the GP library}

\begin{capi}
\begin{ccode}
void GP_Terminate()
\end{ccode}
\end{capi}

\wcoll

\begin{desc}

This function terminates the GP library and cleans up any resources used by the
library. It should be called before call GA\_Terminate.

\end{desc}

\end{document}