APPENDIX E

Quick UPC Reference

KEYWORDS

• THREADS: total number of threads
• MYTHREAD: identification number of the current thread (between 0 and THREADS−1)
• UPC_MAX_BLOCK_SIZE: maximum block size allowed by the compilation environment

SHARED VARIABLE DECLARATIONS

Shared Objects

Shared variables are declared using the type qualifier “shared.” Shared objects must be declared statically (i.e., either as global variables or with the keyword static).

Examples of Shared Object Declaration

shared int i;

shared int b[100*THREADS];

The following will not compile if you do not specify the number of threads:

shared int a[100];

All the elements of a are allocated in thread 0:

shared [] int a[100];

Distribute the elements in round-robin fashion by chunks of two elements: a[0] and a[1] are allocated in thread 0; a[2] and a[3] in thread 1;…:

shared [2] int a[100];

Shared Pointers

Pointer to shared object:

shared int* p;

Shared pointer to shared object:

shared int* shared sp;

Equivalent of memset:

upc_memset(dst, char, size)

Assign a block of characters to shared memory.

LOCKS

//Dynamic lock collectively allocated:

{
 upc_lock_t *l;
 l = upc_all_lock_alloc();

 //…
 upc_lock (l);
 // protected section
 upc_unlock (l);

 if( upc_lock_attempt(l))
   {
     //do something if l currently unlocked
   }

 //unallocates the lock
 upc_lock_free (l);
}

//Dynamic lock globally allocated:
upc_lock_t *l;

{
 if(MYTHREAD ==3)
  l = upc_global_lock_alloc();
}

GENERAL UTILITIES

Terminate the UPC program with exit status status:

upc_global_exit(status)

WORK SHARING

The iteration distribution follows the distribution layout of a:

upc_forall (i=0; i7<N; i++; &a[i])

Distributes the iterations in round-robin fashion with wrapping from the last thread to the first thread:

upc_forall (i=0; i<N; i++; i)

Distributes the iterations by consecutive chunks:

upc_forall(i=0; i<N; i++;
i*THREADS/N)

SYNCHRONIZATION

Memory Consistency

These include files set to which consistency model, strict or relaxed, is used for the entire program.

#include "upc_strict.h"

or

"upc_relaxed.h"

Sets strict memory consistency for the rest of the file:

#pragma upc strict

Sets relaxed memory consistency for the rest of the file:

#pragma upc relaxed

All accesses to i are made using the relaxed consistency model:

shared relaxed int i;

All accesses to i are made using the relaxed consistency model:

relaxed shared int i;

All accesses to i are made using the strict consistency model:

strict shared int i;

Synchronizes the shared memory accesses locally; it is equivalent to a null strict reference.

upc_fence;

Barriers

Synchronizes the program globally:

upc_barrier [value];

value is an integer.

//Before the barrier:

upc_notify [value];

// Nonsynchronized statements relative to this ongoing barrier:

upc_wait [value];

// After the barrier:

LIBRARY ROUTINES

• upc_threadof(p): thread having affinity to the location pointed by p
• upc_phaseof(p): phase associated with the location pointed by p
• upc_resetphase(p): shared address with the phase set to zero pointed by p
• upc_addrfield(p): address field associated with the location pointed by p
• upc_localsizeof(p): size of the local portion pointed by p
• upc_blocksizeof(p): blocking factor associated with object pointed by p
• upc_elemsizeof(p): size of the leftmost type of object pointed by p

DYNAMIC MEMORY ALLOCATION

Three different memory allocation methods are provided by UPC:

• upc_alloc(n): allocates at least n bytes of shared space with affinity to the calling thread; needs to be called by one thread only
• upc_global_alloc(n, b): globally allocates n × b bytes of shared data distributed across the threads with a block size of b bytes; needs to be called by one thread only
• upc_all_alloc(n, b): collectively allocates n × b bytes of shared data distributed across the threads with a block size of b bytes; needs to be called by all the threads
• upc_free(p): frees shared memory pointed to by p from the heap

STRING FUNCTIONS IN UPC

Equivalent of memcpy:

upc_memcpy(dst, src, size)

Copy from shared memory to shared memory.

upc_memput(dst, src, size)

Copy from private memory to shared memory.

upc_memget(dst, src, size)

Copy from shared memory to private memory.

UPC: Distributed Shared Memory Programming, by Tarek El-Ghazawi, William Carlson, Thomas Sterling, and Katherine Yelick
Published 2005 John Wiley & Sons, Inc.