Skip to content

Commit 3505d30

Browse files
sei-smcmillansei-smcmillan
committed
CLEAN 2.0 SPEC!!
Turned off all "NEW CONTENT" annotations. Removed obsolete comments. Removed color (except in changelog). Normalized a small bit of notation defining the intermediate vector/matrix across all operations (there is more todo).
1 parent 4b35c00 commit 3505d30

15 files changed

+67
-286
lines changed

‎graph-api-c/GraphBLAS_API_C.tex

+12-26
Original file line numberDiff line numberDiff line change
@@ -95,17 +95,17 @@
9595
\newcommand{\bDin}[1]{\mbox{$\mathbf{D}_{in_{#1}}$}}
9696
\newcommand{\bDout}{\mbox{$\mathbf{D}_{out}$}}
9797

98-
\newcommand{\aydin}[1]{{{\color{orange}[Aydin: #1]}}}
99-
\newcommand{\scott}[1]{{{\color{violet}[Scott: #1]}}}
100-
\newcommand{\tim}[1]{{{\color{teal}[Tim: #1]}}}
101-
\newcommand{\jose}[1]{{{\color{red}[Jose: #1]}}}
102-
\newcommand{\ben}[1]{{{\color{blue}[Ben: #1]}}}
103-
104-
%\newcommand{\aydin}[1]{}
105-
%\newcommand{\scott}[1]{}
106-
%\newcommand{\tim}[1]{}
107-
%\newcommand{\jose}[1]{}
108-
%\newcommand{\ben}[1]{}
98+
%\newcommand{\aydin}[1]{{{\color{orange}[Aydin: #1]}}}
99+
%\newcommand{\scott}[1]{{{\color{violet}[Scott: #1]}}}
100+
%\newcommand{\tim}[1]{{{\color{teal}[Tim: #1]}}}
101+
%\newcommand{\jose}[1]{{{\color{red}[Jose: #1]}}}
102+
%\newcommand{\ben}[1]{{{\color{blue}[Ben: #1]}}}
103+
104+
\newcommand{\aydin}[1]{}
105+
\newcommand{\scott}[1]{}
106+
\newcommand{\tim}[1]{}
107+
\newcommand{\jose}[1]{}
108+
\newcommand{\ben}[1]{}
109109

110110
%\aydin{testing}
111111
%\scott{testing}
@@ -243,9 +243,7 @@ \section*{Acknowledgments}
243243
\item Carl Yang (UC Davis)
244244
\end{itemize}
245245

246-
\scott{TODO: NEED TO UPDATE THIS OR ADD A NEW SECTION FOR 2.0}
247-
248-
The GraphBLAS specification is based upon work funded and supported in part by:
246+
The GraphBLAS C API Specification is based upon work funded and supported in part by:
249247
\begin{itemize}
250248
\item NSF Graduate Research Fellowship under Grant No. DGE 1752814 and by the NSF under Award No. 1823034 with the University of California, Berkeley
251249
\item The Department of Energy Office of Advanced Scientific Computing Research under contract number DE-AC02-05CH11231
@@ -290,16 +288,6 @@ \chapter{Introduction}
290288
that supports acquire-release memory orders. This is needed to support
291289
the memory models required for multithreaded execution as described in section~\ref{Sec:MultiThread}.
292290

293-
%We anticipate that given the diverse platforms that may support the GraphBLAS C API, certain
294-
%specific features may not be practical to support. An implementation of the GraphBLAS C API
295-
%may still call itself ``conformant'' to this specification if the following conditions hold.
296-
%\begin{enumerate}
297-
%\item Every method defined in the GraphBLAS specification is supported for at least one combination of input parameters.
298-
%\item This situation must be documented as an \emph{implementation} defined feature of the implementation of the GraphBLAS.
299-
%\item This situation is caught as an API error (section~\ref{Sec:ErrorModel}) and the parameter {\sf GrB\_NOT\_IMPLEMENTED}
300-
%is returned by the associated method call.
301-
%\end{enumerate}
302-
303291
Implementations of the GraphBLAS C API will target a wide range of platforms. We expect cases will arise where it will be
304292
prohibitive for a platform to support a particular type or a specific parameter for a method defined by the GraphBLAS C API. We
305293
want to encourage implementors to support the GraphBLAS C API even when such cases arise. Hence, an implementation
@@ -320,7 +308,6 @@ \chapter{Introduction}
320308
\item Chapter~\ref{Chp:Concepts}: Basic Concepts
321309
\item Chapter~\ref{Chp:Objects}: Objects
322310
\item Chapter~\ref{Chp:Methods}: Methods
323-
%\item Chapter~\ref{Chp:Extensions}: Possible Extensions (ABAB: put back when needed)
324311
\item Chapter~\ref{Chp:Nonpolymorphic}: Nonpolymorphic Interface
325312
\item Appendix~\ref{Chp:RevHistory}: Revision History
326313
\item Appendix~\ref{App:Matrix_format_details}: Non-Opaque Data Format Definitions
@@ -368,7 +355,6 @@ \section{Object Methods}
368355
\input{ops_reduce_transpose}
369356
\input{ops_kronecker}
370357

371-
%\input{sequence_termination}
372358

373359
%=============================================================================
374360
%=============================================================================

‎graph-api-c/basic_concepts.tex

+10-52
Original file line numberDiff line numberDiff line change
@@ -215,22 +215,6 @@ \subsection{The execution of an application using the GraphBLAS C API}
215215
subgraph of that DAG. An ordered collection of GraphBLAS method calls in program order that
216216
defines that subgraph for a particular object is the \emph{sequence} for that object.
217217

218-
\comment{
219-
\glossItem{sequence} A series of contiguous GraphBLAS method calls in a thread,
220-
in program order. An implementation of the GraphBLAS may
221-
reorder or even fuse GraphBLAS methods within a sequence as long as the
222-
definitions of any GraphBLAS object that is later read by an application
223-
are not changed; by ``read'' we mean that values are copied from an
224-
opaque GraphBLAS object into a non-opaque object.
225-
226-
A sequence begins when a thread calls its first GraphBLAS method either
227-
(1) after it starts executing or (2) after termination of the previous
228-
sequence. In blocking mode, every GraphBLAS method call is its own
229-
sequence, and implicitly terminates it on return. In nonblocking mode,
230-
a sequence is terminated by either (1) a call to {\sf GrB\_finalize()}
231-
or (2) a call to {\sf GrB\_wait()}.
232-
}
233-
234218
\glossItem{complete} A GraphBLAS object is complete when it can be used in a happens-before relationship
235219
with a method call that reads the variable on another thread. This concept is used
236220
when reasoning about memory orders in multithreaded programs. A GraphBLAS object defined on one thread
@@ -240,28 +224,6 @@ \subsection{The execution of an application using the GraphBLAS C API}
240224
complete after a GraphBLAS method call that writes to that object returns. In nonblocking-mode, an object is complete
241225
after a call to the {\sf GrB\_wait()} method with the {\sf GrB\_COMPLETE} parameter.
242226

243-
\comment{
244-
A GraphBLAS object is fully defined by the sequence
245-
of method calls that produce the object as an output. In blocking mode,
246-
each method call completes upon return. In non-blocking mode,
247-
the execution of a method call may be deferred. A method call with output
248-
object {\sf obj} is said to be complete in non-blocking mode
249-
when the first {\sf GrB\_wait(obj)} invoked after it has returned.
250-
A complete method call cannot incur
251-
additional execution time or generate additional errors.}
252-
253-
\comment{
254-
\glossItem{materialize} To cause the values associated with an object to be
255-
produced and stored
256-
in memory. A GraphBLAS object has been
257-
\emph{materialized} when the computations that implement the mathematical definition
258-
of the object are {\it complete}.
259-
A GraphBLAS object that is never loaded into a non-opaque data structure may
260-
potentially never be materialized. This might happen, for example, if the operations
261-
associated with the object are fused or otherwise changed by the runtime system
262-
that supports the implementation of the GraphBLAS C API.
263-
}
264-
265227
\glossItem{materialize} A GraphBLAS object is materialized when it is (1) complete, (2) the computations
266228
defined by the sequence that define the object have finished (either fully or stopped at an error) and will not consume any
267229
additional computational resources, and (3) any errors associated with that sequence are available to be read according to the
@@ -508,18 +470,16 @@ \section{GraphBLAS Opaque Objects}
508470
should be destroyed by a call to {\sf GrB\_free}. The behavior of a program
509471
that calls {\sf GrB\_free} on a pre-defined object is undefined.
510472

511-
\comment{
512-
This is typically done with one of
513-
the methods that has a ``{\sf \_new}'' suffix in its name (e.g.,
514-
{\sf GrB\_Vector\_new}). If available, an object can also be initialized by
515-
duplicating an existing object with one of the methods that has the
516-
``{\sf \_dup}'' suffix in its name (e.g., {\sf GrB\_Vector\_dup}). Note that
517-
there are other valid constructor methods included in the API (e.g.,
518-
``{\sf \_diag}'', ``{\sf \_import}'', and ``{\sf \_deserialize}'' matrix
519-
methods). Regardless of the method of construction, any resources associated
520-
with that object can be released (destructed) by a call to the {\sf GrB\_free}
521-
method when an application is finished with an object.
522-
}
473+
%This is typically done with one of
474+
%the methods that has a ``{\sf \_new}'' suffix in its name (e.g.,
475+
%{\sf GrB\_Vector\_new}). If available, an object can also be initialized by
476+
%duplicating an existing object with one of the methods that has the
477+
%``{\sf \_dup}'' suffix in its name (e.g., {\sf GrB\_Vector\_dup}). Note that
478+
%there are other valid constructor methods included in the API (e.g.,
479+
%``{\sf \_diag}'', ``{\sf \_import}'', and ``{\sf \_deserialize}'' matrix
480+
%methods). Regardless of the method of construction, any resources associated
481+
%with that object can be released (destructed) by a call to the {\sf GrB\_free}
482+
%method when an application is finished with an object.
523483

524484
These constructor and destructor methods are the only methods that change
525485
the value of a handle. Hence, objects changed by these methods are passed
@@ -781,8 +741,6 @@ \subsection{Multi-threaded execution}
781741
\section{Error Model}
782742
\label{Sec:ErrorModel}
783743

784-
%\scott{Should this section also discuss NOT IMPLEMENTED error?} ... No, it doesn't belong here
785-
786744
All GraphBLAS methods return a value of type {\sf GrB\_Info} (an enum) to
787745
provide information available to the system at the time the method returns.
788746
The returned value will be one of the defined values shown in

‎graph-api-c/context_methods.tex

+1-1
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ \subsection{{\sf getVersion}: Get the version number of the standard.}
123123
The {\sf getVersion} method is used to query the major and minor version number of the
124124
GraphBLAS C API specification that the library implements at runtime. To
125125
support compile time queries the following two macros shall also be defined by
126-
the library.\scott{Where should the macros be specified?}
126+
the library.
127127
\begin{verbatim}
128128
#define GRB_VERSION 2
129129
#define GRB_SUBVERSION 0

‎graph-api-c/descriptor_methods.tex

-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ \subsubsection{{\sf Descriptor\_new}: Create new descriptor}
2929
\item[{\sf GrB\_PANIC}] unknown internal error.
3030
\item[{\sf GrB\_OUT\_OF\_MEMORY}] not enough memory available for operation.
3131
\item[{\sf GrB\_NULL\_POINTER}] {\sf desc} pointer is {\sf NULL}.
32-
%\item[{\sf GrB\_INVALID\_VALUE}] {\sf desc} object is already initialized.
3332
\end{itemize}
3433

3534
\paragraph{Description}

‎graph-api-c/error_methods.tex

+2-7
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,5 @@ \subsection{{\sf error}: Retrieve an error string}
4242
string (not a {\sf NULL} pointer) is always a valid error string. The string
4343
that is returned is owned by {\sf obj} and will be valid until the next time
4444
{\sf obj} is used as an {\sf OUT} or {\sf INOUT} parameter or the object is freed
45-
by a call to {\sf GrB\_free(obj)}.
46-
{\color{red}
47-
This is a thread-safe function. It can be safely called by multiple threads for the
48-
same object in a race-free program.}
49-
% This is a thread-safe function. , in the sense that multiple threads can call it
50-
% simultaneously and each will get its own error string back, referring to the
51-
% object passed as {\sf obj}.} \scott{Is this really true?} \jose{Yes, I think it is.}
45+
by a call to {\sf GrB\_free(obj)}. This is a thread-safe function. It can be
46+
safely called by multiple threads for the same object in a race-free program.

0 commit comments

Comments
 (0)