Defined rntm_t to relocate cntx_t.thrloop (#235).

Details:
- Defined a new struct datatype, rntm_t (runtime), to house the thrloop
  field of the cntx_t (context). The thrloop array holds the number of
  ways of parallelism (thread "splits") to extract per level-3
  algorithmic loop until those values can be used to create a
  corresponding node in the thread control tree (thrinfo_t structure),
  which (for any given level-3 invocation) usually happens by the time
  the macrokernel is called for the first time.
- Relocating the thrloop from the cntx_t remedies a thread-safety issue
  when invoking level-3 operations from two or more application threads.
  The race condition existed because the cntx_t, a pointer to which is
  usually queried from the global kernel structure (gks), is supposed to
  be a read-only. However, the previous code would write to the cntx_t's
  thrloop field *after* it had been queried, thus violating its read-only
  status. In practice, this would not cause a problem when a sequential
  application made a multithreaded call to BLIS, nor when two or more
  application threads used the same parallelization scheme when calling
  BLIS, because in either case all application theads would be using
  the same ways of parallelism for each loop. The true effects of the
  race condition were limited to situations where two or more application
  theads used *different* parallelization schemes for any given level-3
  call.
- In remedying the above race condition, the application or calling
  library can now specify the parallelization scheme on a per-call basis.
  All that is required is that the thread encode its request for
  parallelism into the rntm_t struct prior to passing the address of the
  rntm_t to one of the expert interfaces of either the typed or object
  APIs. This allows, for example, one application thread to extract 4-way
  parallelism from a call to gemm while another application thread
  requests 2-way parallelism. Or, two threads could each request 4-way
  parallelism, but from different loops.
- A rntm_t* parameter has been added to the function signatures of most
  of the level-3 implementation stack (with the most notable exception
  being packm) as well as all level-1v, -1d, -1f, -1m, and -2 expert
  APIs. (A few internal functions gained the rntm_t* parameter even
  though they currently have no use for it, such as bli_l3_packm().)
  This required some internal calls to some of those functions to
  be updated since BLIS was already using those operations internally
  via the expert interfaces. For situations where a rntm_t object is
  not available, such as within packm/unpackm implementations, NULL is
  passed in to the relevant expert interfaces. This is acceptable for
  now since parallelism is not obtained for non-level-3 operations.
- Revamped how global parallelism is encoded. First, the conventional
  environment variables such as BLIS_NUM_THREADS and BLIS_*_NT  are only
  read once, at library initialization. (Thanks to Nathaniel Smith for
  suggesting this to avoid repeated calls getenv(), which can be slow.)
  Those values are recorded to a global rntm_t object. Public APIs, in
  bli_thread.c, are still available to get/set these values from the
  global rntm_t, though now the "set" functions have additional logic
  to ensure that the values are set in a synchronous manner via a mutex.
  If/when NULL is passed into an expert API (meaning the user opted to
  not provide a custom rntm_t), the values from the global rntm_t are
  copied to a local rntm_t, which is then passed down the function stack.
  Calling a basic API is equivalent to calling the expert APIs with NULL
  for the cntx and rntm parameters, which means the semantic behavior of
  these basic APIs (vis-a-vis multithreading) is unchanged from before.
- Renamed bli_cntx_set_thrloop_from_env() to bli_rntm_set_ways_for_op()
  and reimplemented, with the function now being able to treat the
  incoming rntm_t in a manner agnostic to its origin--whether it came
  from the application or is an internal copy of the global rntm_t.
- Removed various global runtime APIs for setting the number of ways of
  parallelism for individual loops (e.g. bli_thread_set_*_nt()) as well
  as the corresponding "get" functions. The new model simplifies these
  interfaces so that one must either set the total number of threads, OR
  set all of the ways of parallelism for each loop simultaneously (in a
  single function call).
- Updated sandbox/ref99 according to above changes.
- Rewrote/augmented docs/Multithreading.md to document the three methods
  (and two specific ways within each method) of requesting parallelism
  in BLIS.
- Removed old, disabled code from bli_l3_thrinfo.c.
- Whitespace changes to code (e.g. bli_obj.c) and docs/BuildSystem.md.

frame/include/bli_misc_macro_defs.h

@@ -263,6 +263,13 @@ static void bli_toggle_bool( bool_t* b )
 	else if ( bli_is_scomplex( dt ) ) PASTEMAC(c,fname)(o0,o1,o2,o3,o4,o5,o6,o7,o8,o9,o10,o11,o12,o13,o14,o15,o16,o17,o18,o19); \
 	else if ( bli_is_dcomplex( dt ) ) PASTEMAC(z,fname)(o0,o1,o2,o3,o4,o5,o6,o7,o8,o9,o10,o11,o12,o13,o14,o15,o16,o17,o18,o19); \
 }
+#define bli_call_ft_21( dt, fname, o0, o1, o2, o3, o4, o5, o6, o7, o8, o9, o10, o11, o12, o13, o14, o15, o16, o17, o18, o19, o20 ) \
+{ \
+	if      ( bli_is_float( dt )    ) PASTEMAC(s,fname)(o0,o1,o2,o3,o4,o5,o6,o7,o8,o9,o10,o11,o12,o13,o14,o15,o16,o17,o18,o19,o20); \
+	else if ( bli_is_double( dt )   ) PASTEMAC(d,fname)(o0,o1,o2,o3,o4,o5,o6,o7,o8,o9,o10,o11,o12,o13,o14,o15,o16,o17,o18,o19,o20); \
+	else if ( bli_is_scomplex( dt ) ) PASTEMAC(c,fname)(o0,o1,o2,o3,o4,o5,o6,o7,o8,o9,o10,o11,o12,o13,o14,o15,o16,o17,o18,o19,o20); \
+	else if ( bli_is_dcomplex( dt ) ) PASTEMAC(z,fname)(o0,o1,o2,o3,o4,o5,o6,o7,o8,o9,o10,o11,o12,o13,o14,o15,o16,o17,o18,o19,o20); \
+}
 
 
 

