Merge pull request #202 from DrTimothyAldenDavis/v742

GraphBLAS v7.4.2.beta2: NTHREADS and CHUNK in descriptor is deprecated

Author: DrTimothyAldenDavis

Config/GraphBLAS.h.in

@@ -425,16 +425,6 @@ GrB_Info GrB_getVersion         // runtime access to C API version number
 //
 // GrB_INP1: the same as GrB_INP0 but for the second input
 //
-// GxB_NTHREADS: the maximum number of threads to use in the current method.
-//      If <= GxB_DEFAULT (which is zero), then the number of threads is
-//      determined automatically.  This is the default value.
-//
-// GxB_CHUNK: an integer parameter that determines the number of threads to use
-//      for a small problem.  If w is the work to be performed, and chunk is
-//      the value of this parameter, then the # of threads is limited to floor
-//      (w/chunk).  The default chunk is currently 64K, but this may change in
-//      the future.  If chunk is set to <= GxB_DEFAULT (that is, zero), the
-//      default is used.
 //
 // GxB_AxB_METHOD: this is a hint to SuiteSparse:GraphBLAS on which algorithm
 //      it should use to compute C=A*B, in GrB_mxm, GrB_mxv, and GrB_vxm.
@@ -499,12 +489,9 @@ typedef enum
     GrB_INP0 = 2,   // descriptor for the first input of a method
     GrB_INP1 = 3,   // descriptor for the second input of a method
 
-    GxB_DESCRIPTOR_NTHREADS = GxB_NTHREADS,     // max number of threads to use.
-                    // If <= GxB_DEFAULT, then GraphBLAS selects the number
-                    // of threads automatically.
-
-    GxB_DESCRIPTOR_CHUNK = GxB_CHUNK,   // chunk size for small problems.
-                    // If <= GxB_DEFAULT, then the default is used.
+    // setting NTHREADS and CHUNK in the descriptor is deprecated
+    GxB_DESCRIPTOR_NTHREADS = GxB_NTHREADS,     // DEPRECATED
+    GxB_DESCRIPTOR_CHUNK = GxB_CHUNK,           // DEPRECATED
 
     // GPU control (DRAFT: in progress, do not use)
     GxB_DESCRIPTOR_GPU_CONTROL = GxB_GPU_CONTROL,
@@ -4089,7 +4076,7 @@ GrB_Info GxB_Matrix_diag    // construct a diagonal matrix from a vector
     GrB_Matrix C,                   // output matrix
     const GrB_Vector v,             // input vector
     int64_t k,
-    const GrB_Descriptor desc       // to specify # of threads
+    const GrB_Descriptor desc
 ) ;
 
 // GxB_Vector_diag extracts a vector v from an input matrix A, which may be
@@ -4481,8 +4468,7 @@ GrB_Info GxB_Global_Option_get_FUNCTION // gets the current global option
 
 // GxB_set and GxB_get are generic methods that and set or query the options in
 // a GrB_Matrix, a GrB_Descriptor, or in the global options.  They can be used
-// with the following syntax.  Note that GxB_NTHREADS can be used for both the
-// global nthreads_max, and for the # of threads in the descriptor.
+// with the following syntax.
 
 // To set/get the global options:
 //
@@ -4586,12 +4572,6 @@ GrB_Info GxB_Global_Option_get_FUNCTION // gets the current global option
 //      GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_DOT) ;
 //      GxB_get (GrB_Descriptor d, GrB_AxB_METHOD, GrB_Desc_Value *v) ;
 //
-//      GxB_set (GrB_Descriptor d, GxB_NTHREADS, nthreads) ;
-//      GxB_get (GrB_Descriptor d, GxB_NTHREADS, int *nthreads) ;
-//
-//      GxB_set (GrB_Descriptor d, GxB_CHUNK, double chunk) ;
-//      GxB_get (GrB_Descriptor d, GxB_CHUNK, double *chunk) ;
-//
 //      GxB_set (GrB_Descriptor d, GxB_SORT, int sort) ;
 //      GxB_get (GrB_Descriptor d, GxB_SORT, int *sort) ;
 //
@@ -10964,7 +10944,6 @@ GrB_Info GxB_Matrix_serialize       // serialize a GrB_Matrix to a blob
     // input:
     GrB_Matrix A,                   // matrix to serialize
     const GrB_Descriptor desc       // descriptor to select compression method
