Implemented support for fat multithreading. (#665)

Details:
- Allow the user to configure BLIS in such a way that multiple threading
  implementations get compiled into the library, with one of those
  implementations chosen at runtime. For now, there are only three
  implementations available: OpenMP, pthreads, and single. (Here,
  'single' merely refers to single-threaded mode.) The configure script
  now allows the user to give the -t option with a comma-separated list
  of values, such as '-t openmp,pthreads'. The first value in the list
  will always be the default at library initialization time, and
  'single' is always silently appended to the end of the list. The user
  can specify which implementation should execute in one of three ways:
  by setting the BLIS_THREAD_IMPL environment variable prior to launch;
  by calling the bli_thread_set_thread_impl() global runtime API; or by
  encoding their choice into a rntm_t that is passed into one of the
  expert interfaces. Any of these three choices overrides the
  initialization-time default (i.e., the first value listed to the -t
  configure option). Requesting an implementation that was not compiled
  into the library will result in an error message followed by
  bli_abort().
- Relocated the 'auto' logic for the -t option from the top-level
  Makefile to the configure script. (Currently, this logic is pretty
  dumb, choosing 'openmp' for gcc and icc, and 'pthreads' for clang.)
- Defined a new 'timpl_t' enum in bli_type_defs.h, with three valid
  values: BLIS_SINGLE, BLIS_OPENMP, BLIS_POSIX.
- Reorganized the thrcomm_t struct into a single defintion with two
  preprocessor blocks, one each for additional fields needed by OpenMP
  and pthreads.
- Added timpl_t argument to bli_thrcomm_bcast(), bli_thrcomm_barrier(),
  bli_thrcomm_init(), and bli_thrcomm_cleanup(), which these functions
  need since they are now wrappers that choose the implementation-
  specific function corresponding to the currently enabled threading
  implementation.
- Added rntm_t* to bli_thread_broadcast(), bli_thread_barrier() so that
  those functions can pass the timpl_t value into bli_thrcomm_bcast()
  and bli_thrcomm_barrier(), respectively.
- Defined bli_env_get_str() in bli_env.c to allow the querying of
  BLIS_THREAD_IMPL (which, unlike BLIS_NUM_THREADS and friends, is
  expected to be a string).
- Defined bli_thread_get_thread_impl(), bli_thread_set_thread_impl() to
  get and set the current threading implementation at runtime.
- Defined bli_rntm_thread_impl() and bli_rntm_set_thread_impl() to query
  and set the threading implementation within a rntm_t. Also choose
  BLIS_SINGLE as the default value when initializing rntm_t structs.
- Added bli_info_get_*() functions to query whether OpenMP or pthreads
  would be chosen as the default at init-time. Note that this only
  tests whether OpenMP or pthreads is the first implementation in the
  list passed to the threading configure option (-t) and is *not* the
  same as querying which implementation is currently selected, since
  that can be influenced by BLIS_THREAD_IMPL and/or
  bli_thread_set_thread_impl().
- Changed l3int_t to l3int_ft.
- Updated docs/Multithreading.md to document the new behavior.
- Updated sandbox/gemmlike and addon/gemmd to work with the new fat
  threading feature. This included a few bugfixes to bring the codes up
  to date, as necessary.
- Comment, whitespace updates.

Author: fgvanzee

Makefile

@@ -1149,24 +1149,24 @@ endif # ifeq ($(IS_WIN),no)
 # --- Query current configuration ---
 
 showconfig: check-env
-	@echo "configuration family:    $(CONFIG_NAME)"
-	@echo "sub-configurations:      $(CONFIG_LIST)"
-	@echo "requisite kernels sets:  $(KERNEL_LIST)"
-	@echo "kernel-to-config map:    $(KCONFIG_MAP)"
+	@echo "configuration family:       $(CONFIG_NAME)"
+	@echo "sub-configurations:         $(CONFIG_LIST)"
+	@echo "requisite kernels sets:     $(KERNEL_LIST)"
+	@echo "kernel-to-config map:       $(KCONFIG_MAP)"
 	@echo "-------------------------"
-	@echo "BLIS version string:     $(VERSION)"
-	@echo ".so major version:       $(SO_MAJOR)"
-	@echo ".so minor.build vers:    $(SO_MINORB)"
-	@echo "install libdir:          $(INSTALL_LIBDIR)"
-	@echo "install includedir:      $(INSTALL_INCDIR)"
-	@echo "install sharedir:        $(INSTALL_SHAREDIR)"
-	@echo "debugging status:        $(DEBUG_TYPE)"
-	@echo "multithreading status:   $(THREADING_MODEL)"
-	@echo "enable BLAS API?         $(MK_ENABLE_BLAS)"
-	@echo "enable CBLAS API?        $(MK_ENABLE_CBLAS)"
-	@echo "build static library?    $(MK_ENABLE_STATIC)"
-	@echo "build shared library?    $(MK_ENABLE_SHARED)"
-	@echo "ARG_MAX hack enabled?    $(ARG_MAX_HACK)"
+	@echo "BLIS version string:        $(VERSION)"
+	@echo ".so major version:          $(SO_MAJOR)"
+	@echo ".so minor.build vers:       $(SO_MINORB)"
+	@echo "install libdir:             $(INSTALL_LIBDIR)"
+	@echo "install includedir:         $(INSTALL_INCDIR)"
+	@echo "install sharedir:           $(INSTALL_SHAREDIR)"
+	@echo "debugging status:           $(DEBUG_TYPE)"
+	@echo "enabled threading model(s): $(THREADING_MODEL)"
+	@echo "enable BLAS API?            $(MK_ENABLE_BLAS)"
+	@echo "enable CBLAS API?           $(MK_ENABLE_CBLAS)"
+	@echo "build static library?       $(MK_ENABLE_STATIC)"
+	@echo "build shared library?       $(MK_ENABLE_SHARED)"
+	@echo "ARG_MAX hack enabled?       $(ARG_MAX_HACK)"
 
 
 # --- Clean rules ---

addon/gemmd/attic/bli_gemm_ex.c

@@ -36,13 +36,13 @@
 
 void bli_gemm_ex
      (
-       obj_t*  alpha,
-       obj_t*  a,
-       obj_t*  b,
-       obj_t*  beta,
-       obj_t*  c,
-       cntx_t* cntx,
-       rntm_t* rntm
+       const obj_t*  alpha,
+       const obj_t*  a,
+       const obj_t*  b,
+       const obj_t*  beta,
+       const obj_t*  c,
+       const cntx_t* cntx,
+             rntm_t* rntm
      )
 {
 	bli_init_once();
@@ -82,7 +82,8 @@ void bli_gemm_ex
 	// Invoke the operation's front end.
 	bli_gemm_front
 	(
-	  alpha, a, b, beta, c, cntx, rntm, NULL
+	  ( obj_t* )alpha, ( obj_t* )a, ( obj_t* )b, ( obj_t* )beta, ( obj_t* )c,
+	  ( cntx_t* )cntx, ( rntm_t* )rntm, NULL
 	);
 }
 

addon/gemmd/bao_gemmd.c

@@ -81,16 +81,28 @@ void bao_gemmd_ex
 	if ( rntm == NULL ) { bli_rntm_init_from_global( &rntm_l ); rntm = &rntm_l; }
 	else                { rntm_l = *rntm;                       rntm = &rntm_l; }
 
+	// Set the .pack_a and .pack_b fields to TRUE. This is only needed because
+	// this addon uses bli_thrinfo_sup_grow(), which calls
+	// bli_thrinfo_sup_create_for_cntl(), which employs an optimization if
+	// both fields are FALSE (as is often the case with sup). However, this
+	// addon implements the "large" code path, and so both A and B must
+	// always be packed. Setting the fields to TRUE will avoid the optimization
+	// while this addon implementation executes (and it also reinforces the
+	// fact that we *are* indeed packing A and B, albeit not in the sup context
+	// originally envisioned for the .pack_a and .pack_b fields).
+	bli_rntm_set_pack_a( TRUE, rntm );
+	bli_rntm_set_pack_b( TRUE, rntm );
+
 	// Obtain a valid (native) context from the gks if necessary.
 	// NOTE: This must be done before calling the _check() function, since
 	// that function assumes the context pointer is valid.
-	if ( cntx == NULL ) cntx = bli_gks_query_cntx();
+	if ( cntx == NULL ) cntx = ( cntx_t* )bli_gks_query_cntx();
 
 	// Check parameters.
 	if ( bli_error_checking_is_enabled() )
 		bao_gemmd_check( alpha, a, d, b, beta, c, cntx );
 
-	// -- bli_gemmd_front() ----------------------------------------------------
+	// -- bao_gemmd_front() ----------------------------------------------------
 
 	obj_t a_local;
 	obj_t b_local;

addon/gemmd/bao_gemmd_bp_var1.c

@@ -458,7 +458,7 @@ void PASTECH2(bao_,ch,varname) \
 			/* This barrier is needed to prevent threads from starting to pack
 			   the next row panel of B before the current row panel is fully
 			   computed upon. */ \
-			bli_thread_barrier( thread_pb ); \
+			bli_thread_barrier( rntm, thread_pb ); \
 		} \
 	} \
 \

