s1kd-appcheck: Add -#, --threads option

Replaced the -j (--jobs) option with -# (--threads), with the intention of eventually adding this same option to other tools such as s1kd-validate, s1kd-brexcheck and s1kd-instance. Also expanded the syntax of the argument to <x[,y]>, where x represents the number of threads created to iterate over the list of objects, and y represents the number of threads created to validate each object (meaning x * y threads are created in total).
kibook · Apr 9, 2024 · b553f5d · b553f5d
1 parent fa140e2
commit b553f5d
Show file tree

Hide file tree

Showing 4 changed files with 296 additions and 143 deletions.
diff --git a/tools/s1kd-appcheck/README.md b/tools/s1kd-appcheck/README.md
@@ -78,10 +78,6 @@ the actual validation.
   - \-i, --ignore \<id:type\>  
     Ignore a specified applicability property when validating.
 
-  - \-j, --jobs \<jobs\>  
-    Specifies the number of jobs to run in parallel when checking an
-    object's applicability.
-
   - \-K, --filter \<cmd\>  
     The command used to filter objects prior to validation. The objects
     will be passed to the command on stdin, and the filters will be
@@ -145,6 +141,27 @@ the actual validation.
     Check with CCT dependency tests added to assertions which use the
     dependant values.
 
+  - \-\#, --threads \<x\[,y\]\>  
+    Specifies the number of parallel threads to use for object
+    validation. `x` represents the number of threads used to iterate
+    over the list of objects. `y` represents the number of threads used
+    to check each individual object. If both are specified, this means
+    that in total `x * y` threads will be created. When either is
+    unspecified, the default value is 1.
+
+    The numbers chosen typically will depend on the number of CPU cores
+    available, how many objects are being validated, and the complexity
+    of the applicability in the objects. Generally, the total number of
+    threads (`x * y`) should not exceed the number of available cores.
+    If you are validating a large number of objects with relatively
+    little applicability, then `x` should be greater than `y`. On the
+    other hand, if you are validating a small number of objects with
+    complex applicability, then `y` should be greater than `x`. When
+    validating a single object, `x` should always be 1.
+
+    Benchmarks should be performed to find the combination that is the
+    best for your hardware and data.
+
   - \-^, --remove-deleted  
     Validate objects with elements that have a change type of "delete"
     removed.

diff --git a/tools/s1kd-appcheck/doc/DMC-S1KDTOOLS-A-11-00-00-00A-040A-D_EN-CA.XML b/tools/s1kd-appcheck/doc/DMC-S1KDTOOLS-A-11-00-00-00A-040A-D_EN-CA.XML
@@ -6,10 +6,10 @@
       <dmIdent>
         <dmCode modelIdentCode="S1KDTOOLS" systemDiffCode="A" systemCode="11" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
         <language languageIsoCode="en" countryIsoCode="CA"/>
-        <issueInfo issueNumber="010" inWork="04"/>
+        <issueInfo issueNumber="010" inWork="05"/>
       </dmIdent>
       <dmAddressItems>
-        <issueDate year="2024" month="04" day="08"/>
+        <issueDate year="2024" month="04" day="09"/>
         <dmTitle>
           <techName>s1kd-appcheck(1) | s1kd-tools</techName>
         </dmTitle>
@@ -45,7 +45,7 @@
         <simplePara>Add new exit status.</simplePara>
       </reasonForUpdate>
       <reasonForUpdate id="rfu-0003" updateHighlight="1">
-        <simplePara>Add --jobs option.</simplePara>
+        <simplePara>Add --threads option.</simplePara>
       </reasonForUpdate>
       <reasonForUpdate id="rfu-0004" updateHighlight="1">
         <simplePara>Add --ignore option.</simplePara>
@@ -146,12 +146,6 @@
                 <para>Ignore a specified applicability property when validating.</para>
               </listItemDefinition>
             </definitionListItem>
