upc_all_scatter

Date:: 05-03-2013

NAME

upc_all_scatter - collectively scatters shared memory

SYNOPSIS

void upc_all_scatter( shared void * restrict dst, shared const void * restrict src,
                                     size_t nbytes, upc_flag_t flags );

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

The upc_all_scatter collective function copies the i-th block of an area of shared memory (src) with affinity to a single thread to a block of shared memory (dst) with affinity to the i-th thread. The number of bytes in each block is nbytes, where nbytes > 0.

The upc_all_scatter function treats the src pointer as if it pointed to a shared memory area with the type:

shared [] char[nbytes * THREADS]

and it treats the dst pointer as if it pointed to a shared memory area with the type:

shared [nbytes] char[nbytes * THREADS]

The target of the dst pointer must have affinity to thread 0. The dst pointer is treated as if it has phase 0.

For each thread i, the effect is equivalent to copying the i-th block of nbytes bytes pointed to by src to the block of nbytes bytes pointed to by dst that has affinity to thread i.

Controlling Data Synchronization

The argument flag is of type upc_flag_t and is used to specify the data synchronization semantics for the collective function. The value of flag is formed by or-ing together a constant of the form UPC_IN_XSYNC and a constant of the form UPC_OUT_YSYNC, where X and Y may be NO, MY, or ALL. If X is:

NO: The function may begin to read or write data when the first thread has entered the collective function call.
MY: The function may begin to read or write only data which has affinity to threads that have entered the collective function call.
ALL: The function may begin to read or write data only after all threads have entered the function call.

And if Y is:

NO: The function may read and write data until the last thread has returned from the collective function call.
MY: The function call may return in a thread only after all reads and writes of data with affinity to the thread are complete.
ALL: The function call may return only after all reads and writes of data are complete.

For further information, see upc_flag_t(3c).

EXAMPLES

Example 1: upc_all_scatter for the dynamic THREADS translation environment.

#include <upc.h>
#include <upc_collective.h>
#define NELEMS 10
#define SRC_THREAD 1
shared int *A;
shared [] int *myA, *srcA;
shared [NELEMS] int B[NELEMS*THREADS];

// allocate and initialize an array distributed across all threads
A = upc_all_alloc(THREADS, THREADS*NELEMS*sizeof(int));
myA = (shared [] int *) &A[SRC_THREAD];
upc_barrier;
upc_all_scatter( B, srcA, sizeof(int)*NELEMS,
UPC_IN_NOSYNC | UPC_OUT_NOSYNC);
upc_barrier;

Example 2: upc_all_scatter for the static THREADS translation environment.

#include <upc.h>
#include <upc_collective.h>
#define NELEMS 10
shared [] int A[NELEMS*THREADS];
shared [NELEMS] int B[NELEMS*THREADS];

// Initialize A.
upc_all_scatter( B, A, sizeof(int)*NELEMS,
     UPC_IN_ALLSYNC | UPC_OUT_ALLSYNC );