Deprecate KMP_PLACE_THREADS and rename as KMP_HW_SUBSET

[tlwilmar]

Summary

Deprecated KMP_PLACE_THREADS and renamed it into KMP_HW_SUBSET due to confusion about its purpose and function among users.

Patch by Andrey Churbanov

[AndreyChurbanov]

LGTM

runtime/src/i18n/en_US.txt

 # --------------------------------------------------------------------------------------------------
 
 # Meta information about message catalog.
 
 Language "English"
 Country  "USA"
 LangId   "1033"
 Version  "2"
-Revision "20140827"
+Revision "20160405"
 
 
 
 # --------------------------------------------------------------------------------------------------
 -*- STRINGS -*-
 # --------------------------------------------------------------------------------------------------
 
 # Strings are not complete messages, just fragments. We need to work on it and reduce number of

 AffGranCantUseMultGroups     "Cannot use affinity granularity \"%1$s\" with multiple Windows* OS processor groups, using \"%2$s\"."
 AffWindowsProcGroupMap       "%1$s: Mapping Windows* OS processor group <i> proc <j> to OS proc 64*<i>+<j>."
 AffOSProcToGroup             "%1$s: OS proc %2$d maps to Windows* OS processor group %3$d proc %4$d"
 AffBalancedNotAvail          "%1$s: Affinity balanced is not available."
 OBSOLETE                     "%1$s: granularity=core will be used."
 EnvLockWarn                  "%1$s must be set prior to first OMP lock call or critical section; ignored."
 FutexNotSupported            "futex system call not supported; %1$s=%2$s ignored."
 AffGranUsing                 "%1$s: granularity=%2$s will be used."
-AffThrPlaceInvalid           "%1$s: invalid value \"%2$s\", valid format is \"Ns[@N],Nc[@N],Nt "
+AffHWSubsetInvalid           "%1$s: invalid value \"%2$s\", valid format is \"Ns[@N],Nc[@N],Nt "
                              "(nSockets@offset, nCores@offset, nTthreads per core)\"."
-AffThrPlaceUnsupported       "KMP_PLACE_THREADS ignored: unsupported architecture."
-AffThrPlaceManyCores         "KMP_PLACE_THREADS ignored: too many cores requested."
+AffHWSubsetUnsupported       "KMP_HW_SUBSET ignored: unsupported architecture."
+AffHWSubsetManyCores         "KMP_HW_SUBSET ignored: too many cores requested."
 SyntaxErrorUsing             "%1$s: syntax error, using %2$s."
 AdaptiveNotSupported         "%1$s: Adaptive locks are not supported; using queuing."
 EnvSyntaxError               "%1$s: Invalid symbols found. Check the value \"%2$s\"."
 EnvSpacesNotAllowed          "%1$s: Spaces between digits are not allowed \"%2$s\"."
 BoundToOSProcSet             "%1$s: pid %2$d thread %3$d bound to OS proc set %4$s"
 CnsLoopIncrIllegal           "%1$s error: parallel loop increment and condition are inconsistent."
 NoGompCancellation           "libgomp cancellation is not currently supported."
-AffThrPlaceNonUniform        "KMP_PLACE_THREADS ignored: non-uniform topology."
-AffThrPlaceNonThreeLevel     "KMP_PLACE_THREADS ignored: only three-level topology is supported."
+AffHWSubsetNonUniform        "KMP_HW_SUBSET ignored: non-uniform topology."
+AffHWSubsetNonThreeLevel     "KMP_HW_SUBSET ignored: only three-level topology is supported."
 AffGranTopGroup              "%1$s: granularity=%2$s is not supported with KMP_TOPOLOGY_METHOD=group. Using \"granularity=fine\"."
 AffGranGroupType             "%1$s: granularity=group is not supported with KMP_AFFINITY=%2$s. Using \"granularity=core\"."
-AffThrPlaceManySockets       "KMP_PLACE_THREADS ignored: too many sockets requested."
-AffThrPlaceDeprecated        "KMP_PLACE_THREADS \"o\" offset designator deprecated, please use @ prefix for offset value."
+AffHWSubsetManySockets       "KMP_HW_SUBSET ignored: too many sockets requested."
+AffHWSubsetDeprecated        "KMP_HW_SUBSET \"o\" offset designator deprecated, please use @ prefix for offset value."
 AffUsingHwloc                "%1$s: Affinity capable, using hwloc."
 AffIgnoringHwloc             "%1$s: Ignoring hwloc mechanism."
 AffHwlocErrorOccurred        "%1$s: Hwloc failed in %2$s. Relying on internal affinity mechanisms."
 EnvSerialWarn                "%1$s must be set prior to OpenMP runtime library initialization; ignored."
