Merge pull request #173 from DrTimothyAldenDavis/dev2

Adding NOPENMP option

CHOLMOD/CMakeLists.txt

@@ -68,7 +68,15 @@ endif ( )
 #-------------------------------------------------------------------------------
 
 enable_language ( C Fortran )
-find_package ( OpenMP )
+
+option ( NOPENMP "ON: do not use OpenMP.  OFF (default): use OpenMP" off )
+if ( NOPENMP )
+    # OpenMP has been disabled
+    set ( OPENMP_FOUND false )
+else ( )
+    find_package ( OpenMP )
+endif ( )
+
 find_package ( SuiteSparse_config 6.0.0 REQUIRED )
 find_package ( COLAMD 3.0.0 REQUIRED )
 find_package ( AMD 3.0.0 REQUIRED )

ChangeLog

@@ -16,7 +16,7 @@ Nov 12, 2022: SuiteSparse 6.0.0
         name space.  No longer an independent library.
     * SPDX License Identifier: added to each file. No change in license.
     * BLAS/LAPACK interface: now supports any Fortran BLAS/LAPACK, with
-        either 32-bit (default) or 64-bit integers.
+        either 32-bit (default) or 64-bit integers, via FindBLAS.cmake.
     * SPEX: replaces SLIP_LU
 
 Aug 25, 2022, SuiteSparse 5.13.0

GraphBLAS/CMakeLists.txt

@@ -73,7 +73,13 @@ endif ( )
 # find OpenMP, CUDA, RMM, and cpu_features
 #-------------------------------------------------------------------------------
 
-find_package ( OpenMP )
+option ( NOPENMP "ON: do not use OpenMP.  OFF (default): use OpenMP" off )
+if ( NOPENMP )
+    # OpenMP has been disabled
+    set ( OPENMP_FOUND false )
+else ( )
+    find_package ( OpenMP )
+endif ( )
 
 if ( SUITESPARSE_CUDA )
     # with CUDA and RMM

GraphBLAS/Config/GraphBLAS.h.in

@@ -4390,6 +4390,7 @@ typedef enum            // for global options or matrix options
     GxB_API_URL = 19,               // URL for the API (char *)
     GxB_COMPILER_VERSION = 23,      // compiler version (3 int's)
     GxB_COMPILER_NAME = 24,         // compiler name (char *)
+    GxB_LIBRARY_OPENMP = 25,        // library compiled with OpenMP
 
     //------------------------------------------------------------
     // for GxB_Global_Option_get/set only:

GraphBLAS/Doc/ChangeLog

@@ -2,6 +2,7 @@ Version 7.3.2, Nov 12, 2022
 
     * cmake_modules: minor revision to build system, to sync 
         with SuiteSparse v6.0.0
+    * Added option -DNOPENMP=1 to disable OpenMP parallelism
 
 Version 7.3.1, Oct 21, 2022
 

GraphBLAS/Doc/GraphBLAS_UserGuide.tex

@@ -3717,8 +3717,9 @@ \subsubsection{{\sf GrB\_Scalar\_wait:} wait for a scalar}
 all pending computations are finished, and different user threads may
 simultaneously call GraphBLAS operations that use the scalar \verb's' as an
 input parameter.
+See Section~\ref{omp_parallelism}
+if GraphBLAS is compiled without OpenMP.
 
-\newpage
 %-------------------------------------------------------------------------------
 \subsubsection{{\sf GrB\_Scalar\_dup:} copy a scalar}
 %-------------------------------------------------------------------------------
@@ -4030,6 +4031,8 @@ \subsubsection{{\sf GrB\_Vector\_wait:} wait for a vector}
 all pending computations are finished, and different user threads may
 simultaneously call GraphBLAS operations that use the vector \verb'w' as an
 input parameter.
+See Section~\ref{omp_parallelism}
+if GraphBLAS is compiled without OpenMP.
 
 \newpage
 %-------------------------------------------------------------------------------
@@ -4623,8 +4626,11 @@ \subsubsection{{\sf GrB\_Matrix\_wait:} wait for a matrix}
 all pending computations are finished, and different user threads may
 simultaneously call GraphBLAS operations that use the matrix \verb'C' as an
 input parameter.
+See Section~\ref{omp_parallelism}
+if GraphBLAS is compiled without OpenMP.
 
 %-------------------------------------------------------------------------------
+\newpage
 \subsubsection{{\sf GrB\_Matrix\_dup:}          copy a matrix}
 %-------------------------------------------------------------------------------
 \label{matrix_dup}
@@ -4663,7 +4669,6 @@ \subsubsection{{\sf GrB\_Matrix\_dup:}          copy a matrix}
 same set of values, but they do not depend on each other.  Modifying one has
 no effect on the other.
 