addon/gemmd/bao_l3_packm_a.c

@@ -61,7 +61,7 @@ void PASTECH2(bao_,ch,opname) \
 \
 	/* Barrier to make sure all threads are caught up and ready to begin the
 	   packm stage. */ \
-	bli_thread_barrier( thread ); \
+	bli_thread_barrier( rntm, thread ); \
 \
 	/* Compute the size of the memory block eneded. */ \
 	siz_t size_needed = sizeof( ctype ) * m_pack * k_pack; \
@@ -90,7 +90,7 @@ void PASTECH2(bao_,ch,opname) \
 \
 		/* Broadcast the address of the chief thread's passed-in mem_t to all
 		   threads. */ \
-		mem_t* mem_p = bli_thread_broadcast( thread, mem ); \
+		mem_t* mem_p = bli_thread_broadcast( rntm, thread, mem ); \
 \
 		/* Non-chief threads: Copy the contents of the chief thread's
 		   passed-in mem_t to the passed-in mem_t for this thread. (The
@@ -139,7 +139,7 @@ void PASTECH2(bao_,ch,opname) \
 \
 			/* Broadcast the address of the chief thread's passed-in mem_t
 			   to all threads. */ \
-			mem_t* mem_p = bli_thread_broadcast( thread, mem ); \
+			mem_t* mem_p = bli_thread_broadcast( rntm, thread, mem ); \
 \
 			/* Non-chief threads: Copy the contents of the chief thread's
 			   passed-in mem_t to the passed-in mem_t for this thread. (The
@@ -319,7 +319,7 @@ void PASTECH2(bao_,ch,opname) \
 	); \
 \
 	/* Barrier so that packing is done before computation. */ \