+EnvVarDeprecated             "%1$s variable deprecated, please use %2$s instead."
 
 
 # --------------------------------------------------------------------------------------------------
 -*- HINTS -*-
 # --------------------------------------------------------------------------------------------------
 
 # Hints. Hint may be printed after a message. Usually it is longer explanation text or suggestion.
 # To maintain hint numbers (they are visible to customers), add new hints to the end.

runtime/src/kmp_affinity.cpp

if (__kmp_place_num_sockets == 0)
         __kmp_place_num_sockets = nPackages;    // use all available sockets
     if (__kmp_place_num_cores == 0)
         __kmp_place_num_cores = nCoresPerPkg;   // use all available cores
     if (__kmp_place_num_threads_per_core == 0 ||
         __kmp_place_num_threads_per_core > __kmp_nThreadsPerCore)
         __kmp_place_num_threads_per_core = __kmp_nThreadsPerCore; // use all HW contexts
 
     if ( !__kmp_affinity_uniform_topology() ) {
-        KMP_WARNING( AffThrPlaceNonUniform );
+        KMP_WARNING( AffHWSubsetNonUniform );
         return; // don't support non-uniform topology
     }
     if ( depth != 3 ) {
-        KMP_WARNING( AffThrPlaceNonThreeLevel );
+        KMP_WARNING( AffHWSubsetNonThreeLevel );
         return; // don't support not-3-level topology
     }
     if (__kmp_place_socket_offset + __kmp_place_num_sockets > nPackages) {
-        KMP_WARNING(AffThrPlaceManySockets);
+        KMP_WARNING(AffHWSubsetManySockets);
         return;
     }
     if ( __kmp_place_core_offset + __kmp_place_num_cores > nCoresPerPkg ) {
-        KMP_WARNING( AffThrPlaceManyCores );
+        KMP_WARNING( AffHWSubsetManyCores );
         return;
     }
 
     AddrUnsPair *newAddr = (AddrUnsPair *)__kmp_allocate( sizeof(AddrUnsPair) *
         __kmp_place_num_sockets * __kmp_place_num_cores * __kmp_place_num_threads_per_core);
 
     int i, j, k, n_old = 0, n_new = 0;
     for (i = 0; i < nPackages; ++i)

runtime/src/kmp_settings.c

 
 } // __kmp_stg_print_speculative_statsfile
 
 #endif // KMP_DEBUG_ADAPTIVE_LOCKS
 
 #endif // KMP_USE_ADAPTIVE_LOCKS
 
 // -------------------------------------------------------------------------------------------------
-// KMP_PLACE_THREADS
+// KMP_HW_SUBSET (was KMP_PLACE_THREADS)
 // -------------------------------------------------------------------------------------------------
 
 static void