-\newpage
 %-------------------------------------------------------------------------------
 \subsubsection{{\sf GrB\_Matrix\_clear:}        clear a matrix of all entries}
 %-------------------------------------------------------------------------------
@@ -4685,7 +4690,7 @@ \subsubsection{{\sf GrB\_Matrix\_clear:}        clear a matrix of all entries}
 with \verb'A (:,:) = 0' in MATLAB.  The type and dimensions of \verb'A' do not
 change.  Any pending updates to the matrix are discarded.
 
-% \newpage
+\newpage
 %-------------------------------------------------------------------------------
 \subsubsection{{\sf GrB\_Matrix\_nrows:}        return the number of rows of a matrix}
 %-------------------------------------------------------------------------------
@@ -4869,7 +4874,7 @@ \subsubsection{{\sf GrB\_Matrix\_build:} build a matrix from a set of tuples}
 for assembling duplicates (summation), and it can only build double, double
 complex, and logical sparse matrices.
 
-\newpage
+% \newpage
 %-------------------------------------------------------------------------------
 \subsubsection{{\sf GxB\_Matrix\_build\_Scalar:} build a matrix from a set of tuples}
 %-------------------------------------------------------------------------------
@@ -4898,6 +4903,7 @@ \subsubsection{{\sf GxB\_Matrix\_build\_Scalar:} build a matrix from a set of tu
 entries in the sparsity pattern of \verb'C' are identical, and equal to the
 input scalar value.
 
+\newpage
 %-------------------------------------------------------------------------------
 \subsubsection{{\sf GrB\_Matrix\_setElement:}   add an entry to a matrix}
 %-------------------------------------------------------------------------------
@@ -8433,6 +8439,7 @@ \section{SuiteSparse:GraphBLAS Options} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \verb'GxB_LIBRARY_LICENSE'      & \verb'char *' & license \\
 \verb'GxB_LIBRARY_COMPILE_DATE' & \verb'char *' & date of compilation \\
 \verb'GxB_LIBRARY_COMPILE_TIME' & \verb'char *' & time of compilation \\
+\verb'GxB_LIBRARY_OPENMP'       & \verb'bool'   & true if compiled with OpenMP\\
 \verb'GxB_LIBRARY_URL'          & \verb'char *' & url of library \\
 \verb'GxB_API_VERSION'          & \verb'int [3]' & C API version \\
 \verb'GxB_API_DATE'             & \verb'char *' & C API date \\
@@ -8571,6 +8578,23 @@ \subsection{OpenMP parallelism}
 set, or set to \verb'GxB_DEFAULT', then any operation that uses this descriptor
 will use 4 threads.
 
+GraphBLAS may be compiled without OpenMP, by setting \verb'-DNOPENMP=1'.
+The library will be thread-safe, with one exception.  \verb'GrB_wait' is
+intended to provide thread-safety by flushing the cache of one user thread
+so the object can be safely read by another thread.  This is accomplished
+with \verb'pragma omp flush', but if OpenMP is not available, this does
+nothing.  If OpenMP is not available or \verb'-DNOPEMP=1' is used, then
+user applications need to ensure their own thread safety when one user thread
+computes a result that is then read by another thread.
+
+You can query GraphBLAS at run time to ask if it was compiled with OpenMP:
+
+\begin{verbatim}
+    bool have_openmp ;
+    GxB_get (GxB_LIBRARY_OPENMP, &have_openmp) ;
+    if (!have_openmp) printf ("GraphBLAS not compiled with OpenMP\n") :
+\end{verbatim}
+
 %-------------------------------------------------------------------------------
 \subsection{Storing a matrix by row or by column}
 %-------------------------------------------------------------------------------
@@ -8816,6 +8840,7 @@ \subsection{Parameter types}
     GxB_LIBRARY_LICENSE = 13,       // license of the library (char *)
     GxB_LIBRARY_COMPILE_DATE = 14,  // date library was compiled (char *)
     GxB_LIBRARY_COMPILE_TIME = 15,  // time library was compiled (char *)
+    GxB_LIBRARY_OPENMP = 25,        // library compiled with OpenMP
     GxB_API_VERSION = 16,           // API version (3 int's)
     GxB_API_DATE = 17,              // date of the API (char *)
     GxB_API_ABOUT = 18,             // about the API (char *)
@@ -9166,6 +9191,7 @@ \subsection{{\sf GxB\_Global\_Option\_get:} retrieve a global option}
         \verb'GxB_LIBRARY_LICENSE'      & license for the library \\
         \verb'GxB_LIBRARY_COMPILE_DATE' & date of compilation \\
         \verb'GxB_LIBRARY_COMPILE_TIME' & time of compilation \\
+        \verb'GxB_LIBRARY_OPENMP'       & library compiled with OpenMP\\
         \verb'GxB_LIBRARY_URL'          & URL of the library \\
         \hline
         \verb'GxB_API_VERSION'  & GraphBLAS C API Specification Version \\
@@ -9363,6 +9389,7 @@ \subsection{Summary of usage of {\sf GxB\_set} and {\sf GxB\_get}}
     GxB_get (GxB_LIBRARY_LICENSE,      char **) ;
     GxB_get (GxB_LIBRARY_COMPILE_DATE, char **) ;
     GxB_get (GxB_LIBRARY_COMPILE_TIME, char **) ;
+    GxB_get (GxB_LIBRARY_OPENMP,       bool *) ;
     GxB_get (GxB_LIBRARY_URL,          char **) ;
     GxB_get (GxB_API_VERSION,          int *) ;
     GxB_get (GxB_API_DATE,             char **) ;
@@ -14791,7 +14818,10 @@ \subsection{User applications using OpenMP or other threading models}
 
 GraphBLAS can also be combined with user applications that rely on MPI, the
 Intel TBB threading library, POSIX pthreads, Microsoft Windows threads, or any
-other threading library.  In all cases, GraphBLAS will be thread safe.
+other threading library.  If GraphBLAS itself is compiled with OpenMP,
+it will be thread safe when combined with other libraries.
+See Section~\ref{omp_parallelism} for thread-safety issues that can occur
+if GraphBLAS is compiled without OpenMP.
 
 \newpage
 %-------------------------------------------------------------------------------
@@ -15460,6 +15490,7 @@ \section{Release Notes}
     \begin{packed_itemize}
     \item \verb'cmake_modules': minor revision to build system, to sync 
         with SuiteSparse v6.0.0
+    \item Added option \verb'-DNOPENMP=1' to disable OpenMP parallelism.
     \end{packed_itemize}
 
 \item Version 7.3.1 (Oct 21, 2022)

GraphBLAS/GraphBLAS/@GrB/private/mexfunctions/gbver.c

@@ -51,10 +51,13 @@ void mexFunction
                 version [0], version [1], version [2], date) ;
         char *compiler ;
         int cver [3] ;