-	bli_thread_barrier( thread ); \
+	bli_thread_barrier( rntm, thread ); \
 }
 
 //INSERT_GENTFUNC_BASIC0( packm_a )

addon/gemmd/bao_l3_packm_b.c

@@ -61,7 +61,7 @@ void PASTECH2(bao_,ch,opname) \
 \
 	/* Barrier to make sure all threads are caught up and ready to begin the
 	   packm stage. */ \
-	bli_thread_barrier( thread ); \
+	bli_thread_barrier( rntm, thread ); \
 \
 	/* Compute the size of the memory block eneded. */ \
 	siz_t size_needed = sizeof( ctype ) * k_pack * n_pack; \
@@ -90,7 +90,7 @@ void PASTECH2(bao_,ch,opname) \
 \
 		/* Broadcast the address of the chief thread's passed-in mem_t to all
 		   threads. */ \
-		mem_t* mem_p = bli_thread_broadcast( thread, mem ); \
+		mem_t* mem_p = bli_thread_broadcast( rntm, thread, mem ); \
 \
 		/* Non-chief threads: Copy the contents of the chief thread's
 		   passed-in mem_t to the passed-in mem_t for this thread. (The
@@ -139,7 +139,7 @@ void PASTECH2(bao_,ch,opname) \
 \
 			/* Broadcast the address of the chief thread's passed-in mem_t
 			   to all threads. */ \
-			mem_t* mem_p = bli_thread_broadcast( thread, mem ); \
+			mem_t* mem_p = bli_thread_broadcast( rntm, thread, mem ); \
 \
 			/* Non-chief threads: Copy the contents of the chief thread's
 			   passed-in mem_t to the passed-in mem_t for this thread. (The
@@ -319,7 +319,7 @@ void PASTECH2(bao_,ch,opname) \
 	); \
 \
 	/* Barrier so that packing is done before computation. */ \
-	bli_thread_barrier( thread ); \
+	bli_thread_barrier( rntm, thread ); \
 }
 
 //INSERT_GENTFUNC_BASIC0( packm_b )

addon/gemmd/thread/bao_l3_decor.c