-                                    // and to control # of threads used
 ) ;
 
 GrB_Info GrB_Matrix_serialize       // serialize a GrB_Matrix to a blob
@@ -10986,7 +10965,6 @@ GrB_Info GxB_Vector_serialize       // serialize a GrB_Vector to a blob
     // input:
     GrB_Vector u,                   // vector to serialize
     const GrB_Descriptor desc       // descriptor to select compression method
-                                    // and to control # of threads used
 ) ;
 
 GrB_Info GrB_Matrix_serializeSize   // estimate the size of a blob
@@ -10999,8 +10977,7 @@ GrB_Info GrB_Matrix_serializeSize   // estimate the size of a blob
 ) ;
 
 // The GrB* and GxB* deserialize methods are nearly identical.  The GxB*
-// deserialize methods simply add the descriptor, which allows for optional
-// control of the # of threads used to deserialize the blob.
+// deserialize methods simply add the descriptor.
 
 GrB_Info GxB_Matrix_deserialize     // deserialize blob into a GrB_Matrix
 (
@@ -11013,7 +10990,7 @@ GrB_Info GxB_Matrix_deserialize     // deserialize blob into a GrB_Matrix
                         // type of C.
     const void *blob,       // the blob
     GrB_Index blob_size,    // size of the blob
-    const GrB_Descriptor desc       // to control # of threads used
+    const GrB_Descriptor desc
 ) ;
 
 GrB_Info GrB_Matrix_deserialize     // deserialize blob into a GrB_Matrix
@@ -11040,7 +11017,7 @@ GrB_Info GxB_Vector_deserialize     // deserialize blob into a GrB_Vector
                         // type of w.
     const void *blob,       // the blob
     GrB_Index blob_size,    // size of the blob
-    const GrB_Descriptor desc       // to control # of threads used
+    const GrB_Descriptor desc
 ) ;
 
 // GxB_deserialize_type_name extracts the type_name of the GrB_Type of the
@@ -11131,7 +11108,7 @@ GrB_Info GxB_Matrix_reshape     // reshape a GrB_Matrix in place
     bool by_col,                // true if reshape by column, false if by row
     GrB_Index nrows_new,        // new number of rows of C
     GrB_Index ncols_new,        // new number of columns of C
-    const GrB_Descriptor desc   // to control # of threads used
+    const GrB_Descriptor desc
 ) ;
 
 // GxB_Matrix_reshapeDup reshapes a matrix into another matrix.
@@ -11151,7 +11128,7 @@ GrB_Info GxB_Matrix_reshapeDup // reshape a GrB_Matrix into another GrB_Matrix
     bool by_col,                // true if reshape by column, false if by row
     GrB_Index nrows_new,        // number of rows of C
     GrB_Index ncols_new,        // number of columns of C
-    const GrB_Descriptor desc   // to control # of threads used
+    const GrB_Descriptor desc
 ) ;
 
 //==============================================================================

Doc/ChangeLog

@@ -1,6 +1,10 @@
 Version 7.4.2, Jan 17, 2023
 
     * minor change to build system: for SuiteSparse v7.0.0
+    * deprecation notice:  in GraphBLAS v8.0.0, the ability to set the
+        # of threads, and chunk size, in the descriptor will be removed.
+        It still appears in v7.x, but will be replaced by a Context object
+        in v8.0.0.
 
 Version 7.4.1, Jan 9, 2023
 

Doc/GraphBLAS_UserGuide.pdf

@@ -5163,7 +5163,7 @@ \subsubsection{{\sf GxB\_Matrix\_reshape:} reshape a matrix}
     bool by_col,                // true if reshape by column, false if by row
     GrB_Index nrows_new,        // new number of rows of C
     GrB_Index ncols_new,        // new number of columns of C
-    const GrB_Descriptor desc   // to control # of threads used
+    const GrB_Descriptor desc
 ) ;
 \end{verbatim} } \end{mdframed}
 
@@ -5217,7 +5217,7 @@ \subsubsection{{\sf GxB\_Matrix\_reshapeDup:} reshape a matrix}
     bool by_col,                // true if reshape by column, false if by row
     GrB_Index nrows_new,        // number of rows of C
     GrB_Index ncols_new,        // number of columns of C
-    const GrB_Descriptor desc   // to control # of threads used
+    const GrB_Descriptor desc
 ) ;
 \end{verbatim} } \end{mdframed}
 