-__kmp_stg_parse_place_threads( char const * name, char const * value, void * data ) {
+__kmp_stg_parse_hw_subset( char const * name, char const * value, void * data ) {
     // Value example: 5Cx2Tx15O
     // Which means "use 5 cores with offset 15, 2 threads per core"
     // AC: extended to sockets level, examples of
     //     "use 2 sockets with offset 6, 2 cores with offset 2 per socket, 2 threads per core":
     //     2s,6o,2c,2o,2t; 2s,6o,2c,2t,2o; 2s@6,2c@2,2t
     //     To not break legacy code core-offset can be last;
     //     postfix "o" or prefix @ can be offset designator.
     // Note: not all syntax errors are analyzed, some may be skipped.
 #define CHECK_DELIM(_x)   (*(_x) == ',' || *(_x) == 'x')
+    static int parsed = 0;
     int         num;
     int single_warning = 0;
     int flagS = 0, flagC = 0, flagT = 0, flagSO = 0, flagCO = 0;
     const char *next = value;
     const char *prev;
 
+    if( strcmp(name, "KMP_PLACE_THREADS") == 0 ) {
+        KMP_INFORM(EnvVarDeprecated,name,"KMP_HW_SUBSET");
+        if( parsed == 1 ) {
+            return; // already parsed KMP_HW_SUBSET
+        }
+    }
+    parsed = 1;
+
+    SKIP_WS(next);  // skip white spaces
+    if (*next == '\0')
+        return;   // no data provided, retain default values
+    if( strcmp(name, "KMP_PLACE_THREADS") == 0 ) {
+        KMP_INFORM(EnvVarDeprecated,name,"KMP_HW_SUBSET");
+        if( parsed == 1 ) {
+            return; // already parsed KMP_HW_SUBSET
+        }
+    }
+    parsed = 1;
+
     SKIP_WS(next);  // skip white spaces
     if (*next == '\0')
         return;   // no data provided, retain default values
     // Get num_sockets first (or whatever specified)
     if (*next >= '0' && *next <= '9') {
         prev = next;
         SKIP_DIGITS(next);
         num = __kmp_str_to_int(prev, *next);
         SKIP_WS(next);
         if (*next == 's' || *next == 'S') {  // e.g. "2s"
             __kmp_place_num_sockets = num;
             flagS = 1; // got num sockets
             next++;
             if (*next == '@') { // socket offset, e.g. "2s@4"
                 flagSO = 1;
                 prev = ++next;  // don't allow spaces for simplicity
                 if (!(*next >= '0' && *next <= '9')) {
-                    KMP_WARNING(AffThrPlaceInvalid, name, value);
+                    KMP_WARNING(AffHWSubsetInvalid, name, value);
                     return;
                 }
                 SKIP_DIGITS(next);
                 num = __kmp_str_to_int(prev, *next);
                 __kmp_place_socket_offset = num;
             }
         } else if (*next == 'c' || *next == 'C') {
             __kmp_place_num_cores = num;
             flagS = flagC = 1; // sockets were not specified - use default
             next++;
             if (*next == '@') { // core offset, e.g. "2c@6"
                 flagCO = 1;
                 prev = ++next;  // don't allow spaces for simplicity
                 if (!(*next >= '0' && *next <= '9')) {
-                    KMP_WARNING(AffThrPlaceInvalid, name, value);
+                    KMP_WARNING(AffHWSubsetInvalid, name, value);
                     return;
                 }
                 SKIP_DIGITS(next);
                 num = __kmp_str_to_int(prev, *next);
                 __kmp_place_core_offset = num;
             }
         } else if (CHECK_DELIM(next)) {
             __kmp_place_num_cores = num; // no letter-designator - num cores
             flagS = flagC = 1; // sockets were not specified - use default
             next++;
         } else if (*next == 't' || *next == 'T') {
             __kmp_place_num_threads_per_core = num;
             // sockets, cores were not specified - use default
             return;   // we ignore offset value in case all cores are used
         } else if (*next == '\0') {
             __kmp_place_num_cores = num;
             return;   // the only value provided - set num cores
         } else {
-            KMP_WARNING(AffThrPlaceInvalid, name, value);
+            KMP_WARNING(AffHWSubsetInvalid, name, value);
             return;
         }
     } else {
-        KMP_WARNING(AffThrPlaceInvalid, name, value);
+        KMP_WARNING(AffHWSubsetInvalid, name, value);
         return;
     }
     KMP_DEBUG_ASSERT(flagS); // num sockets should already be set here
     SKIP_WS(next);
     if (*next == '\0')
         return;   // " n  " - something like this
     if (CHECK_DELIM(next)) {
         next++;   // skip delimiter
if (*next >= '0' && *next <= '9') {
             KMP_DEBUG_ASSERT(flagC == 0);
             __kmp_place_num_cores = num;
             flagC = 1;
             next++;
             if (*next == '@') { // core offset, e.g. "2c@6"
                 flagCO = 1;
                 prev = ++next;  // don't allow spaces for simplicity
                 if (!(*next >= '0' && *next <= '9')) {
-                    KMP_WARNING(AffThrPlaceInvalid, name, value);
+                    KMP_WARNING(AffHWSubsetInvalid, name, value);
                     return;
                 }
                 SKIP_DIGITS(next);
                 num = __kmp_str_to_int(prev, *next);
                 __kmp_place_core_offset = num;
             }
         } else if (*next == 'o' || *next == 'O') { // offset specified
-            KMP_WARNING(AffThrPlaceDeprecated);
+            KMP_WARNING(AffHWSubsetDeprecated);
             single_warning = 1;
             if (flagC) { // whether num_cores already specified (sockets skipped)
                 KMP_DEBUG_ASSERT(!flagCO); // either "o" or @, not both
                 __kmp_place_core_offset = num;
             } else {
                 KMP_DEBUG_ASSERT(!flagSO); // either "o" or @, not both
                 __kmp_place_socket_offset = num;
             }
             next++;
         } else if (*next == 't' || *next == 'T') {
             KMP_DEBUG_ASSERT(flagT == 0);
             __kmp_place_num_threads_per_core = num;
             flagC = 1; // num_cores could be skipped ?
             flagT = 1;
             next++; // can have core-offset specified after num threads
         } else if (*next == '\0') {
             KMP_DEBUG_ASSERT(flagC); // 4x2 means 4 cores 2 threads per core
             __kmp_place_num_threads_per_core = num;
             return;   // two values provided without letter-designator
         } else {
-            KMP_WARNING(AffThrPlaceInvalid, name, value);
+            KMP_WARNING(AffHWSubsetInvalid, name, value);
             return;
         }
     } else {
-        KMP_WARNING(AffThrPlaceInvalid, name, value);
+        KMP_WARNING(AffHWSubsetInvalid, name, value);
         return;
     }
     SKIP_WS(next);
     if (*next == '\0')
         return;   // " Ns,Nc  " - something like this
     if (CHECK_DELIM(next)) {
         next++;   // skip delimiter
         SKIP_WS(next);
if (*next >= '0' && *next <= '9') {
             next++; // can have core-offset specified later (e.g. 2s,1c,2t,3o)
         } else if (*next == 'c' || *next == 'C') {
             KMP_DEBUG_ASSERT(flagC == 0);
             __kmp_place_num_cores = num;
             flagC = 1;
             next++;
             //KMP_DEBUG_ASSERT(*next != '@'); // socket offset used "o" designator
         } else if (*next == 'o' || *next == 'O') {
-            KMP_WARNING(AffThrPlaceDeprecated);
+            KMP_WARNING(AffHWSubsetDeprecated);
             single_warning = 1;
             KMP_DEBUG_ASSERT(flagC);
             //KMP_DEBUG_ASSERT(!flagSO); // socket offset couldn't use @ designator
             __kmp_place_core_offset = num;
             next++;
         } else {
-            KMP_WARNING(AffThrPlaceInvalid, name, value);
+            KMP_WARNING(AffHWSubsetInvalid, name, value);
             return;
         }
     } else {
-        KMP_WARNING(AffThrPlaceInvalid, name, value);
+        KMP_WARNING(AffHWSubsetInvalid, name, value);
         return;
     }
     KMP_DEBUG_ASSERT(flagC);
     SKIP_WS(next);
     if ( *next == '\0' )
             return;
     if (CHECK_DELIM(next)) {
         next++;   // skip delimiter
         SKIP_WS(next);
     }
 
     // Get 4-th value (could be core-offset, num_threads)
     if (*next >= '0' && *next <= '9') {
         prev = next;
         SKIP_DIGITS(next);
         num = __kmp_str_to_int(prev, *next);
         SKIP_WS(next);
         if (*next == 'o' || *next == 'O') {
             if (!single_warning) { // warn once
-                KMP_WARNING(AffThrPlaceDeprecated);
+                KMP_WARNING(AffHWSubsetDeprecated);
             }
             KMP_DEBUG_ASSERT(!flagSO); // socket offset couldn't use @ designator
             __kmp_place_core_offset = num;
             next++;
         } else if (*next == 't' || *next == 'T') {
             KMP_DEBUG_ASSERT(flagT == 0);
             __kmp_place_num_threads_per_core = num;
             flagT = 1;
             next++; // can have core-offset specified after num threads
         } else {
-            KMP_WARNING(AffThrPlaceInvalid, name, value);
+            KMP_WARNING(AffHWSubsetInvalid, name, value);
             return;
         }
     } else {
-        KMP_WARNING(AffThrPlaceInvalid, name, value);
+        KMP_WARNING(AffHWSubsetInvalid, name, value);
         return;
     }
     SKIP_WS(next);
     if ( *next == '\0' )
         return;
     if (CHECK_DELIM(next)) {
         next++;   // skip delimiter
         SKIP_WS(next);
     }
 
     // Get 5-th value (could be core-offset, num_threads)
     if (*next >= '0' && *next <= '9') {
         prev = next;
         SKIP_DIGITS(next);
         num = __kmp_str_to_int(prev, *next);
         SKIP_WS(next);
         if (*next == 'o' || *next == 'O') {
             if (!single_warning) { // warn once
-                KMP_WARNING(AffThrPlaceDeprecated);
+                KMP_WARNING(AffHWSubsetDeprecated);
             }
             KMP_DEBUG_ASSERT(flagT);
             KMP_DEBUG_ASSERT(!flagSO); // socket offset couldn't use @ designator
             __kmp_place_core_offset = num;
         } else if (*next == 't' || *next == 'T') {
             KMP_DEBUG_ASSERT(flagT == 0);
             __kmp_place_num_threads_per_core = num;
         } else {
-            KMP_WARNING(AffThrPlaceInvalid, name, value);
+            KMP_WARNING(AffHWSubsetInvalid, name, value);
         }
     } else {
-        KMP_WARNING(AffThrPlaceInvalid, name, value);
+        KMP_WARNING(AffHWSubsetInvalid, name, value);
     }
     return;
 #undef CHECK_DELIM
 }
 
 static void
-__kmp_stg_print_place_threads( kmp_str_buf_t * buffer, char const * name, void * data ) {
+__kmp_stg_print_hw_subset( kmp_str_buf_t * buffer, char const * name, void * data ) {
     if (__kmp_place_num_sockets + __kmp_place_num_cores + __kmp_place_num_threads_per_core) {
         int comma = 0;
         kmp_str_buf_t buf;
         __kmp_str_buf_init(&buf);
         if(__kmp_env_format)
             KMP_STR_BUF_PRINT_NAME_EX(name);
         else
             __kmp_str_buf_print(buffer, "   %s='", name);
#endif
     { "KMP_LOCK_KIND",                     __kmp_stg_parse_lock_kind,          __kmp_stg_print_lock_kind,          NULL, 0, 0 },
     { "KMP_SPIN_BACKOFF_PARAMS",           __kmp_stg_parse_spin_backoff_params, __kmp_stg_print_spin_backoff_params, NULL, 0, 0 },
 #if KMP_USE_ADAPTIVE_LOCKS
     { "KMP_ADAPTIVE_LOCK_PROPS",           __kmp_stg_parse_adaptive_lock_props,__kmp_stg_print_adaptive_lock_props,  NULL, 0, 0 },
 #if KMP_DEBUG_ADAPTIVE_LOCKS
     { "KMP_SPECULATIVE_STATSFILE",         __kmp_stg_parse_speculative_statsfile,__kmp_stg_print_speculative_statsfile,  NULL, 0, 0 },
 #endif
 #endif // KMP_USE_ADAPTIVE_LOCKS
-    { "KMP_PLACE_THREADS",                 __kmp_stg_parse_place_threads,      __kmp_stg_print_place_threads,      NULL, 0, 0 },
+    { "KMP_PLACE_THREADS",                 __kmp_stg_parse_hw_subset,      __kmp_stg_print_hw_subset,      NULL, 0, 0 },
+    { "KMP_HW_SUBSET",                     __kmp_stg_parse_hw_subset,      __kmp_stg_print_hw_subset,      NULL, 0, 0 },
 #if USE_ITT_BUILD
     { "KMP_FORKJOIN_FRAMES",               __kmp_stg_parse_forkjoin_frames,    __kmp_stg_print_forkjoin_frames,    NULL, 0, 0 },
     { "KMP_FORKJOIN_FRAMES_MODE",          __kmp_stg_parse_forkjoin_frames_mode,__kmp_stg_print_forkjoin_frames_mode,  NULL, 0, 0 },
 #endif
 
 # if OMP_40_ENABLED
     { "OMP_DISPLAY_ENV",                   __kmp_stg_parse_omp_display_env,    __kmp_stg_print_omp_display_env,    NULL, 0, 0 },
     { "OMP_CANCELLATION",                  __kmp_stg_parse_omp_cancellation,   __kmp_stg_print_omp_cancellation,   NULL, 0, 0 },