From 07bbe6840a5c582514216747ea43fcc79c06a4f6 Mon Sep 17 00:00:00 2001 From: Raye Kimmerer Date: Thu, 21 Dec 2023 17:44:45 -0500 Subject: [PATCH] Get/Set Proposal (#73) - Issue BB-28 (#14), BB-27 (#13), BB-13 (#5), BB-7 (#4): We added a capability for meta-data associated with each GraphBLAS object and the library implementation (the global scope) as well. This was done through the new `GrB_get` and `GrB_set` methods with `(field, value)` pairs. We also needed a new error code for the case where an attempt is made to write to a write-once feild, `GrB_ALREADY_SET`. - Issue BB-15 (#7), BB-14 (#6): The definition of meta-data on GraphBLAS objects added the ability to interact directly with the type system behind these objects. This required the addition of type codes `(GrB_Type_Code)` and the ability to manage the type system through strings. - We augmented the deserialization method so if passed a type parameter of `GrB_NULL` it will infer type information needed for deserialization of a GraphBLAS matrix. - We added a new built-in descriptor `GrB_COMP_STRUCTURE` and an explicit reference to the default value of a descriptor field, `GrB_DEFAULT` --------- Co-authored-by: Jim Kitchen Co-authored-by: Tim Davis Co-authored-by: tgmattso Co-authored-by: Erik Welch --- .gitignore | 12 ++ graph-api-c/GraphBLAS_API_C.tex | 27 ++- graph-api-c/algebra_methods.tex | 2 +- graph-api-c/appendices.tex | 34 +++- graph-api-c/context_methods.tex | 2 +- graph-api-c/free_methods.tex | 2 +- graph-api-c/nonpolymorphic.tex | 176 ++++++++++++++++++- graph-api-c/objects.tex | 238 ++++++++++++++++++++++++-- graph-api-c/ops_apply.tex | 8 +- graph-api-c/ops_assign.tex | 4 +- graph-api-c/ops_reduce_transpose.tex | 4 +- graph-api-c/ops_select.tex | 4 +- graph-api-c/query_methods.tex | 86 ++++++++++ graph-api-c/vector_matrix_methods.tex | 9 +- 14 files changed, 561 insertions(+), 47 deletions(-) create mode 100644 .gitignore create mode 100644 graph-api-c/query_methods.tex diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..613c412 --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +graph-api-c/GraphBLAS_API_C.aux +graph-api-c/GraphBLAS_API_C.fdb_latexmk +graph-api-c/GraphBLAS_API_C.fls +graph-api-c/GraphBLAS_API_C.lof +graph-api-c/GraphBLAS_API_C.log +graph-api-c/GraphBLAS_API_C.lot +graph-api-c/GraphBLAS_API_C.out +graph-api-c/GraphBLAS_API_C.pdf +graph-api-c/GraphBLAS_API_C.toc +graph-api-c/GraphBLAS_API_C.synctex.gz +# Vi +*.sw? diff --git a/graph-api-c/GraphBLAS_API_C.tex b/graph-api-c/GraphBLAS_API_C.tex index 3dac6aa..13d6902 100644 --- a/graph-api-c/GraphBLAS_API_C.tex +++ b/graph-api-c/GraphBLAS_API_C.tex @@ -133,11 +133,10 @@ \title{ The GraphBLAS C API Specification \footnote{Based on \emph{GraphBLAS Mathematics} by Jeremy Kepner}: \\ -{\large Version 2.0.1} \\ -{\normalsize \scott{THIS IS A DRAFT VERION. Update acks and remove DRAFT before release.}} +{\large Version 2.1} \\ } -\author{Benjamin Brock, Ayd\i n Bulu\c{c}, Timothy Mattson, Scott McMillan, Jos\'e Moreira} +\author{Benjamin Brock, Ayd\i n Bulu\c{c}, Raye Kimmerer, Jim Kitchen, Manoj Kumar, Timothy Mattson, Scott McMillan, Jos\'e Moreira, Erik Welch} \date{Generated on \today\ at \currenttime\ EDT} @@ -149,19 +148,18 @@ \vfill -Copyright \copyright\ 2017-2021 Carnegie Mellon University, The Regents +Copyright \copyright\ 2017-2023 Carnegie Mellon University, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy), the Regents of the University of California (U.C. Davis and U.C. Berkeley), Intel Corporation, International Business Machines -Corporation, and Massachusetts Institute of Technology Lincoln -Laboratory. +Corporation, NVIDIA Corporation, Anaconda Inc., and Massachusetts Institute of Technology. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the United States Department of Defense, the United States Department of Energy, Carnegie Mellon University, the Regents of the -University of California, Intel Corporation, or the IBM Corporation. +University of California, Intel Corporation, NVIDIA Corporation, Anaconda Inc., or IBM Corporation. NO WARRANTY. THIS MATERIAL IS FURNISHED ON AN AS-IS BASIS. THE COPYRIGHT OWNERS AND/OR AUTHORS MAKE NO WARRANTIES OF ANY KIND, EITHER EXPRESSED @@ -225,6 +223,16 @@ \section*{Acknowledgments} This document represents the work of the people who have served on the C API Subcommittee of the GraphBLAS Forum. +Those who served as C API Subcommittee members for GraphBLAS 2.1 are (in alphabetical order): +\begin{itemize} +\item Raye Kimmerer (MIT) +\item Jim Kitchen (Anaconda) +\item Manoj Kumar (IBM) % FIXME +\item Timothy G. Mattson (Human Learning Group) +\item Erik Welch (NVIDIA Corporation) +\end{itemize} + + Those who served as C API Subcommittee members for GraphBLAS 2.0 are (in alphabetical order): \begin{itemize} \item Benjamin Brock (UC Berkeley) @@ -250,10 +258,12 @@ \section*{Acknowledgments} \item Intel Corporation \item Department of Defense under Contract No. FA8702-15-D-0002 with Carnegie Mellon University for the operation of the Software Engineering Institute [DM-0003727, DM19-0929, DM21-0090] \item International Business Machines Corporation +\item NVIDIA Corporation +\item Anaconda Inc. \end{itemize} The following people provided valuable input and feedback during the development of the specification (in alphabetical order): David Bader, -Hollen Barmer, Bob Cook, Tim Davis, Jeremy Kepner, James Kitchen, Peter Kogge, Manoj Kumar, Roi Lipman, Andrew Mellinger, +Hollen Barmer, Bob Cook, Tim Davis, Jeremy Kepner, Jim Kitchen, Peter Kogge, Manoj Kumar, Roi Lipman, Andrew Mellinger, Maxim Naumov, Nancy M. Ott, Michel Pelletier, Gabor Szarnyas, Ping Tak Peter Tang, Erik Welch, Michael Wolf, Albert-Jan Yzelman. \vfill \pagebreak @@ -337,6 +347,7 @@ \section{Object methods} This section describes methods that setup and operate on GraphBLAS opaque objects but are not part of the the GraphBLAS math specification. +\input{query_methods.tex} \input{algebra_methods} \input{scalar_methods} \input{vector_matrix_methods} diff --git a/graph-api-c/algebra_methods.tex b/graph-api-c/algebra_methods.tex index 158ca3f..c88972c 100644 --- a/graph-api-c/algebra_methods.tex +++ b/graph-api-c/algebra_methods.tex @@ -349,7 +349,7 @@ \subsubsection{{\sf Semiring\_new}: Construct a new GraphBLAS semiring} %----------------------------------------------------------------------------- -\subsubsection{{\sf IndexUnaryOp\_new}: Construct a new GraphBLAS index unary operator \scott{NEW CONTENT}} +\subsubsection{{\sf IndexUnaryOp\_new}: Construct a new GraphBLAS index unary operator} Initializes a new GraphBLAS index unary operator with a specified user-defined function and its types (domains). diff --git a/graph-api-c/appendices.tex b/graph-api-c/appendices.tex index a370c4c..d38acf7 100644 --- a/graph-api-c/appendices.tex +++ b/graph-api-c/appendices.tex @@ -2,14 +2,44 @@ \chapter{Revision history} \label{Chp:RevHistory} %-------------------------------------------------------------- -Changes in 2.0.1 (Released: \#\# Xxxxx 2022: +Changes in 2.1.0 (Released: 22 December 2023): % FIXME +\begin{itemize} +\item (Issue BB-28, BB-27, BB-13, BB-7) We added a capability for meta-data associated with each GraphBLAS +object and the library implementation (the global scope) as well. This was done through the new +{\sf GrB\_get} and {\sf GrB\_set} methods with {({\sf field}, {\sf value})} pairs. We also needed + a new error code for the case where an attempt is made to write to a write-once feild, +{\sf GrB\_ALREADY\_SET} + +\item (Issue BB-15, BB-14) The definition of meta-data on GraphBLAS objects added the ability to interact +directly with the type system behind these objects. This required the addition of type +codes ({\sf GrB\_Type\_Code}) and the ability to manage the type system through strings. + +\item We augmented the deserialization method so if passed a type parameter of {\sf GrB\_NULL} +it will infer type information needed for deserialization of a GraphBLAS matrix. + +\item We added a new built-in descriptor {\sf GrB\_COMP\_STRUCTURE} and an explicit reference +to the default value of a descriptor field, {\sf GrB\_DEFAULT}. + +%%% Originial Text .... <<<< remove once we finalize on the above text>>>> +%\item Added {\sf GrB\_get} and {\sf GrB\_set} methods, and associated +%field values to {\sf GrB\_Field}. +%\item Added {\sf GrB\_Type\_Code}. +%\item Added {\sf GrB\_DEFAULT}. +%\item Added {\sf GrB\_COMP\_STRUCTURE}. +%\item Added {\sf GrB\_ALREADY\_SET}. +%\item Allow deserialization when input type parameter is NULL. +\end{itemize} + +%-------------------------------------------------------------- + +Changes in 2.0.1 (Released: 9 December 2022): % Verify Date \begin{itemize} \item (Issue GH-69) Fix error in description of contents of matrix constructed from {\sf GrB\_Matrix\_diag}. \end{itemize} %-------------------------------------------------------------- -Changes in 2.0.0 (Released: 15 November 2021: +Changes in 2.0.0 (Released: 15 November 2021): \begin{itemize} \item Reorganized Chapters 2 and 3: Chapter 2 contains prose regarding the basic concepts captured in the API; Chapter 3 presents all of the enumerations, literals, data types, and predefined objects required by the API. Made short captions for the List of Tables. \item (Issue BB-49, BB-50) Updated and corrected language regarding multithreading and completion, and requirements regarding acquire-release memory orders. Methods that used to force complete no longer do. diff --git a/graph-api-c/context_methods.tex b/graph-api-c/context_methods.tex index d346dd8..127bffc 100644 --- a/graph-api-c/context_methods.tex +++ b/graph-api-c/context_methods.tex @@ -106,7 +106,7 @@ \subsection{{\sf getVersion}: Get the version number of the standard.} \begin{itemize}[leftmargin=1.1in] \item[{\sf version}] ({\sf OUT}) On successful return will hold the value of the major version number. - \item[{\sf version}] ({\sf OUT}) On successful return will hold the value + \item[{\sf subversion}] ({\sf OUT}) On successful return will hold the value of the subversion number. \end{itemize} diff --git a/graph-api-c/free_methods.tex b/graph-api-c/free_methods.tex index 1d8bdfd..293d250 100644 --- a/graph-api-c/free_methods.tex +++ b/graph-api-c/free_methods.tex @@ -38,7 +38,7 @@ \subsection{{\sf free}: Destroy an object and release its resources} so they are available for use by other GraphBLAS objects. The parameter passed into {\sf GrB\_free} is a handle referencing a -GraphBLAS opaque object of a data type from table~\ref{Tab:ObjTypes}. +GraphBLAS opaque object of a data type from Table~\ref{Tab:ObjTypes}. The object must have been created by an explicit call to a GraphBLAS constructor. The behavior of a program that calls {\sf GrB\_free} on a pre-defined object is implementation defined. diff --git a/graph-api-c/nonpolymorphic.tex b/graph-api-c/nonpolymorphic.tex index 0614eb1..f972744 100644 --- a/graph-api-c/nonpolymorphic.tex +++ b/graph-api-c/nonpolymorphic.tex @@ -1,4 +1,4 @@ -\chapter{Nonpolymorphic interface\scott{NEW CONTENT}} +\chapter{Nonpolymorphic interface} \label{Chp:Nonpolymorphic} Each polymorphic GraphBLAS method (those with multiple parameter @@ -429,7 +429,7 @@ \chapter{Nonpolymorphic interface\scott{NEW CONTENT}} \begin{landscape} \begin{table}[htb] -\caption{Long-name, nonpolymorphic form of GraphBLAS methods (continued).\scott{NEW CONTENT}} +\caption{Long-name, nonpolymorphic form of GraphBLAS methods (continued).} {\scriptsize \hspace*{-3em}\begin{tabular}{l|l} Polymorphic signature & Nonpolymorphic signature \\ @@ -471,7 +471,7 @@ \chapter{Nonpolymorphic interface\scott{NEW CONTENT}} \begin{table}[htb] -\caption{Long-name, nonpolymorphic form of GraphBLAS methods (continued).\scott{NEW CONTENT}} +\caption{Long-name, nonpolymorphic form of GraphBLAS methods (continued).} {\scriptsize \hspace*{-2em}\begin{tabular}{l|l} Polymorphic signature & Nonpolymorphic signature \\ @@ -566,3 +566,173 @@ \chapter{Nonpolymorphic interface\scott{NEW CONTENT}} \label{Tab:NonPolymorphic6} \end{table} \end{landscape} + +%----------------------------------------------------------------------------- + +\begin{table}[htb] +\caption{Long-name, nonpolymorphic form of GraphBLAS methods (continued).} +{\scriptsize +\hspace*{-2em}\begin{tabular}{l|l} +Polymorphic signature & Nonpolymorphic signature \\ +\hline + +{\sf GrB\_get(GrB\_Scalar,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Scalar\_get\_Scalar(GrB\_Scalar,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Scalar,char*,GrB\_Field)} & {\sf GrB\_Scalar\_get\_String(GrB\_Scalar,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Scalar,int32\_t*,GrB\_Field)} & {\sf GrB\_Scalar\_get\_INT32(GrB\_Scalar,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Scalar,size\_t*,GrB\_Field)} & {\sf GrB\_Scalar\_get\_SIZE(GrB\_Scalar,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Scalar,void*,GrB\_Field)} & {\sf GrB\_Scalar\_get\_VOID(GrB\_Scalar,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_Vector,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Vector\_get\_Scalar(GrB\_Vector,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Vector,char*,GrB\_Field)} & {\sf GrB\_Vector\_get\_String(GrB\_Vector,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Vector,int32\_t*,GrB\_Field)} & {\sf GrB\_Vector\_get\_INT32(GrB\_Vector,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Vector,size\_t*,GrB\_Field)} & {\sf GrB\_Vector\_get\_SIZE(GrB\_Vector,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Vector,void*,GrB\_Field)} & {\sf GrB\_Vector\_get\_VOID(GrB\_Vector,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_Matrix,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Matrix\_get\_Scalar(GrB\_Matrix,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Matrix,char*,GrB\_Field)} & {\sf GrB\_Matrix\_get\_String(GrB\_Matrix,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Matrix,int32\_t*,GrB\_Field)} & {\sf GrB\_Matrix\_get\_INT32(GrB\_Matrix,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Matrix,size\_t*,GrB\_Field)} & {\sf GrB\_Matrix\_get\_SIZE(GrB\_Matrix,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Matrix,void*,GrB\_Field)} & {\sf GrB\_Matrix\_get\_VOID(GrB\_Matrix,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_UnaryOp,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_UnaryOp\_get\_Scalar(GrB\_UnaryOp,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_UnaryOp,char*,GrB\_Field)} & {\sf GrB\_UnaryOp\_get\_String(GrB\_UnaryOp,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_UnaryOp,int32\_t*,GrB\_Field)} & {\sf GrB\_UnaryOp\_get\_INT32(GrB\_UnaryOp,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_UnaryOp,size\_t*,GrB\_Field)} & {\sf GrB\_UnaryOp\_get\_SIZE(GrB\_UnaryOp,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_UnaryOp,void*,GrB\_Field)} & {\sf GrB\_UnaryOp\_get\_VOID(GrB\_UnaryOp,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_IndexUnaryOp,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_IndexUnaryOp\_get\_Scalar(GrB\_IndexUnaryOp,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_IndexUnaryOp,char*,GrB\_Field)} & {\sf GrB\_IndexUnaryOp\_get\_String(GrB\_IndexUnaryOp,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_IndexUnaryOp,int32\_t*,GrB\_Field)} & {\sf GrB\_IndexUnaryOp\_get\_INT32(GrB\_IndexUnaryOp,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_IndexUnaryOp,size\_t*,GrB\_Field)} & {\sf GrB\_IndexUnaryOp\_get\_SIZE(GrB\_IndexUnaryOp,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_IndexUnaryOp,void*,GrB\_Field)} & {\sf GrB\_IndexUnaryOp\_get\_VOID(GrB\_IndexUnaryOp,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_BinaryOp,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_BinaryOp\_get\_Scalar(GrB\_BinaryOp,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_BinaryOp,char*,GrB\_Field)} & {\sf GrB\_BinaryOp\_get\_String(GrB\_BinaryOp,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_BinaryOp,int32\_t*,GrB\_Field)} & {\sf GrB\_BinaryOp\_get\_INT32(GrB\_BinaryOp,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_BinaryOp,size\_t*,GrB\_Field)} & {\sf GrB\_BinaryOp\_get\_SIZE(GrB\_BinaryOp,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_BinaryOp,void*,GrB\_Field)} & {\sf GrB\_BinaryOp\_get\_VOID(GrB\_BinaryOp,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_Monoid,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Monoid\_get\_Scalar(GrB\_Monoid,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Monoid,char*,GrB\_Field)} & {\sf GrB\_Monoid\_get\_String(GrB\_Monoid,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Monoid,int32\_t*,GrB\_Field)} & {\sf GrB\_Monoid\_get\_INT32(GrB\_Monoid,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Monoid,size\_t*,GrB\_Field)} & {\sf GrB\_Monoid\_get\_SIZE(GrB\_Monoid,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Monoid,void*,GrB\_Field)} & {\sf GrB\_Monoid\_get\_VOID(GrB\_Monoid,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_Semiring,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Semiring\_get\_Scalar(GrB\_Semiring,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Semiring,char*,GrB\_Field)} & {\sf GrB\_Semiring\_get\_String(GrB\_Semiring,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Semiring,int32\_t*,GrB\_Field)} & {\sf GrB\_Semiring\_get\_INT32(GrB\_Semiring,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Semiring,size\_t*,GrB\_Field)} & {\sf GrB\_Semiring\_get\_SIZE(GrB\_Semiring,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Semiring,void*,GrB\_Field)} & {\sf GrB\_Semiring\_get\_VOID(GrB\_Semiring,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_Descriptor,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Descriptor\_get\_Scalar(GrB\_Descriptor,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Descriptor,char*,GrB\_Field)} & {\sf GrB\_Descriptor\_get\_String(GrB\_Descriptor,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Descriptor,int32\_t*,GrB\_Field)} & {\sf GrB\_Descriptor\_get\_INT32(GrB\_Descriptor,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Descriptor,size\_t*,GrB\_Field)} & {\sf GrB\_Descriptor\_get\_SIZE(GrB\_Descriptor,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Descriptor,void*,GrB\_Field)} & {\sf GrB\_Descriptor\_get\_VOID(GrB\_Descriptor,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_Type,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Type\_get\_Scalar(GrB\_Type,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Type,char*,GrB\_Field)} & {\sf GrB\_Type\_get\_String(GrB\_Type,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Type,int32\_t*,GrB\_Field)} & {\sf GrB\_Type\_get\_INT32(GrB\_Type,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Type,size\_t*,GrB\_Field)} & {\sf GrB\_Type\_get\_SIZE(GrB\_Type,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Type,void*,GrB\_Field)} & {\sf GrB\_Type\_get\_VOID(GrB\_Type,void*,GrB\_Field)} \\ +\hline + +{\sf GrB\_get(GrB\_Global,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Global\_get\_Scalar(GrB\_Global,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Global,char*,GrB\_Field)} & {\sf GrB\_Global\_get\_String(GrB\_Global,char*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Global,int32\_t*,GrB\_Field)} & {\sf GrB\_Global\_get\_INT32(GrB\_Global,int32\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Global,size\_t*,GrB\_Field)} & {\sf GrB\_Global\_get\_SIZE(GrB\_Global,size\_t*,GrB\_Field)} \\ +{\sf GrB\_get(GrB\_Global,void*,GrB\_Field)} & {\sf GrB\_Global\_get\_VOID(GrB\_Global,void*,GrB\_Field)} \\ +\hline + +\end{tabular} +} +\label{Tab:NonPolymorphic7} +\end{table} + +%----------------------------------------------------------------------------- + + +\begin{table}[htb] +\caption{Long-name, nonpolymorphic form of GraphBLAS methods (continued).} +{\scriptsize +\hspace*{-2em}\begin{tabular}{l|l} +Polymorphic signature & Nonpolymorphic signature \\ +\hline + +{\sf GrB\_set(GrB\_Scalar,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Scalar\_set\_Scalar(GrB\_Scalar,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Scalar,char*,GrB\_Field)} & {\sf GrB\_Scalar\_set\_String(GrB\_Scalar,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Scalar,int32\_t,GrB\_Field)} & {\sf GrB\_Scalar\_set\_INT32(GrB\_Scalar,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Scalar,void*,GrB\_Field,size\_t)} & {\sf GrB\_Scalar\_set\_VOID(GrB\_Scalar,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_Vector,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Vector\_set\_Scalar(GrB\_Vector,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Vector,char*,GrB\_Field)} & {\sf GrB\_Vector\_set\_String(GrB\_Vector,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Vector,int32\_t,GrB\_Field)} & {\sf GrB\_Vector\_set\_INT32(GrB\_Vector,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Vector,void*,GrB\_Field,size\_t)} & {\sf GrB\_Vector\_set\_VOID(GrB\_Vector,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_Matrix,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Matrix\_set\_Scalar(GrB\_Matrix,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Matrix,char*,GrB\_Field)} & {\sf GrB\_Matrix\_set\_String(GrB\_Matrix,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Matrix,int32\_t,GrB\_Field)} & {\sf GrB\_Matrix\_set\_INT32(GrB\_Matrix,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Matrix,void*,GrB\_Field,size\_t)} & {\sf GrB\_Matrix\_set\_VOID(GrB\_Matrix,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_UnaryOp,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_UnaryOp\_set\_Scalar(GrB\_UnaryOp,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_UnaryOp,char*,GrB\_Field)} & {\sf GrB\_UnaryOp\_set\_String(GrB\_UnaryOp,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_UnaryOp,int32\_t,GrB\_Field)} & {\sf GrB\_UnaryOp\_set\_INT32(GrB\_UnaryOp,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_UnaryOp,void*,GrB\_Field,size\_t)} & {\sf GrB\_UnaryOp\_set\_VOID(GrB\_UnaryOp,void*,GrB\_Field,size\_t)} \\ + +{\sf GrB\_set(GrB\_IndexUnaryOp,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_IndexUnaryOp\_set\_Scalar(GrB\_IndexUnaryOp,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_IndexUnaryOp,char*,GrB\_Field)} & {\sf GrB\_IndexUnaryOp\_set\_String(GrB\_IndexUnaryOp,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_IndexUnaryOp,int32\_t,GrB\_Field)} & {\sf GrB\_IndexUnaryOp\_set\_INT32(GrB\_IndexUnaryOp,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_IndexUnaryOp,void*,GrB\_Field,size\_t)} & {\sf GrB\_IndexUnaryOp\_set\_VOID(GrB\_IndexUnaryOp,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_BinaryOp,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_BinaryOp\_set\_Scalar(GrB\_BinaryOp,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_BinaryOp,char*,GrB\_Field)} & {\sf GrB\_BinaryOp\_set\_String(GrB\_BinaryOp,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_BinaryOp,int32\_t,GrB\_Field)} & {\sf GrB\_BinaryOp\_set\_INT32(GrB\_BinaryOp,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_BinaryOp,void*,GrB\_Field,size\_t)} & {\sf GrB\_BinaryOp\_set\_VOID(GrB\_BinaryOp,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_Monoid,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Monoid\_set\_Scalar(GrB\_Monoid,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Monoid,char*,GrB\_Field)} & {\sf GrB\_Monoid\_set\_String(GrB\_Monoid,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Monoid,int32\_t,GrB\_Field)} & {\sf GrB\_Monoid\_set\_INT32(GrB\_Monoid,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Monoid,void*,GrB\_Field,size\_t)} & {\sf GrB\_Monoid\_set\_VOID(GrB\_Monoid,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_Semiring,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Semiring\_set\_Scalar(GrB\_Semiring,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Semiring,char*,GrB\_Field)} & {\sf GrB\_Semiring\_set\_String(GrB\_Semiring,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Semiring,int32\_t,GrB\_Field)} & {\sf GrB\_Semiring\_set\_INT32(GrB\_Semiring,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Semiring,void*,GrB\_Field,size\_t)} & {\sf GrB\_Semiring\_set\_VOID(GrB\_Semiring,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_Descriptor,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Descriptor\_set\_Scalar(GrB\_Descriptor,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Descriptor,char*,GrB\_Field)} & {\sf GrB\_Descriptor\_set\_String(GrB\_Descriptor,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Descriptor,int32\_t,GrB\_Field)} & {\sf GrB\_Descriptor\_set\_INT32(GrB\_Descriptor,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Descriptor,void*,GrB\_Field,size\_t)} & {\sf GrB\_Descriptor\_set\_VOID(GrB\_Descriptor,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_Type,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Type\_set\_Scalar(GrB\_Type,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Type,char*,GrB\_Field)} & {\sf GrB\_Type\_set\_String(GrB\_Type,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Type,int32\_t,GrB\_Field)} & {\sf GrB\_Type\_set\_INT32(GrB\_Type,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Type,void*,GrB\_Field,size\_t)} & {\sf GrB\_Type\_set\_VOID(GrB\_Type,void*,GrB\_Field,size\_t)} \\ +\hline + +{\sf GrB\_set(GrB\_Global,GrB\_Scalar,GrB\_Field)} & {\sf GrB\_Global\_set\_Scalar(GrB\_Global,GrB\_Scalar,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Global,char*,GrB\_Field)} & {\sf GrB\_Global\_set\_String(GrB\_Global,char*,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Global,int32\_t,GrB\_Field)} & {\sf GrB\_Global\_set\_INT32(GrB\_Global,int32\_t,GrB\_Field)} \\ +{\sf GrB\_set(GrB\_Global,void*,GrB\_Field,size\_t)} & {\sf GrB\_Global\_set\_VOID(GrB\_Global,void*,GrB\_Field,size\_t)} \\ +\hline +\end{tabular} +} +\label{Tab:NonPolymorphic7b} +\end{table} \ No newline at end of file diff --git a/graph-api-c/objects.tex b/graph-api-c/objects.tex index a8e32a4..cc1aefd 100644 --- a/graph-api-c/objects.tex +++ b/graph-api-c/objects.tex @@ -110,7 +110,10 @@ \section{Types (domains)} {\tt uint32\_t}, {\tt int64\_t}, {\tt uint64\_t}) are defined in {\tt stdint.h}, and the floating-point types ({\tt float}, {\tt double}) are native to the language and platform and in most cases defined by the -IEEE-754 standard. +IEEE-754 standard. UDT stands for user-defined type and is the type code returned +for all objects which use a non-predefined type. Implementations which add new +types should start their {\sf GrB\_Type\_Code}s at 100 to avoid possible conflicts +with built-in types which may be added in the future. \begin{table} \hrule @@ -125,20 +128,22 @@ \section{Types (domains)} \label{Tab:PredefinedDomains} \vspace{1\baselineskip} -\begin{tabular}{l|l|l|l} -{\sf GrB\_Type} & Suffix & C type & Domain \\ +\begin{tabular}{l|l|l|l|l} +{\sf GrB\_Type} & {\sf GrB\_Type\_Code} & Suffix & C type & Domain \\ \hline -{\sf GrB\_BOOL} & {\sf BOOL} & {\tt bool} & $\{ {\tt false}, {\tt true} \}$ \\ -{\sf GrB\_INT8} & {\sf INT8} & {\tt int8\_t} & $\mathbb{Z} \cap [-2^{7},2^{7})$ \\ -{\sf GrB\_UINT8} & {\sf UINT8} & {\tt uint8\_t} & $\mathbb{Z} \cap [0,2{^8})$ \\ -{\sf GrB\_INT16} & {\sf INT16} & {\tt int16\_t} & $\mathbb{Z} \cap [-2^{15},2^{15})$ \\ -{\sf GrB\_UINT16} & {\sf UINT16} & {\tt uint16\_t} & $\mathbb{Z} \cap [0,2^{16})$ \\ -{\sf GrB\_INT32} & {\sf INT32} & {\tt int32\_t} & $\mathbb{Z} \cap [-2^{31},2^{31})$ \\ -{\sf GrB\_UINT32} & {\sf UINT32} & {\tt uint32\_t} & $\mathbb{Z} \cap [0,2^{32})$ \\ -{\sf GrB\_INT64} & {\sf INT64} & {\tt int64\_t} & $\mathbb{Z} \cap [-2^{63},2^{63})$ \\ -{\sf GrB\_UINT64} & {\sf UINT64} & {\tt uint64\_t} & $\mathbb{Z} \cap [0,2^{64})$ \\ -{\sf GrB\_FP32} & {\sf FP32} & {\tt float} & IEEE 754 {\sf binary32} \\ -{\sf GrB\_FP64} & {\sf FP64} & {\tt double} & IEEE 754 {\sf binary64} +- & {\sf GrB\_UDT\_CODE}=0 & {\sf UDT} & - & - \\ +{\sf GrB\_BOOL} & {\sf GrB\_BOOL\_CODE}=1 & {\sf BOOL} & {\tt bool} & $\{ {\tt false}, {\tt true} \}$ \\ +{\sf GrB\_INT8} & {\sf GrB\_INT8\_CODE}=2 & {\sf INT8} & {\tt int8\_t} & $\mathbb{Z} \cap [-2^{7},2^{7})$ \\ +{\sf GrB\_UINT8} & {\sf GrB\_UINT8\_CODE}=3 & {\sf UINT8} & {\tt uint8\_t} & $\mathbb{Z} \cap [0,2{^8})$ \\ +{\sf GrB\_INT16} & {\sf GrB\_INT16\_CODE}=4 & {\sf INT16} & {\tt int16\_t} & $\mathbb{Z} \cap [-2^{15},2^{15})$ \\ +{\sf GrB\_UINT16} & {\sf GrB\_UINT16\_CODE}=5 & {\sf UINT16} & {\tt uint16\_t} & $\mathbb{Z} \cap [0,2^{16})$ \\ +{\sf GrB\_INT32} & {\sf GrB\_INT32\_CODE}=6 & {\sf INT32} & {\tt int32\_t} & $\mathbb{Z} \cap [-2^{31},2^{31})$ \\ +{\sf GrB\_UINT32} & {\sf GrB\_UINT32\_CODE}=7 & {\sf UINT32} & {\tt uint32\_t} & $\mathbb{Z} \cap [0,2^{32})$ \\ +{\sf GrB\_INT64} & {\sf GrB\_INT64\_CODE}=8 & {\sf INT64} & {\tt int64\_t} & $\mathbb{Z} \cap [-2^{63},2^{63})$ \\ +{\sf GrB\_UINT64} & {\sf GrB\_UINT64\_CODE}=9 & {\sf UINT64} & {\tt uint64\_t} & $\mathbb{Z} \cap [0,2^{64})$ \\ +{\sf GrB\_FP32} & {\sf GrB\_FP32\_CODE}=10 & {\sf FP32} & {\tt float} & IEEE 754 {\sf binary32} \\ +{\sf GrB\_FP64} & {\sf GrB\_FP64\_CODE}=11 & {\sf FP64} & {\tt double} & IEEE 754 {\sf binary64} \\ + \end{tabular} \end{center} \hrule @@ -396,7 +401,7 @@ \subsection{Operators} {\small \begin{tabular}{l|l|cccc|rcll} Operator type & GraphBLAS & \multicolumn{4}{c|}{Domains ($-$ is don't care)} & \multicolumn{4}{c}{Description} \\ -Type & Name & $A,u$ & $i$, $j$ & $s$ & result & &&& \\ \hline +Type & identifier & $A,u$ & $i$, $j$ & $s$ & result & &&& \\ \hline {\sf GrB\_IndexUnaryOp} & {\sf GrB\_ROWINDEX\_$I_{32/64}$} & $-$ & $I_{U64}$ & $I_{32/64}$ & $I_{32/64}$ & $f(A_{ij},i,j,s)$ & $=$ & $(i + s)$, & replace with its row index (+ s) \\ & & $-$ & $I_{U64}$ & $I_{32/64}$ & $I_{32/64}$ & $f(u_{i}, i,0,s)$ & $=$ & $(i + s)$ & \\ {\sf GrB\_IndexUnaryOp} & {\sf GrB\_COLINDEX\_$I_{32/64}$} & $-$ & $I_{U64}$ & $I_{32/64}$ & $I_{32/64}$ & $f(A_{ij},i,j,s)$ & $=$ & $(j + s)$ & replace with its column index (+ s) \\ @@ -823,6 +828,7 @@ \subsection{Masks} %---------------------------------------------------------------------------- %============================================================================ + \section{Descriptors} \label{Sec:Descriptors} @@ -897,7 +903,7 @@ \section{Descriptors} \begin{tabular}{l|l|l} Value Name & Value & Description \\ \hline -(reserved) & 0 & Unused \\ +{\sf GrB\_DEFAULT} & 0 & The default (unset) value for each field. \\ {\sf GrB\_REPLACE} & 1 & Clear the output object before assigning computed values.\\ {\sf GrB\_COMP} & 2 & Use the complement of the associated object. When combined \\ & & with {\sf GrB\_STRUCTURE}, the complement of the structure of the \\ @@ -906,6 +912,7 @@ \section{Descriptors} {\sf GrB\_STRUCTURE} & 4 & The write mask is constructed from the structure (pattern of \\ & & stored values) of the associated object. The stored values are \\ & & not examined.\\ +{\sf GrB\_COMP\_STRUCTURE} & 6 & Shorthand for both {GrB\_COMP} and {GrB\_STRUCTURE}. \\ \end{tabular} \end{center} \hrule @@ -993,6 +1000,199 @@ \section{Descriptors} \hrule \end{table} +\section{Fields} +\label{Sec:Fields} + +All GraphBLAS objects and library implementations contain fields similar to those in descriptors. +These fields provide information to users and let users set runtime parameters or hints. +Users query or set these fields for any GraphBLAS object through {\sf GrB\_get} and {\sf GrB\_set} +methods. +The library implementation itself also contains several (\emph{field}, \emph{value}) pairs, +which provide defaults to object level fields, and implementation information such as the +version number or implementation name. + +The required (\emph{field}, \emph{value}) pairs available for each object are defined in Table~\ref{Tab:Fields}. +Implementations may add their own custom {\sf GrB\_Field} enum values to extend the behavior of objects +and methods. A field must always be readable, but in many cases may not be writable. +Such read-only fields might contain static, compile-time information such as {\sf GrB\_API\_VER}, +while others are determined by other operations, such as {\sf GrB\_BLOCKING\_MODE} +which is determined by {\sf GrB\_Init}. + +{\sf GrB\_INVALID\_VALUE} must be returned when attempting to write to fields which are read only. + +The {\sf GrB\_Field} enumeration is defined by the values in Table~\ref{Tab:Fields}. Selected +values are described in Table~\ref{Tab:Field_Desc}. + +\subsection{Input Types} +\label{Sec:getset_types} +Allowable types used in {\sf GrB\_get} and {\sf GrB\_set} are {\sf INT32}, {\sf GrB\_Scalar}, +{\sf char*}, {\sf void*}, and {\sf SIZE}. Each {\sf GrB\_Field} is associated with exactly one of these +types as defined in Table~\ref{Tab:Fields}. Implementations that add additional {\sf GrB\_Field}s +must document the type associated with each {\sf GrB\_Field}. + +\subsubsection{INT32 } +{\sf INT32} types use a 32-bit signed integer type. This can be used both for +numeric values as well as enumerated {\sf C} types. Enumerated types must specify the +numeric value for each enum, and the value specified must fit within the allowable +32-bit signed integer range. + +\subsubsection{{\sf GrB\_Scalar} } +When calling {\sf GrB\_get}, the user must provide an already initialized {\sf GrB\_Scalar} +object to which the implementation will write a value of the correct element type. +When calling {\sf GrB\_set}, the {\sf GrB\_Scalar} +must not be empty, otherwise a {\sf GrB\_EMPTY\_OBJECT} error is raised. + +\subsubsection{String ({\sf char*}) } +When the input to {\sf GrB\_set} is a {\sf char*}, the input array is a null terminated string. +The {\sf GraphBLAS} implementation must copy this array into internal data structures. +Using {\sf GrB\_get} for strings requires two calls. First, call {\sf GrB\_get} with the +field and object, but pass {\sf size\_t*} as the value argument. The implementation will return +the size of the string buffer that the user must create. Second, call {\sf GrB\_get} with +the field and object, this time passing a pointer to the newly created string buffer. +The {\sf GraphBLAS} implementation will write to this buffer, including a trailing null +terminator. The size returned in the first call will include enough bytes for the null terminator. + +\subsubsection{{\sf void*} } +When the input to {\sf GrB\_set} is a {\sf void*}, an extra {\sf size\_t} argument is passed to +indicate the size of the buffer. The {\sf GraphBLAS} implementation must copy this many bytes +from the buffer into internal data structures. Similar to reading strings, {\sf GrB\_get} must +be called twice for {\sf void*}. The first call passes {\sf size\_t*} to find the required +buffer size. The user must create a buffer and then pass the pointer to {\sf GrB\_get}. The +implementation will write to this buffer. +No standard specification or protocol is required for the contents of {\sf void*}. It is meant +to be a mechanism to allow full freedom for {\sf GraphBLAS} implementations with needs that +cannot be handled using {\sf INT32}, {\sf GrB\_Scalar}, or {\sf String}s. + +\subsubsection{SIZE } +{\sf SIZE} types use a {\sf size\_t} type. Normally, {\sf SIZE} is used in conjunction with {\sf char*} +and {\sf void*} to indicate the buffer size. However, it can also be used when the actual return +type is {\sf size\_t}, as is the case for the size of a Type. + +\subsection{Hints} +\label{Sec:Hints} +Several fields are {\em hints} (marked {\sf H} in Table~\ref{Tab:Fields}). Hints are used +to represent intended use cases or best guesses but do not determine strict behavior. +When {\sf GrB\_set} is called with a hint, the GraphBLAS implementation should +return {\sf GrB\_SUCCESS}, but is free to use or ignore the hint. +When {\sf GrB\_get} is called, the implementation should return a best guess of the +correct answer. If there is no clear answer, the implementation should return {\sf GrB\_UNKNOWN}. + +\subsection{{\sf GrB\_NAME}} +\label{Sec:Name} +The {\sf GrB\_NAME} field is a special case regarding writability. +All user-defined objects have a {\sf GrB\_NAME} field which defaults to an empty string. +Collections and {\sf GrB\_Descriptor}s may have their {\sf GrB\_NAME} set at any time. +User-defined algebraic objects and {\sf GrB\_Type}s may only have their {\sf GrB\_NAME} +set once to a globally unique value. Attempting to set this field after it has already +been set will return a {\sf GrB\_ALREADY\_SET} error code. + +Built-in algebraic objects and {\sf GrB\_Type}s have names which can be read but not written to. +The name returned will be the string form of the {\sf GrB\_Type} listed in Table~\ref{Tab:PredefinedTypes} +or the GraphBLAS identifier listed in Tables~\ref{Tab:PredefOperators}, \ref{Tab:PredefIndexOperators}, +\ref{Tab:PredefinedMonoids}, \ref{Tab:PredefinedTrueSemirings}, +and~\ref{Tab:PredefinedUsefulSemirings}. +For example, the name of GrB\_BOOL type is {\tt "GrB\_BOOL"} (8 characters) and the name of GrB\_MIN\_FP64 binary op +is {\tt "GrB\_MIN\_FP64"} (12 characters). + +The {\sf GrB\_NAME} of the global context is read-only and returns the name of the library implementation. + +\begin{landscape} +\begin{table} +\hrule +\begin{center} +\caption{Field values of type {\sf GrB\_Field} enumeration, corresponding types, and +the objects which must implement that {\sf GrB\_Field}. {\sf Collection} refers to +{\sf GrB\_Matrix}, {\sf GrB\_Vector}, and {\sf GrB\_Scalar}, {\sf Algebraic} refers to +{\sf Operators}, {\sf Monoids}, and {\sf Semirings}, {\sf Type} refers to {\sf GrB\_Type}, +and {\sf Global} refers to the {\sf GrB\_Global} context. All fields may be read, +some may be written (denoted by {\sf W}), and some are hints (denoted by {\sf H}) +which may be ignored by the implementation. For {\sf *} see~\ref{Sec:Fields}} +\label{Tab:Fields} + +\begin{tabular}{l|l|l|l|p{1.9in}} +Field Name & W \(\mid\) H & Value & Implementing Objects & Type \\ \hline +{\sf GrB\_OUTP\_FIELD} & W \(\mid\) --- & 0 & {\sf GrB\_Descriptor} & INT32 ({\sf GrB\_Desc\_Value}) \\ +{\sf GrB\_MASK\_FIELD} & W \(\mid\) --- & 1 & {\sf GrB\_Descriptor} & INT32 ({\sf GrB\_Desc\_Value}) \\ +{\sf GrB\_INP0\_FIELD} & W \(\mid\) --- & 2 & {\sf GrB\_Descriptor} & INT32 ({\sf GrB\_Desc\_Value}) \\ +{\sf GrB\_INP1\_FIELD} & W \(\mid\) --- & 3 & {\sf GrB\_Descriptor} & INT32 ({\sf GrB\_Desc\_Value}) \\ \hline +{\sf GrB\_NAME} & {\sf *} & 10 & {\sf Global}, {\sf Collection}, {\sf Algebraic}, {\sf Type} & Null terminated char* \\ +{\sf GrB\_LIBRARY\_VER\_MAJOR} & --- \(\mid\) --- & 11 & {\sf Global} & INT32 \\ +{\sf GrB\_LIBRARY\_VER\_MINOR} & --- \(\mid\) --- & 12 & {\sf Global} & INT32 \\ +{\sf GrB\_LIBRARY\_VER\_PATCH} & --- \(\mid\) --- & 13 & {\sf Global} & INT32 \\ +{\sf GrB\_API\_VER\_MAJOR} & --- \(\mid\) --- & 14 & {\sf Global} & INT32 \\ +{\sf GrB\_API\_VER\_MINOR} & --- \(\mid\) --- & 15 & {\sf Global} & INT32 \\ +{\sf GrB\_API\_VER\_PATCH} & --- \(\mid\) --- & 16 & {\sf Global} & INT32 \\ +{\sf GrB\_BLOCKING\_MODE} & --- \(\mid\) --- & 17 & {\sf Global} & INT32 ({\sf GrB\_Mode}) \\ \hline +{\sf GrB\_STORAGE\_ORIENTATION\_HINT} & W \(\mid\) H & 100 & {\sf Global}, {\sf Collection} & INT32 ({\sf GrB\_Orientation}) \\ +{\sf GrB\_EL\_TYPE\_CODE} & --- \(\mid\) --- & 102 & {\sf Collection}, {\sf Type} & INT32 ({\sf GrB\_Type\_Code}) \\ \hline +{\sf GrB\_INP0\_TYPE\_CODE} & --- \(\mid\) --- & 103 & {\sf Algebraic} & INT32 ({\sf GrB\_Type\_Code}) \\ +{\sf GrB\_INP1\_TYPE\_CODE} & --- \(\mid\) --- & 104 & {\sf Algebraic} & INT32 ({\sf GrB\_Type\_Code}) \\ +{\sf GrB\_OUTP\_TYPE\_CODE} & --- \(\mid\) --- & 105 & {\sf Algebraic} & INT32 ({\sf GrB\_Type\_Code}) \\ +{\sf GrB\_EL\_TYPE\_STRING} & --- \(\mid\) --- & 106 & {\sf Collection}, {\sf Type} & Null terminated char* \\ +{\sf GrB\_INP0\_TYPE\_STRING} & --- \(\mid\) --- & 107 & {\sf Algebraic} & Null terminated char* \\ +{\sf GrB\_INP1\_TYPE\_STRING} & --- \(\mid\) --- & 108 & {\sf Algebraic} & Null terminated char* \\ +{\sf GrB\_OUTP\_TYPE\_STRING} & --- \(\mid\) --- & 109 & {\sf Algebraic} & Null terminated char* \\ +{\sf GrB\_SIZE} & --- \(|\) --- & 110 & {\sf Type} & SIZE \\ +\hline +\end{tabular} +\end{center} + +\end{table} +\end{landscape} + +\begin{table} +\hrule +\begin{center} +\caption{Descriptions of select \emph{field}, \emph{value} pairs listed in Table~\ref{Tab:Fields}} +\label{Tab:Field_Desc} + +\begin{tabular}{l|p{3.5in}} +Field Name & Description \\ +\hline +{\sf GrB\_NAME} & The name of any GraphBLAS object, \\ + & or the name of the library implementation. \\ +{\sf GrB\_BLOCKING\_MODE} & The blocking mode as set by {\sf GrB\_init} \\ +{\sf GrB\_STORAGE\_ORIENTATION\_HINT} & Hint to the library that a collection is best stored in \\ + & a row (lexicographic) or column (colexicographic) major format. \\ +{\sf GrB\_EL\_TYPE\_(CODE | STRING)} & The element type of a collection. \\ +{\sf GrB\_INP0\_TYPE\_(CODE | STRING)} & The type of the first argument to an operator. \\ + & Returns {\sf GrB\_NO\_VALUE} for Semirings and \\ + & IndexUnaryOps which depend only on the index. \\ +{\sf GrB\_INP1\_TYPE\_(CODE | STRING)} & The type of the second argument to an operator. \\ + & Returns {\sf GrB\_NO\_VALUE} for Semirings, UnaryOps, \\ + & and IndexUnaryOps which depend only on the index. \\ +{\sf GrB\_OUTP\_TYPE\_(CODE | STRING)} & The type of the output of an operator. \\ +{\sf GrB\_SIZE} & The size of the {\sf GrB\_Type}. \\ +\hline +\end{tabular} +\end{center} + +\end{table} + +\begin{table} +\hrule +\begin{center} +\caption[Field value enumerations.]{Enumerations not defined elsewhere in the documents and used +when getting or setting fields are defined in the following tables.} +\label{Tab:FieldValueLiterals} + +\vspace{1\baselineskip} +(a) Field values of type {\sf GrB\_Orientation}. +\vspace{1\baselineskip} + +\begin{tabular}{l|l|l} +Value Name & Value & Description \\ \hline +{\sf GrB\_ROWMAJOR} & 0 & The majority of iteration over the object will be row-wise. \\ +{\sf GrB\_COLMAJOR} & 1 & The majority of iteration over the object will be column-wise. \\ +{\sf GrB\_BOTH} & 2 & Iteration may occur with equal frequency in both directions. \\ +{\sf GrB\_UNKNOWN} & 3 & No indication is given or is unknown. \\ +\end{tabular} + +\end{center} +\hrule +\end{table} + + %============================================================================ \section{{GrB\_Info} return values} @@ -1022,14 +1222,16 @@ \section{{GrB\_Info} return values} \begin{tabular}{l|r|p{3.45in}} Symbol & Value & Description \\ \hline -{\sf GrB\_UNINITIALIZED\_OBJECT} & -1 & A GraphBLAS object is passed to a method before {\sf new} was called on it.\\ +{\sf GrB\_UNINITIALIZED\_OBJECT} & -1 & The {\sf GrB\_Type} object has not + been initialized by a call to {\sf GrB\_Type\_new}\\ {\sf GrB\_NULL\_POINTER} & -2 & A NULL is passed for a pointer parameter. \\ {\sf GrB\_INVALID\_VALUE} & -3 & Miscellaneous incorrect values. \\ {\sf GrB\_INVALID\_INDEX} & -4 & Indices passed are larger than dimensions of the matrix or vector being accessed. \\ {\sf GrB\_DOMAIN\_MISMATCH} & -5 & A mismatch between domains of collections and operations when user-defined domains are in use.\\ {\sf GrB\_DIMENSION\_MISMATCH}~~ & -6 & Operations on matrices and vectors with incompatible dimensions. \\ {\sf GrB\_OUTPUT\_NOT\_EMPTY} & -7 & An attempt was made to build a matrix or vector using an output object that already contains valid tuples (elements).\\ -{\sf GrB\_NOT\_IMPLEMENTED} & -8 & An attempt was made to call a GraphBLAS method for a combination of input parameters that is not supported by a particular implementation.\\ +{\sf GrB\_NOT\_IMPLEMENTED} & -8 & An attempt was made to call a GraphBLAS method for a combination of input parameters that is not supported by a particular implementation.\\ +{\sf GrB\_ALREADY\_SET} & -9 & An attempt was made to write to a field which may only be written to once. \end{tabular} \vspace{1\baselineskip} diff --git a/graph-api-c/ops_apply.tex b/graph-api-c/ops_apply.tex index 71f1f72..83342bc 100644 --- a/graph-api-c/ops_apply.tex +++ b/graph-api-c/ops_apply.tex @@ -442,7 +442,7 @@ \subsubsection{{\sf apply}: Matrix variant} %----------------------------------------------------------------------------- -\subsubsection{{\sf apply}: Vector-BinaryOp variants\scott{NEW CONTENT}} +\subsubsection{{\sf apply}: Vector-BinaryOp variants} Computes the transformation of the values of the stored elements of a vector using a binary operator and a scalar value. In the {\em bind-first} variant, the @@ -748,7 +748,7 @@ \subsubsection{{\sf apply}: Vector-BinaryOp variants\scott{NEW CONTENT}} %-------------------------------------------------------------- -\subsubsection{{\sf apply}: Matrix-BinaryOp variants\scott{NEW CONTENT}} +\subsubsection{{\sf apply}: Matrix-BinaryOp variants} Computes the transformation of the values of the stored elements of a matrix using a binary operator and a scalar value. In the {\em bind-first} variant, the @@ -1093,7 +1093,7 @@ \subsubsection{{\sf apply}: Matrix-BinaryOp variants\scott{NEW CONTENT}} %----------------------------------------------------------------------------- -\subsubsection{{\sf apply}: Vector index unary operator variant\scott{NEW CONTENT}} +\subsubsection{{\sf apply}: Vector index unary operator variant} Computes the transformation of the values of the stored elements of a vector using an index unary operator that is a function of the stored value, its location @@ -1345,7 +1345,7 @@ \subsubsection{{\sf apply}: Vector index unary operator variant\scott{NEW CONTEN %----------------------------------------------------------------------------- -\subsubsection{{\sf apply}: Matrix index unary operator variant\scott{NEW CONTENT}} +\subsubsection{{\sf apply}: Matrix index unary operator variant} Computes the transformation of the values of the stored elements of a matrix using an index unary operator that is a function of the stored value, its location diff --git a/graph-api-c/ops_assign.tex b/graph-api-c/ops_assign.tex index 426a65f..69a8c95 100644 --- a/graph-api-c/ops_assign.tex +++ b/graph-api-c/ops_assign.tex @@ -1397,7 +1397,7 @@ \subsubsection{{\sf assign}: Row variant} %----------------------------------------------------------------------------- -\subsubsection{{\sf assign}: Constant vector variant\scott{NEW CONTENT}} +\subsubsection{{\sf assign}: Constant vector variant} Assign the same value to a specified subset of vector elements. With the use of {\sf GrB\_ALL}, the entire destination vector can be filled with the constant. @@ -1748,7 +1748,7 @@ \subsubsection{{\sf assign}: Constant vector variant\scott{NEW CONTENT}} %----------------------------------------------------------------------------- -\subsubsection{{\sf assign}: Constant matrix variant\scott{NEW CONTENT}} +\subsubsection{{\sf assign}: Constant matrix variant} Assign the same value to a specified subset of matrix elements. With the use of {\sf GrB\_ALL}, the entire destination matrix can be filled with the constant. diff --git a/graph-api-c/ops_reduce_transpose.tex b/graph-api-c/ops_reduce_transpose.tex index 2e3161a..665fcb8 100644 --- a/graph-api-c/ops_reduce_transpose.tex +++ b/graph-api-c/ops_reduce_transpose.tex @@ -245,7 +245,7 @@ \subsubsection{{\sf reduce}: Standard matrix to vector variant} %----------------------------------------------------------------------------- -\subsubsection{{\sf reduce}: Vector-scalar variant\scott{NEW CONTENT}} +\subsubsection{{\sf reduce}: Vector-scalar variant} \label{Sec:Reduce_vector_scalar} Reduce all stored values into a single scalar. @@ -446,7 +446,7 @@ \subsubsection{{\sf reduce}: Vector-scalar variant\scott{NEW CONTENT}} %----------------------------------------------------------------------------- -\subsubsection{{\sf reduce}: Matrix-scalar variant\scott{NEW CONTENT}} +\subsubsection{{\sf reduce}: Matrix-scalar variant} \label{Sec:Reduce_matrix_scalar} Reduce all stored values into a single scalar. diff --git a/graph-api-c/ops_select.tex b/graph-api-c/ops_select.tex index 6e695c8..1b2492b 100644 --- a/graph-api-c/ops_select.tex +++ b/graph-api-c/ops_select.tex @@ -6,7 +6,7 @@ \subsection{{\sf select}:} Apply a select operator to the stored elements of an %----------------------------------------------------------------------------- -\subsubsection{{\sf select}: Vector variant\scott{NEW CONTENT}} +\subsubsection{{\sf select}: Vector variant} Apply a select operator (an index unary operator) to the elements of a vector. @@ -264,7 +264,7 @@ \subsubsection{{\sf select}: Vector variant\scott{NEW CONTENT}} %----------------------------------------------------------------------------- -\subsubsection{{\sf select}: Matrix variant\scott{NEW CONTENT}} +\subsubsection{{\sf select}: Matrix variant} Apply a select operator (an index unary operator) to the elements of a matrix. diff --git a/graph-api-c/query_methods.tex b/graph-api-c/query_methods.tex new file mode 100644 index 0000000..8416e2c --- /dev/null +++ b/graph-api-c/query_methods.tex @@ -0,0 +1,86 @@ +\subsection{Get and Set methods} + +The methods in this section query and, optionally, +set internal fields of GraphBLAS objects. + +%----------------------------------------------------------------------------- +\subsubsection{{\sf get}: Query the value of a field for an object} + +Get the content of a field for an existing GraphBLAS object. + +\paragraph{\syntax} + +\begin{verbatim} + GrB_Info GrB_get(GrB_ obj, value, GrB_Field field); +\end{verbatim} + +\paragraph{Parameters} + +\begin{itemize}[leftmargin=1.1in] + \item[{\sf obj}] ({\sf IN}) An existing, valid GraphBLAS object (collection, operation, type) which is being queried. + To indicate the global context, the constant {\sf GrB\_Global} is used. + \item[{\sf value}] ({\sf OUT}) A pointer to or {\sf GrB\_Scalar} containing a value whose type is dependent on {\sf field} which will be + filled with the current value of the field. {\sf type} may be {\sf int32\_t*}, {\sf size\_t*}, + {\sf GrB\_Scalar}, {\sf char*} or {\sf void*}. + \item[{\sf field}] ({\sf IN}) The field being queried. +\end{itemize} + +\paragraph{Return Value} + +\begin{itemize}[leftmargin=2.1in] +\item[{\sf GrB\_SUCCESS}] The method completed successfully. +\item[{\sf GrB\_PANIC}] unknown internal error. +\item[{\sf GrB\_OUT\_OF\_MEMORY}] not enough memory available for operation. +\item[{\sf GrB\_UNINITIALIZED\_OBJECT}] the {\sf value} parameter is {\sf GrB\_Scalar} and has not been + initialized by a call to the appropriate {\sf new} method. +\item[{\sf GrB\_INVALID\_VALUE}] invalid value type provided for the field or invalid field. +\end{itemize} + +\paragraph{Description} + +This method queries a field of an existing GraphBLAS object. +The type of the argument is uniquely determined by {\sf field}. +For the case of {\sf char*} and {\sf void*}, the value can be replaced with {\sf size\_t*} +to get the required buffer size to hold the response. +Fields marked as hints in Table~\ref{Tab:Fields} will return a hint on how best to use the +object. + +%----------------------------------------------------------------------------- +\subsubsection{{\sf set}: Set a field for an object} + +Set the content of a field for an existing GraphBLAS object. + +\paragraph{\syntax} + +\begin{verbatim} + GrB_Info GrB_set(GrB_ obj, value, GrB_Field field); + GrB_Info GrB_set(GrB_ obj, void *value, GrB_Field field, size_t voidSize); +\end{verbatim} + +\paragraph{Parameters} + +\begin{itemize}[leftmargin=2.1in] + \item[{\sf obj}] ({\sf IN}) The GraphBLAS object which is having its {\sf field} set. + To indicate the global context, the constant {\sf GrB\_Global} is used. + \item[{\sf value}] ({\sf IN}) A value whose type is dependent on {\sf field}. + {\sf type} may be a {\sf int32\_t}, {\sf GrB\_Scalar}, {\sf char*} or {\sf void*}. + \item[{\sf field}] ({\sf IN}) The field being set. + \item[{\sf voidSize}] ({\sf IN}) The size of the {\sf void*} buffer. Note that a size is not needed for + {\sf char*} because the string is assumed null-terminated. +\end{itemize} + +\paragraph{Return Values} + +\begin{itemize}[leftmargin=2.1in] + \item[{\sf GrB\_SUCCESS}] The method completed successfully. + \item[{\sf GrB\_PANIC}] unknown internal error. + \item[{\sf GrB\_OUT\_OF\_MEMORY}] not enough memory available for operation. + \item[{\sf GrB\_UNINITIALIZED\_OBJECT}] the {\sf GrB\_Scalar} parameter has not been + initialized by a call to the appropriate {\sf new} method. + \item[{\sf GrB\_INVALID\_VALUE}] invalid value set on the field, invalid field, or field is read-only. + \item[{\sf GrB\_ALREADY\_SET}] this field has already been set, and may only be set once. + \end{itemize} + +\paragraph{Description} + +This method sets a field of {\sf obj} or the Global context to a new value. \ No newline at end of file diff --git a/graph-api-c/vector_matrix_methods.tex b/graph-api-c/vector_matrix_methods.tex index 4bf2b1a..f802699 100644 --- a/graph-api-c/vector_matrix_methods.tex +++ b/graph-api-c/vector_matrix_methods.tex @@ -2158,7 +2158,8 @@ \subsubsection{{\sf Matrix\_deserialize}: Deserialize a GraphBLAS matrix.} \begin{itemize}[leftmargin=1.1in] \item[{\sf A}] ({\sf INOUT}) On a successful return, contains a handle to the newly created GraphBLAS matrix. - \item[{\sf d}] ({\sf IN}) the type of the matrix that was serialized in {\sf serialized\_data}. + \item[{\sf d}] ({\sf IN}) the type of the matrix that was serialized in {\sf serialized\_data}. \\ + If {\sf d} is {\sf GrB\_NULL}, the implementation must attempt to deserialize the matrix without a provided type object. \item[{\sf serialized\_data}] ({\sf IN}) a pointer to a serialized GraphBLAS matrix created with {\sf GrB\_Matrix\_serialize}. \item[{\sf serialized\_size}] ({\sf IN}) the size of the buffer pointed to by {\sf serialized\_data} in bytes. \end{itemize} @@ -2182,7 +2183,9 @@ \subsubsection{{\sf Matrix\_deserialize}: Deserialize a GraphBLAS matrix.} \item[{\sf GrB\_NULL\_POINTER}] {\sf serialized\_data} or {\sf A} is {\sf NULL}. - \item[{\sf GrB\_DOMAIN\_MISMATCH}] The type given in {\sf d} does not match the type of the matrix serialized in {\sf serialized\_data}. + \item[{\sf GrB\_DOMAIN\_MISMATCH}] The type given in {\sf d} does not match the type of the matrix serialized + in {\sf serialized\_data}, or {\sf GrB\_NULL} was passed in and the implementation is unable to construct the + matrix without the explicitly provided {\sf GrB\_Type}. \end{itemize} \paragraph{Description} @@ -2191,7 +2194,7 @@ \subsubsection{{\sf Matrix\_deserialize}: Deserialize a GraphBLAS matrix.} by {\sf serialized\_data}. The object pointed to by {\sf serialized\_data} must have been created using the method {\sf GrB\_Matrix\_serialize}. The domain of the matrix is given as an input in {\sf d}, which must match the domain of the -matrix serialized in {\sf serialized\_data}. Note that for user-defined types, +matrix serialized in {\sf serialized\_data} or be {\sf GrB\_NULL}. Note that for user-defined types, only the size of the type will be checked. Since the format of a serialized matrix is implementation-defined, it is not