-            <definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0003">
-              <listItemTerm>-j, --jobs &lt;jobs&gt;</listItemTerm>
-              <listItemDefinition>
-                <para>Specifies the number of jobs to run in parallel when checking an object's applicability.</para>
-              </listItemDefinition>
-            </definitionListItem>
             <definitionListItem>
               <listItemTerm>-K, --filter &lt;cmd&gt;</listItemTerm>
               <listItemDefinition>
@@ -254,6 +248,14 @@
                 <para>Check with CCT dependency tests added to assertions which use the dependant values.</para>
               </listItemDefinition>
             </definitionListItem>
+            <definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0003">
+              <listItemTerm>-#, --threads &lt;x[,y]&gt;</listItemTerm>
+              <listItemDefinition>
+                <para>Specifies the number of parallel threads to use for object validation. <verbatimText>x</verbatimText> represents the number of threads used to iterate over the list of objects. <verbatimText>y</verbatimText> represents the number of threads used to check each individual object. If both are specified, this means that in total <verbatimText>x * y</verbatimText> threads will be created. When either is unspecified, the default value is 1.</para>
+                <para>The numbers chosen typically will depend on the number of CPU cores available, how many objects are being validated, and the complexity of the applicability in the objects. Generally, the total number of threads (<verbatimText>x * y</verbatimText>) should not exceed the number of available cores. If you are validating a large number of objects with relatively little applicability, then <verbatimText>x</verbatimText> should be greater than <verbatimText>y</verbatimText>. On the other hand, if you are validating a small number of objects with complex applicability, then <verbatimText>y</verbatimText> should be greater than <verbatimText>x</verbatimText>. When validating a single object, <verbatimText>x</verbatimText> should always be 1.</para>
+                <para>Benchmarks should be performed to find the combination that is the best for your hardware and data.</para>
+              </listItemDefinition>
+            </definitionListItem>
             <definitionListItem>
               <listItemTerm>-^, --remove-deleted</listItemTerm>
               <listItemDefinition>

diff --git a/tools/s1kd-appcheck/doc/s1kd-appcheck.1 b/tools/s1kd-appcheck/doc/s1kd-appcheck.1
@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "s1kd-appcheck" "1" "2024-04-08" "" "s1kd-tools"
+.TH "s1kd-appcheck" "1" "2024-04-09" "" "s1kd-tools"
 .hy
 .SH NAME
 .PP
@@ -87,10 +87,6 @@ Show help/usage message.
 -i, --ignore <id:type>
 Ignore a specified applicability property when validating.
 .TP
--j, --jobs <jobs>
-Specifies the number of jobs to run in parallel when checking an
-object\[aq]s applicability.
-.TP
 -K, --filter <cmd>
 The command used to filter objects prior to validation.
 The objects will be passed to the command on stdin, and the filters will
@@ -156,6 +152,33 @@ Print an XML report of the check.
 Check with CCT dependency tests added to assertions which use the
 dependant values.
 .TP
+-#, --threads <x[,y]>
+Specifies the number of parallel threads to use for object validation.
+\f[C]x\f[R] represents the number of threads used to iterate over the
+list of objects.
+\f[C]y\f[R] represents the number of threads used to check each
+individual object.
+If both are specified, this means that in total \f[C]x * y\f[R] threads
+will be created.
+When either is unspecified, the default value is 1.
+.RS
+.PP
+The numbers chosen typically will depend on the number of CPU cores
+available, how many objects are being validated, and the complexity of
+the applicability in the objects.
+Generally, the total number of threads (\f[C]x * y\f[R]) should not
+exceed the number of available cores.
+If you are validating a large number of objects with relatively little
+applicability, then \f[C]x\f[R] should be greater than \f[C]y\f[R].
+On the other hand, if you are validating a small number of objects with
+complex applicability, then \f[C]y\f[R] should be greater than
+\f[C]x\f[R].
+When validating a single object, \f[C]x\f[R] should always be 1.
+.PP
+Benchmarks should be performed to find the combination that is the best
+for your hardware and data.
+.RE
+.TP
 -\[ha], --remove-deleted
 Validate objects with elements that have a change type of
 \[dq]delete\[dq] removed.