@@ -5601,7 +5601,6 @@ \subsubsection{{\sf GxB\_Vector\_serialize:}      serialize a vector}
     // input:
     GrB_Vector u,                   // vector to serialize
     const GrB_Descriptor desc       // descriptor to select compression method
-                                    // and to control # of threads used
 ) ;
 \end{verbatim}
 } \end{mdframed}
@@ -5656,7 +5655,7 @@ \subsubsection{{\sf GxB\_Vector\_deserialize:}    deserialize a vector}
     GrB_Type type,      // type of the vector w.  See GxB_Matrix_deserialize.
     const void *blob,       // the blob
     GrB_Index blob_size,    // size of the blob
-    const GrB_Descriptor desc       // to control # of threads used
+    const GrB_Descriptor desc
 ) ;
 \end{verbatim}
 } \end{mdframed}
@@ -5748,7 +5747,6 @@ \subsubsection{{\sf GxB\_Matrix\_serialize:}      serialize a matrix}
     // input:
     GrB_Matrix A,                   // matrix to serialize
     const GrB_Descriptor desc       // descriptor to select compression method
-                                    // and to control # of threads used
 ) ;
 \end{verbatim}
 } \end{mdframed}
@@ -5817,7 +5815,7 @@ \subsubsection{{\sf GxB\_Matrix\_deserialize:}    deserialize a matrix}
                         // type of C.
     const void *blob,       // the blob
     GrB_Index blob_size,    // size of the blob
-    const GrB_Descriptor desc       // to control # of threads used
+    const GrB_Descriptor desc
 ) ;
 \end{verbatim}
 } \end{mdframed}
