Utility for converting PTS to human-readable text

[Former user]

Originally reported on Google Code with ID 108

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. 

Reported by danbonachea on 2013-03-01 13:46:08

[Former user]

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().

Reported by danbonachea on 2013-03-01 13:47:43 - Labels added: Type-Enhancement - Labels removed: Type-Defect

[Former user]

> 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.

Reported by danbonachea on 2013-03-01 14:05:30

[Former user]

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.

Reported by danbonachea on 2013-03-01 19:17:47