@@ -0,0 +1,150 @@
+/*
+
+   BLIS
+   An object-based framework for developing high-performance BLAS-like
+   libraries.
+
+   Copyright (C) 2022, The University of Texas at Austin
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions are
+   met:
+    - Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    - Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    - Neither the name(s) of the copyright holder(s) nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+   HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+*/
+
+#include "blis.h"
+
+// Initialize a function pointer array containing function addresses for
+// each of the threading-specific level-3 thread decorators.
+
+static l3ao_decor_ft l3ao_decor_fpa[ BLIS_NUM_THREAD_IMPLS ] =
+{
+	[BLIS_SINGLE] = bao_l3_thread_decorator_single,
+	[BLIS_OPENMP] =
+#if   defined(BLIS_ENABLE_OPENMP)
+	                bao_l3_thread_decorator_openmp,
+#elif defined(BLIS_ENABLE_PTHREADS)
+	                NULL,
+#else
+	                NULL,
+#endif
+	[BLIS_POSIX]  =
+#if   defined(BLIS_ENABLE_PTHREADS)
+	                bao_l3_thread_decorator_pthreads,
+#elif defined(BLIS_ENABLE_OPENMP)
+	                NULL,
+#else
+	                NULL,
+#endif
+};
+
+// Define a dispatcher that chooses a threading-specific function from the
+// above function pointer array.
+
+void bao_l3_thread_decorator
+     (
+       l3aoint_ft func,
+       opid_t   family,
+       obj_t*   alpha,
+       obj_t*   a,
+       obj_t*   d,
+       obj_t*   b,
+       obj_t*   beta,
+       obj_t*   c,
+       cntx_t*  cntx,
+       rntm_t*  rntm
+     )
+{
+	rntm_t rntm_l;
+
+	// Query the threading implementation and the number of threads requested.
+	timpl_t ti = bli_rntm_thread_impl( rntm );
+	dim_t   nt = bli_rntm_num_threads( rntm );
+
+	if ( bli_error_checking_is_enabled() )
+		bao_l3_thread_decorator_check( rntm );
+
+	if ( 1 < nt && ti == BLIS_SINGLE )
+	{
+		// Here, we resolve conflicting information. The caller requested
+		// a sequential threading implementation, but also requested more
+		// than one thread. Here, we choose to favor the requested threading
+		// implementation over the number of threads, and so reset all
+		// parallelism parameters to 1.
+		rntm_l = *rntm;
+		nt = 1;
+		bli_rntm_set_ways_only( 1, 1, 1, 1, 1, &rntm_l );
+		bli_rntm_set_num_threads_only( 1, &rntm_l );
+		rntm = &rntm_l;
+	}
+
+	// Use the timpl_t value to index into the corresponding function address
+	// from the function pointer array.
+	const l3ao_decor_ft fp = l3ao_decor_fpa[ ti ];
+
+	// Call the threading-specific decorator function.
+	fp
+	(
+	  func,
+	  family,
+	  alpha,
+	  a,
+	  d,
+	  b,
+	  beta,
+	  c,
+	  cntx,
+	  rntm
+	);
+}
+
+void bao_l3_thread_decorator_check
+     (
+       rntm_t* rntm
+     )
+{
+	//err_t e_val;
+
+	//e_val = bli_check_valid_thread_impl( bli_rntm_thread_impl( rntm ) );
+	//bli_check_error_code( e_val );
+
+	const timpl_t ti = bli_rntm_thread_impl( rntm );
+
+	if (
+#ifndef BLIS_ENABLE_OPENMP
+	    ti == BLIS_OPENMP ||
+#endif
+#ifndef BLIS_ENABLE_PTHREADS
+	    ti == BLIS_POSIX ||
+#endif
+	    FALSE
+	   )
+	{
+		fprintf( stderr, "\n" );
+		fprintf( stderr, "libblis: User requested threading implementation \"%s\", but that method is\n", ( ti == BLIS_OPENMP ? "openmp" : "pthreads" ) );
+		fprintf( stderr, "libblis: unavailable. Try reconfiguring BLIS with \"-t %s\" and recompiling.\n", ( ti == BLIS_OPENMP ? "openmp" : "pthreads" ) );
+		fprintf( stderr, "libblis: %s: line %d\n", __FILE__, ( int )__LINE__ );
+		bli_abort();
+	}
+}
+