+        bool have_openmp ;
         OK (GxB_get (GxB_COMPILER_NAME, &compiler)) ;
         OK (GxB_get (GxB_COMPILER_VERSION, cver)) ;
-        printf ("GraphBLAS compiled with %s (v%d.%d.%d)\n\n", compiler,
-            cver [0], cver [1], cver [2]) ;
+        OK (GxB_get (GxB_LIBRARY_OPENMP, &have_openmp)) ;
+        printf ("GraphBLAS compiled with %s (v%d.%d.%d), %s OpenMP\n", compiler,
+            cver [0], cver [1], cver [2],
+            have_openmp ? "with" : "without") ;
         printf ("@GrB License: Apache-2.0\n\n") ;
         OK (GxB_Global_Option_get (GxB_API_ABOUT, &spec)) ;
         printf ("Spec:\n%s\n", spec) ;

GraphBLAS/GraphBLAS/CMakeLists.txt

@@ -67,7 +67,13 @@ endif ( )
 # find OpenMP and cpu_features
 #-------------------------------------------------------------------------------
 
-find_package ( OpenMP )
+option ( NOPENMP "ON: do not use OpenMP.  OFF (default): use OpenMP" off )
+if ( NOPENMP )
+    # OpenMP has been disabled
+    set ( OPENMP_FOUND false )
+else ( )
+    find_package ( OpenMP )
+endif ( )
 
 if ( NOT GBNCPUFEAT )
     # default: enable Google's cpu_features package

GraphBLAS/Include/GraphBLAS.h

@@ -4390,6 +4390,7 @@ typedef enum            // for global options or matrix options
     GxB_API_URL = 19,               // URL for the API (char *)
     GxB_COMPILER_VERSION = 23,      // compiler version (3 int's)
     GxB_COMPILER_NAME = 24,         // compiler name (char *)
+    GxB_LIBRARY_OPENMP = 25,        // library compiled with OpenMP
 
     //------------------------------------------------------------
     // for GxB_Global_Option_get/set only:

GraphBLAS/Source/GxB_Global_Option_get.c

@@ -219,6 +219,21 @@ GrB_Info GxB_Global_Option_get      // gets the current global option
             }
             break ;
 
+        case GxB_LIBRARY_OPENMP : 
+
+            {
+                va_start (ap, field) ;
+                bool *have_openmp = va_arg (ap, bool *) ;
+                va_end (ap) ;
+                GB_RETURN_IF_NULL (have_openmp) ;
+                #ifdef _OPENMP
+                (*have_openmp) = true ;
+                #else
+                (*have_openmp) = false ;
+                #endif
+            }
+            break ;
+
         case GxB_LIBRARY_URL : 
 
             {