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

[GoogleCodeExporter]

Troy's comment, copied from 
http://code.google.com/p/upc-specification/issues/detail?id=107#c8:

We (too) frequently have users attempt this code:

    shared int* ptr;
    ...
    printf( "%p", ptr );

which does not do what they expect (on our current systems, but used to work on 
older Crays).  The conforming alternative, given that upc_threadof and 
upc_phaseof return a size_t for which there is no format specifier, is the 
verbose:

    printf( "%lu %lu %p", (unsigned long)upc_threadof( ptr ), (unsigned long)upc_phaseof( ptr ),
            upc_addrfield( ptr ) );

I'm sure they'd much rather be able to do this:

    upc_printf( "%P", ptr );

and I think that would cover all user code that I've seen for upc_addrfield, 
but the output format would need to be implementation-defined and the printed 
address value would be just as unspecified as the current upc_addrfield return 
value.  I'm not sure it would be an improvement for implementers given that 
there would be a whole family of printf functions to wrap, but it may be an 
improvement for users.

Paul's response: 

I agree that extending the printf formats to have one for PTS would be nice, 
but it may be hard for some vendors.  Berkeley, for instance, is at the mercy 
of somebody else's libc. Only when using glibc do we have 
register_printf_function().

Original comment by danbonachea on 1 Mar 2013 at 1:47

• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

> I'm not sure it would be an improvement for implementers given that there 
would be a 
> whole family of printf functions to wrap, but it may be an improvement for 
users.

I don't recall the full motivation behind the design of bupc_dump_shared, but I 
believe we wanted to avoid the (small) implementation burden of creating a 
whole family of printf wrappers to accomplish this task, when a single function 
with string output was sufficient. 

A secondary concern is profiling/tracing tools may want to perform a large 
number of these conversions for storage of pointer information in internal data 
structures (ie not directly for output). For that client, the additional 
overhead of scanning a printf format specifier on each invocation is 
unnecessary and undesirable.

If something along the lines of Troy's proposal of upc_printf() has mass 
appeal, we could easily provide that in addition to our vendor-specific 
utility. Contrary to what Paul said, I think we could even pull some sneaky 
tricks to make it work under the name printf(), although requiring that for 
spec compliance is probably unacceptable.

Original comment by danbonachea on 1 Mar 2013 at 2:05

[GoogleCodeExporter]

As a clarification in response to an email from Gary, I am NOT pushing for the 
inclusion of this library extension in 1.3. I haven't heard anyone else ask for 
that either.

We are way past the point for proposing new library extensions, and this one 
doesn't even have anything like consensus on API yet. For now I'm perfectly 
happy to leave this as a vendor extension, and consider it as an addition in 
1.4.

Original comment by danbonachea on 1 Mar 2013 at 7:17