@@ -7598,16 +7596,14 @@ \subsection{GraphBLAS descriptors: {\sf GrB\_Descriptor}} %=====================
 \begin{mdframed}[userdefinedwidth=6in]
 {\footnotesize
 \begin{verbatim}
-#define GxB_NTHREADS 5  // for both GrB_Desc_field and GxB_Option_field
+#define GxB_NTHREADS 5  // for GxB_Option_field
 #define GxB_CHUNK 7
 typedef enum
 {
     GrB_OUTP = 0,   // descriptor for output of a method
     GrB_MASK = 1,   // descriptor for the mask input of a method
     GrB_INP0 = 2,   // descriptor for the first input of a method
     GrB_INP1 = 3,   // descriptor for the second input of a method
-    GxB_DESCRIPTOR_NTHREADS = GxB_NTHREADS,   // number of threads to use
-    GxB_DESCRIPTOR_CHUNK = GxB_CHUNK,   // chunk size for small problems
     GxB_AxB_METHOD = 1000, // descriptor for selecting C=A*B algorithm
     GxB_SORT = 35   // control sort in GrB_mxm
     GxB_COMPRESSION = 36,   // select compression for serialize
@@ -7775,17 +7771,12 @@ \subsection{GraphBLAS descriptors: {\sf GrB\_Descriptor}} %=====================
 
     \end{itemize}
 
-\item \verb'GxB_NTHREADS' controls how many threads a method uses.
-    By default (if set to zero, or \verb'GxB_DEFAULT'), all available threads
-    are used.  The maximum available threads is controlled by the global
-    setting, which is \verb'omp_get_max_threads ( )' by default.  If set to
-    some positive integer \verb'nthreads' less than this maximum, at most
-    \verb'nthreads' threads will be used.  See Section~\ref{omp_parallelism}
-    for details.
+\item \verb'GxB_NTHREADS' controls how many threads a method uses, via
+    the descriptor, but is deprecated.
+    It will be removed from the descriptor entirely in v8.0.0.
 
-\item \verb'GxB_CHUNK' is a \verb'double' value that controls how many threads
-    a method uses for small problems.  See Section~\ref{omp_parallelism} for
-    details.
+\item \verb'GxB_CHUNK' is deprecated as used in the descriptor.
+    It will be removed from the descriptor entirely in v8.0.0.
 
 \item \verb'GxB_SORT' provides a hint to \verb'GrB_mxm', \verb'GrB_mxv',
     \verb'GrB_vxm', and \verb'GrB_reduce' (to vector).  These methods can leave
@@ -7894,7 +7885,7 @@ \subsubsection{{\sf GrB\_Descriptor\_set:}  set a parameter in a descriptor}
 \verb'GrB_Descriptor_set' sets a descriptor field (\verb'GrB_OUTP',
 \verb'GrB_MASK', \verb'GrB_INP0', \verb'GrB_INP1', or \verb'GxB_AxB_METHOD') to
 a particular value.  Use \verb'GxB_Dec_set' to set the value of
-\verb'GxB_NTHREADS', \verb'GxB_CHUNK', and \verb'GxB_SORT'.
+\verb'GxB_SORT'.
 If an error occurs, \verb'GrB_error(&err,desc)' returns details about the error.
 
 \vspace{0.2in}
@@ -8046,16 +8037,6 @@ \subsubsection{{\sf GrB\_DESC\_*:}  built-in descriptors}
 Attempts to modify them result in an error (\verb'GrB_INVALID_VALUE'); attempts
 to free them are silently ignored. 
 
-% \verb'GrB_NULL' is the default descriptor, with all settings at their defaults:
-% \verb'OUTP': do not replace the output,
-% \verb'MASK': mask is valued and not complemented,
-% \verb'INP0': first input not transposed, and
-% \verb'INP1': second input not transposed.
-% For these pre-defined descriptors, the
-% \verb'GxB_NTHREADS',
-% \verb'GxB_CHUNK', and
-% \verb'GxB_SORT' settings are at their default values.
-
 \vspace{0.2in}
 \noindent
 {\footnotesize
@@ -8394,10 +8375,6 @@ \section{SuiteSparse:GraphBLAS Options} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \verb'GrB_MASK'     & \verb'GrB_Desc_Value' & mask option \\
 \verb'GrB_INP0'     & \verb'GrB_Desc_Value' & transpose input 0 \\
 \verb'GrB_INP1'     & \verb'GrB_Desc_Value' & transpose input 1 \\
-\verb'GxB_DESCRIPTOR_NTHREADS'  & \verb'int' & number of threads to use \\
-\verb'GxB_NTHREADS'             & \verb'int' & number of threads to use \\
-\verb'GxB_DESCRIPTOR_CHUNK'     & \verb'double' & chunk size \\
-\verb'GxB_CHUNK'                & \verb'double' & chunk size \\
 \verb'GxB_AxB_METHOD'           & \verb'int' & method for matrix multiply \\
 \verb'GxB_SORT'                 & \verb'int' & lazy vs aggressive sort \\
 \verb'GxB_COMPRESSION'          & \verb'int' & compression for serialization \\
@@ -8495,10 +8472,6 @@ \section{SuiteSparse:GraphBLAS Options} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \verb'GrB_MASK'     & \verb'GrB_Desc_Value' & mask option \\
 \verb'GrB_INP0'     & \verb'GrB_Desc_Value' & transpose input 0 \\
 \verb'GrB_INP1'     & \verb'GrB_Desc_Value' & transpose input 1 \\
-\verb'GxB_DESCRIPTOR_NTHREADS'  & \verb'int' & number of threads to use \\
-\verb'GxB_NTHREADS'             & \verb'int' & number of threads to use \\
-\verb'GxB_DESCRIPTOR_CHUNK'     & \verb'double' & chunk size \\
-\verb'GxB_CHUNK'                & \verb'double' & chunk size \\
 \verb'GxB_AxB_METHOD'           & \verb'int' & method for matrix multiply \\
 \verb'GxB_SORT'                 & \verb'int' & lazy vs aggressive sort \\
 \verb'GxB_COMPRESSION'          & \verb'int' & compression for serialization \\
@@ -8544,19 +8517,9 @@ \subsection{OpenMP parallelism}
     GxB_set (GxB_NTHREADS, nthreads_max) ;
     GxB_set (GxB_CHUNK, (double) 20000) ; \end{verbatim} }
 
-\item Per operation:  Most GraphBLAS operations take a \verb'GrB_Descriptor'
-input, and this can be modified to set the number of threads and chunk
-size for the operation that uses this descriptor.  Note that \verb'chunk'
-is a \verb'double'.
-
-    {\footnotesize
-    \begin{verbatim}
-    GrB_Descriptor desc ;
-    GrB_Descriptor_new (&desc)
-    int nthreads_max = 40 ;
-    GxB_set (desc, GxB_NTHREADS, nthreads_max) ;
-    double chunk = 20000 ;
-    GxB_set (desc, GxB_CHUNK, chunk) ; \end{verbatim} }
+\item Per operation:   Setting the number of threads and the chunk 
+size in the descriptor is deprecated.
+It will be removed entirely in v8.0.0 from the descriptor.
 
 \end{itemize}
 
@@ -8568,15 +8531,9 @@ \subsection{OpenMP parallelism}
 The default for \verb'nthreads_max' is the return value from
 \verb'omp_get_max_threads', and the default chunk size is currently 65,536.
 
-If a descriptor value for either parameter is left at its default, or set to
-\verb'GxB_DEFAULT', then the global setting is used.  This global setting may
-have been modified from its default, and this modified value will be used.
-
 For example, suppose \verb'omp_get_max_threads' reports 8 threads.  If \newline
 \verb'GxB_set (GxB_NTHREADS, 4)' is used, then the global setting is four
-threads, not eight.  If a descriptor is used but its \verb'GxB_NTHREADS' is not
-set, or set to \verb'GxB_DEFAULT', then any operation that uses this descriptor
-will use 4 threads.
+threads, not eight.
 
 GraphBLAS may be compiled without OpenMP, by setting \verb'-DNOPENMP=1'.
 The library will be thread-safe, with one exception.  \verb'GrB_wait' is
@@ -9145,8 +9102,8 @@ \subsection{{\sf GxB\_Desc\_set:} set a {\sf GrB\_Descriptor} value}
 
 This usage is similar to \verb'GrB_Descriptor_set', just with a name that is
 consistent with the other usages of this generic function.  Unlike
-\verb'GrB_Descriptor_set', the \verb'field' may also be \verb'GxB_NTHREADS',
-\verb'GxB_CHUNK', \verb'GxB_SORT', \verb'GxB_COMPRESSION', or
+\verb'GrB_Descriptor_set', the \verb'field' may also be
+\verb'GxB_SORT', \verb'GxB_COMPRESSION', or
 \verb'GxB_IMPORT'.  Refer to Sections~\ref{descriptor_set}~and~\ref{desc_set}
 for details.  If an error occurs, \verb'GrB_error(&err,desc)' returns details
 about the error.
@@ -9333,8 +9290,6 @@ \subsection{{\sf GxB\_Desc\_get:} retrieve a {\sf GrB\_Descriptor} value}
 This usage is the same as \verb'GxB_Desc_get'.  The \verb'field' parameter can
 be \verb'GrB_OUTP', \verb'GrB_MASK', \verb'GrB_INP0', \verb'GrB_INP1',
 \verb'GxB_AxB_METHOD',
-\verb'GxB_NTHREADS',
-\verb'GxB_CHUNK',
 \verb'GxB_SORT',
 \verb'GxB_COMPRESSION', or
 \verb'GxB_IMPORT'.
@@ -9458,10 +9413,6 @@ \subsection{Summary of usage of {\sf GxB\_set} and {\sf GxB\_get}}
     GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_SAXPY) ;
     GxB_set (GrB_Descriptor d, GxB_AxB_METHOD, GxB_AxB_DOT) ;
     GxB_get (GrB_Descriptor d, GrB_AxB_METHOD, GrB_Desc_Value *v) ;
-    GxB_set (GrB_Descriptor d, GxB_NTHREADS, int nthreads) ;
-    GxB_get (GrB_Descriptor d, GxB_NTHREADS, int *nthreads) ;
-    GxB_set (GrB_Descriptor d, GxB_CHUNK, double chunk) ;
-    GxB_get (GrB_Descriptor d, GxB_CHUNK, double *chunk) ;
     GxB_set (GrB_Descriptor d, GxB_SORT, sort) ;
     GxB_get (GrB_Descriptor d, GxB_SORT, int *sort) ;
     GxB_set (GrB_Descriptor d, GxB_COMPRESSION, GxB_FAST_IMPORT) ;
@@ -15542,6 +15493,10 @@ \section{Release Notes}
 
     \begin{itemize}
     \item minor change to build system: for SuiteSparse v7.0.0.
+    \item deprecation notice:  in GraphBLAS v8.0.0, the ability to set the
+        number of threads, and chunk size, in the descriptor will be removed.
+        It still appears in v7.x, but will be replaced by a Context object
+        in v8.0.0.
     \end{itemize}
 
 \item Version 7.4.1 (Dec 29, 2022)