Utility for converting PTS to human-readable text

[GoogleCodeExporter]

Split off from issue 107, which has gone in a totally different direction. 

Provide a utility for converting PTS to human-readable text, for use in 
printf-style debugging (which for better or worse is perceived to have 
widespread use in real UPC application development efforts).

The resolution to 107 may partially obviate the need for this feature (by 
giving users a tool to "roll-their-own") but it still might be a handy feature 
to package up in library form, and allow the implementation to possibly expose 
additional state details that might be useful in debugging.

As a starting point for discussion, here is the pseudo-spec for the BUPC 
vendor-specific replacement: 
(http://upc.lbl.gov/docs/user/index.shtml#bupc_dump_shared)

----------------------------------------------
The 'bupc_dump_shared' function
Shared pointers in UPC are logically composed of three fields: the address of 
the data that the shared pointer currently points to, the UPC thread on which 
that address is valid, and the 'phase' of the shared pointer (see the official 
UPC language specification for an explanation of shared pointer phase). Our 
version of UPC provides a 'bupc_dump_shared' function that will write a 
description of these fields into a character buffer that the user provides:

    int bupc_dump_shared(shared const void *ptr, char *buf, int maxlen);

Any pointer to a shared type may be passed to this function. The 'maxlen' 
parameter gives the length of the buffer pointed to by 'buf', and this length 
must be at least BUPC_DUMP_MIN_LENGTH, or else -1 is returned, and errno set to 
EINVAL. On success, the function returns 0, The buffer will contain either 
"<NULL>" if the pointer to shared == NULL, or a string of the form

    "<address=0x1234 (addrfield=0x1234), thread=4, phase=1>" 

The 'address' field provides the virtual address for the pointer, while the 
'addrfield' contains the actual contents of the shared pointer's address bits. 
On some configurations these values may be the same (if the full address of the 
pointer can be fit into the address bits), while on others they may be quite 
different (if the address bits store an offset from a base initial address that 
may differ from thread to thread).

Both bupc_dump_shared() and BUPC_DUMP_MIN_LENGTH are visible when any of the 
standard UPC headers (upc.h, upc_relaxed.h, or upc_strict.h) are #included. 

Original issue reported on code.google.com by danbonachea on 1 Mar 2013 at 1:46