frame/include/bli_oapi_ba.h

@@ -45,8 +45,9 @@
 #undef  BLIS_OAPI_EX_PARAMS
 #define BLIS_OAPI_EX_PARAMS
 
-// Define the macro to declare a local expert variables that are initialized
-// to NULL.
+// Define the macro to declare local expert variables that are initialized
+// to NULL. The "( void )" statements are to prevent unused variable
+// warnings by the compiler.
 #undef  BLIS_OAPI_EX_DECLS
-#define BLIS_OAPI_EX_DECLS   cntx_t* cntx = NULL; ( void )cntx;
-
+#define BLIS_OAPI_EX_DECLS   cntx_t* cntx = NULL; ( void )cntx; \
+                             rntm_t* rntm = NULL; ( void )rntm;

frame/include/bli_oapi_ex.h

@@ -43,7 +43,7 @@
 // Define the macro to add expert arguments to function signatures
 // and prototypes.
 #undef  BLIS_OAPI_EX_PARAMS
-#define BLIS_OAPI_EX_PARAMS   ,cntx_t* cntx
+#define BLIS_OAPI_EX_PARAMS   ,cntx_t* cntx, rntm_t* rntm
 
 // Define the macro to omit the expert variable declaration block, since
 // it is not needed when expert parameters are passed in through the API.

frame/include/bli_tapi_ba.h

@@ -32,7 +32,7 @@
 
 */
 
-// This file defines macros used to allow the _oapi.c files to produce
+// This file defines macros used to allow the _tapi.c files to produce
 // typed APIs that omit expert parameters.
 
 // Define the macro to remove the function name suffix (in function
@@ -45,8 +45,10 @@
 #undef  BLIS_TAPI_EX_PARAMS
 #define BLIS_TAPI_EX_PARAMS
 
-// Define the macro to declare a local expert variables that are initialized
-// to NULL.
+// Define the macro to declare local expert variables that are initialized
+// to NULL. The "( void )" statements are to prevent unused variable
+// warnings by the compiler.
 #undef  BLIS_TAPI_EX_DECLS
-#define BLIS_TAPI_EX_DECLS   cntx_t* cntx = NULL; ( void )cntx;
+#define BLIS_TAPI_EX_DECLS   cntx_t* cntx = NULL; ( void )cntx; \
+                             rntm_t* rntm = NULL; ( void )rntm;
 

frame/include/bli_tapi_ex.h

@@ -43,7 +43,7 @@
 // Define the macro to add expert arguments to function signatures
 // and prototypes.
 #undef  BLIS_TAPI_EX_PARAMS
-#define BLIS_TAPI_EX_PARAMS   ,cntx_t* cntx
+#define BLIS_TAPI_EX_PARAMS   ,cntx_t* cntx, rntm_t* rntm
 
 // Define the macro to omit the expert variable declaration block, since
 // it is not needed when expert parameters are passed in through the API.

frame/include/bli_type_defs.h

@@ -883,6 +883,7 @@ typedef struct
 	void* buf_align;
 } pblk_t;
 
+
 // -- Pool type --
 
 typedef struct
@@ -897,11 +898,13 @@ typedef struct
 	siz_t   align_size;
 } pool_t;
 
+
 // -- Mutex object type --
 
 #include "bli_mutex.h"
 #include "bli_malloc.h"
 
+
 // -- Memory broker object type --
 
 typedef struct membrk_s
@@ -913,6 +916,7 @@ typedef struct membrk_s
 	free_ft   free_fp;
 } membrk_t;
 
+
 // -- Memory object type --
 
 typedef struct mem_s
@@ -924,6 +928,7 @@ typedef struct mem_s
 	siz_t     size;
 } mem_t;
 
+
 // -- Control tree node type --
 
 struct cntl_s
@@ -1117,6 +1122,7 @@ static void bli_obj_init_subpart_from( obj_t* a, obj_t* b )
 	b->n_panel   = a->n_panel;
 }
 
+
 // -- Context type --
 
 typedef struct cntx_s
@@ -1139,12 +1145,20 @@ typedef struct cntx_s
 	pack_t    schema_b_panel;
 	pack_t    schema_c_panel;
 
-	dim_t     thrloop[ BLIS_NUM_LOOPS ];
-
 	membrk_t* membrk;
 } cntx_t;
 
 
+// -- Runtime type --
+
+typedef struct rntm_s
+{
+	dim_t     num_threads;
+	dim_t     thrloop[ BLIS_NUM_LOOPS ];
+
+} rntm_t;
+
+
 // -- Error types --
 
 typedef enum

frame/include/blis.h

@@ -98,6 +98,7 @@ extern "C" {
 #include "bli_func.h"
 #include "bli_mbool.h"
 #include "bli_cntx.h"
+#include "bli_rntm.h"
 #include "bli_gks.h"
 #include "bli_ind.h"
 #include "bli_membrk.h"