Library: High-Performance Wall-Clock Timers (upc_tick_t)

[Former user]

Originally reported on Google Code with ID 9 ``` The UPC spec working group agreed there was no outstanding issue for the Proposal for High-Performance Wall-Clock Timers in UPC. It is ready for subsequent review/acceptance into the required library specification.

```

Reported by `[e-mail]` on 2012-04-12 21:22:03

<hr>

• *Attachment: [Upc_tick_0.2.pdf](https://storage.googleapis.com/google-code-attachments/upc-specification/issue-9/comment-0/Upc_tick_0.2.pdf)*

[Former user]

``` As the original author I will accept responsibility for merging in this library spec document, once the process for doing so is clarified. ```

Reported by `danbonachea` on 2012-05-31 17:13:00

[Former user]

Reported by `[e-mail]` on 2012-06-01 03:41:47 - Labels added: Spec-1.3

[Former user]

Reported by `[e-mail]` on 2012-06-01 06:08:32 - Labels added: Milestone-Spec-1.3 - Labels removed: Spec-1.3

[Former user]

``` (Updated 'Type' to "Enhancement") ```

Reported by `nspark.work` on 2012-06-18 21:17:52 - Labels added: Type-Enhancement - Labels removed: Type-Defect

[Former user]

Reported by `gary.funck` on 2012-07-03 18:07:50 - Labels added: Type-Lib-Required - Labels removed: Type-Enhancement

[Former user]

Reported by `gary.funck` on 2012-07-03 18:11:10

[Former user]

``` The original upc_tick_t proposal from 2007 has been reformatted to exactly match the UPC spec boilerplate. There are no semantic changes, and the only wording change was to remove an irrelevant paragraph describing the state of prototype implementations. The updated PDF output is attached.

It has been temporarily committed to the repo under "proposed", but after the 2 week (4 week?) comment period it will be moved into the required library section for 1.3, as previously agreed.

```

Reported by `danbonachea` on 2012-08-11 21:01:07

<hr>

• *Attachment: [upc-lib-tick-spec-draft.pdf](https://storage.googleapis.com/google-code-attachments/upc-specification/issue-9/comment-7/upc-lib-tick-spec-draft.pdf)*

[Former user]

``` "There are no semantic changes"

Minor clarification: the new library also specifies a dedicated header file <upc_tick.h> for consistency with our current library approach, rather than using <upc.h>. ```

Reported by `danbonachea` on 2012-08-11 21:08:18

[Former user]

Reported by `danbonachea` on 2012-08-18 20:14:36 - Status changed: `PendingApproval`

[Former user]

``` Set Consensus:High on Pending Approval issues. ```

Reported by `gary.funck` on 2012-08-19 23:31:54 - Labels added: Consensus-High

[Former user]

``` upc_tick.h section has been added to the required library document in SVN r113 lib/proposed/tick directory is now dead and has been removed from SVN minor pagination tweaks to the required spec to accomodate the new section ```

Reported by `danbonachea` on 2012-09-14 01:21:42 - Status changed: `Fixed`

[Former user]

``` For the record: Public comment period for this change was 8/14/2012 - 9/14/2012 No substantial objections were raised or recorded during that period. At the 9/7/2012 telecon, it was announced this change was imminent, feedback was explicitly solicited, and none was received. The change was integrated into a working draft distributed on 9/13/2012 for consideration and draft ratification at the 9/14/2012 telecon. ```

Reported by `danbonachea` on 2012-09-14 07:26:14

[Former user]

``` Changes distributed as Draft 1.1 were ratified during the 9/14/2012 teleconference, for inclusion in the next public draft. ```

Reported by `danbonachea` on 2012-09-14 21:46:01 - Status changed: `Ratified`

[Former user]

``` Reviewing this proposed spec., a few observations/questions.

Here:

1. include <upc_tick.h>
2. include <stdint.h>

uint64_t upc_ticks_to_ns(upc_tick_t ticks);

The collectives library as an example, always includes <upc.h> first. For collectives, this makes sense because upc.h defines things like upc_flag_t which are needed. What about other libraries (esp. required libraries), even if there is no definite need?

Above, <stdint.h> introduces uint64_t. Given that upc_tick.h defines the prototype shown above, or a macro of the same name, should the include of <stdint.h> precede the include of <upc_tick.h>?

In <upc.h>, there is an implicit include of <sys/types.h>:

/* required, to define size_t */

1. include <sys/types.h>

Thus, the user is not required to pre-include <sys/types.h>. Should we take a similar approach here and bury the implicit include of <stdint.h>?

The following question applies to both the definition of upc_ticks_now() below, and similar UPC library-defined prototypes where the function has no arguments.

upc_tick_t upc_ticks_now();

Should this be written as:

upc_tick_t upc_ticks_now(void);

(I don't recall at the moment whether C99 prescribes this form of a prototype.)

```

Reported by `gary.funck` on 2012-09-22 19:54:02

[Former user]

``` The Berkeley timer extensions described here: http://upc.lbl.gov/docs/user/

Define some additional wall clock timer functions:

uint64_t bupc_ticks_to_us (bupc_tick_t ticks); double bupc_ticks_granularityus (); double bupc_ticks_overheadus ();

I don't understand the motivation for returning ticks in microseconds in addition to nanoseconds. One motivation might be to accommodate a smaller returned value (uint32_t for example), but that is not the case. Perhaps this just a convenience function.

I can see the value of returning the granularity, and an approximation of the average overhead. This can be useful for benchmarks, for example. I don't understand why those values are returned as doubles however when everything else is either a upc_tick_t or a uint64_t.

Perhaps the reasons that these functions are not carried forward into the specification has been discussed already. If so, perhaps that reasoning process can be documented in this issue.

Note that when the decision is made not to propagate already existing vendor-supplied functions into the specification, it potentially increases the likelihood that those vendor-specific functions will be retained.

```

Reported by `gary.funck` on 2012-09-22 20:57:33

[Former user]

``` "What about other libraries (esp. required libraries), even if there is no definite need?"

1. including the header in the Synopsis which declares the library function being documented is the standard format used in the C99 spec. It is always done this way, regardless of whether the function declaration actually requires any types or anything else from the header (eg see C99 7.4 ctype.h functions). It's a traditional form of documentation that reminds the client which header is needed in his program to access this function.

You are correct that upc_tick.h will already need to include other headers (eg stdint.h) that define uint64_t before it can declare its own functions, so I think this means the clients of the tick interface can safely assume that has already been taken care of. I will go ahead and remove the include stdint.h line.

"The following question applies to both the definition of upc_ticks_now() below, and similar UPC library-defined prototypes where the function has no arguments."

You are absolutely correct - omitting the (void) argument is legal but leaves the function declaration as incomplete. This is a personal bad habit of mine, and I will fix it immediately. Please let me know if you see this anywhere else in the spec.

uint64_t bupc_ticks_to_us (bupc_tick_t ticks); double bupc_ticks_granularityus (); double bupc_ticks_overheadus ();

These are all just convenience functions of limited value, and I don't see a problem with deprecating the vendor versions once the spec is ratified. The granularity and overhead are just approximated using a straightforward algorithm on all BUPC platforms, which a user could easily write himself using upc_ticks_now(). That's why I never pushed for standardizing them. ```

Reported by `danbonachea` on 2012-09-23 19:40:45

[Former user]

``` In 7.4p1:

"This subsection provides extensions of [ISO/IEC00 Sec 7.23]. All the characteristics of library functions described in [ISO/IEC00 Sec 7.1.4] apply to these as well. Implementations that support this interface shall predefine the feature macro UPC_TICK to the value 1."

Is the intent that the compiler asserts UPC_TICK to 1 via a pre-defined macro mechanism, or might this be asserted by an included <upc.h>? This question of course may also apply to other library-specific predefined macros.

Consider: let's say a compiler has two runtime configurations. In one runtime configuration timers are not supported, in another they are. The compiler itself is agnostic on this point: it is a runtime issue.

In that scenario, it seems that <upc.h> is the place for this.

(This might also be true of the UPC_COLLECTIVE predefined macro at 7.3p1.)

```

Reported by `gary.funck` on 2012-09-25 03:16:49

[Former user]

``` Does <upc_tick.h> also declare the tick-related library functions (or their prototypes)?

In Section 7.4.1:

7.4.1 Standard header 1 The standard header is <upc_tick.h> 2 The header upc_tick.h defines two macros, and declares one type for manipulating time.

This text does not indicate whether the tick-related functions are also defined in <upc_tick.h>.

In one reading of the above statements, <upc_tick.h> might be constrained _only_ to define two macros and one type and nothing else ...

Later in the document:

7.4.2.1 The upc_ticks_now function Synopsis 1 #include <upc_tick.h> upc_tick_t upc_ticks_now();

This seems to imply that <upc_tick.h> defines upc_ticks_now()?

```

Reported by `gary.funck` on 2012-09-25 03:23:44

[Former user]

``` "Implementations that support this interface shall predefine the feature macro UPC_TICK to the value 1."

The word "predefine" implies it is defined before the translation unit is processed, ie not in upc.h. In fact by C99 6.10.8, it would be an error for a header to explicitly

1. define a symbol which is "predefined".

"Consider: let's say a compiler has two runtime configurations. In one runtime configuration timers are not supported, in another they are. The compiler itself is agnostic on this point: it is a runtime issue."

C99 mostly silent on the actual commands that cause translation to occur. One (common) mechanism to "predefine" required macros is simply to include it on the preprocessor line. So in your example above, some compiler wrapper/driver would be responsible for adding things to the compile line like:

-DUPC_TICK -I/path/to/tick/library -L/path/to/tick/library

of course there are many other ways the implementation could achieve the same effect. A similar mechanism would probably be used by third-party implementations of optional UPC libraries to "predefine" their symbol and make the header available.

If you still disagree, please open a new issue, as this point is independent of the addition of the tick library, which is the point of this issue (which is now closed).

I'm opening a new issue for your other comment (issue 91)

```

Reported by `danbonachea` on 2012-09-25 03:57:45