Library section boilerplate spec text

[Former user]

Originally reported on Google Code with ID 91

Split from issue 9 - Gary said:

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 danbonachea on 2012-09-25 03:57:27

[Former user]

```

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

Yes, of course it does... This same argument could be made about all of the core libraries, since nothing explicitly says "yes, upc.h declares upc_all_alloc()", it is merely implied by the section organization.

C99 handles this with an introductory paragraph to each library section that reads something like:

"The header <stdio.h> declares three types, several macros, and many functions for performing input and output."

I suppose we should add this to the upc.h introduction and also the boilerplate for any other UPC libraries..

```

Reported by `danbonachea` on 2012-09-25 03:58:10

[Former user]

``` Change announcement mailed 9/25/2012:

Proposed Change: ------------------------- --- upc-lib-core.tex (revision 143) +++ upc-lib-core.tex (working copy) @@ -29,11 +29,18 @@

\pagebreak \subsection{UPC utilities \tt{<upc.h>}} +\label{upc_h}

\npf This subsection provides the UPC parallel extensions of [ISO/IEC00 Sec 7.20]. All of the characteristics of library functions described in [ISO/IEC00 Sec 7.1.4] apply to these as well.

+\np \xadded[id=DB]{91}{ + Unless otherwise noted, all of the functions, types and macros + specified in Section\ref{upc_h} + are declared by the header {\tt <upc.h>}. + } + \subsubsection{Termination of all threads} \label{upc_global_exit}

--- upc-lib-tick.tex (revision 143) +++ upc-lib-tick.tex (working copy) @@ -34,7 +34,13 @@ <upc_tick.h> \end{verbatim}

-\np The header {\tt upc\_tick.h} defines two macros, and declares one type for manipulating time. +\np \xreplaced[id=DB]{91}{ + Unless otherwise noted, all of the functions, types and macros + specified in Section\ref{upc-tick} + are declared by the header {\tt <upc\_tick.h>}. + }{ + The header {\tt upc\_tick.h} defines two macros, and declares one type for manipulating time. + }

\paragraph{upc\_tick\_t Type} \index{upc\_tick\_t}

--- upc-lib-collectives.tex (revision 143) +++ upc-lib-collectives.tex (working copy) @@ -23,6 +23,12 @@

{\tt <upc\_collective.h>}

+\np \xadded[id=DB]{91}{ + Unless otherwise noted, all of the functions, types and macros + specified in Section\ref{upc-collective} + are declared by the header {\tt <upc\_collective.h>}. + } + \subsubsection{Relocalization Operations}

\paragraph{The {\tt upc\_all\_broadcast} function} ```

Reported by `danbonachea` on 2012-09-25 22:28:50 - Status changed: `PendingApproval` - Labels added: Consensus-High - Labels removed: Consensus-Low

[Former user]

``` Side note - authors of proposed library documents should incorporate an analogous clarification. ```

Reported by `danbonachea` on 2012-09-26 00:12:37

[Former user]

``` Missed one header in the above diff:

--- upc-lib-io.tex (revision 150) +++ upc-lib-io.tex (working copy) @@ -1,4 +1,5 @@ \subsection{UPC Parallel I/O {\tt <upc\_io.h>}} +\label{upc-io} \index{\_\_UPC\_IO\_\_} \index{upc\_io.h}

@@ -8,6 +9,12 @@ that support this interface shall predefine the feature macro {\tt \_\_UPC\_IO\_\_} to the value 1.

+\np \xadded[id=DB]{91}{ + Unless otherwise noted, all of the functions, types and macros + specified in Section\ref{upc-io} + are declared by the header {\tt <upc\_io.h>}. + } + {\bf Common Constraints}

\index{upc\_flag\_t}

```

Reported by `danbonachea` on 2012-10-07 16:41:33

[Former user]

these issues have all reached the end of their 4-week comment period 
and were accepted into the working draft at the 10/31 telecon.
Committed SVN r181

Reported by danbonachea on 2012-10-31 20:49:32 - Status changed: Ratified