Merge pull request #17826 from JamesDeFabia/HPCC-29907

HPCC-29907 Document TIME attribute Reviewed-By: Richard Taylor <[email protected]> Reviewed-by: Gavin Halliday <[email protected]> Merged-by: Gavin Halliday <[email protected]>
hpcc-systems · Oct 4, 2023 · b107b23 · b107b23
2 parents 478e657 + ab560ba
commit b107b23
Show file tree

Hide file tree

Showing 4 changed files with 89 additions and 20 deletions.
diff --git a/docs/EN_US/ECLLanguageReference/ECLR_mods/BltInFunc-IMPORT.xml b/docs/EN_US/ECLLanguageReference/ECLR_mods/BltInFunc-IMPORT.xml
@@ -6,10 +6,10 @@
 
   <para><emphasis>resulttype funcname</emphasis> <emphasis
   role="bold">(</emphasis> <emphasis>parameterlist</emphasis> <emphasis
-  role="bold">) := IMPORT(<indexterm>
-      <primary>IMPORT function</primary>
-    </indexterm></emphasis> <emphasis>language, function </emphasis><emphasis
-  role="bold">);</emphasis></para>
+  role="bold">) := IMPORT(</emphasis> <emphasis>language, function</emphasis>
+  <emphasis role="bold">[:TIME</emphasis>
+  [(<emphasis>label</emphasis>)]<emphasis role="bold"> ]</emphasis><emphasis
+  role="bold">)</emphasis>;</para>
 
   <informaltable colsep="1" frame="all" rowsep="1">
     <tgroup cols="2">
@@ -55,6 +55,20 @@
           <entry>A string constant containing the name of the function to
           include.</entry>
         </row>
+
+        <row>
+          <entry><emphasis role="bold">TIME</emphasis></entry>
+
+          <entry>Tracks timing of an external function call or embedded source
+          code and reports them back as metrics to the user.</entry>
+        </row>
+
+        <row>
+          <entry><emphasis>label</emphasis></entry>
+
+          <entry>Optional. A string constant containing the name to associate
+          with the timer. If omitted, the default is used.</entry>
+        </row>
       </tbody>
     </tgroup>
   </informaltable>
@@ -72,12 +86,9 @@
 
   <para>Example:</para>
 
-  <programlisting lang="mixed" role="NOTrunnable">IMPORT Python3 AS Python;
-// This example illustrates scalar parameters and resuls
-integer add1(integer val) := EMBED(Python)
-  val+1
-ENDEMBED;
-add1(27); //returns 28
+  <programlisting lang="mixed" role="NOTrunnable">IMPORT JAVA;
+INTEGER jadd(INTEGER a, INTEGER b) := IMPORT(java, 'JavaCat.add:(II)I': TIME('MyTime'));
+jadd (22,23);
 </programlisting>
 
   <para>See Also: <link linkend="IMPORT">IMPORT</link>, <link

diff --git a/docs/EN_US/ECLLanguageReference/ECLR_mods/ExtrSvcs-ExternalServicesImpl.xml b/docs/EN_US/ECLLanguageReference/ECLR_mods/ExtrSvcs-ExternalServicesImpl.xml
@@ -222,6 +222,21 @@
               <entry>Internal use, only. Indicates the function is actually a
               method of the internal code context.</entry>
             </row>
+
+            <row>
+              <entry>TIME</entry>
+
+              <entry>Tracks timing of the external function call and reports
+              them back as metrics to the user.</entry>
+            </row>
+
+            <row>
+              <entry><emphasis>label</emphasis></entry>
+
+              <entry>Optional. A string constant containing the name to
+              associate with the timer. If omitted, the default is
+              used.</entry>
+            </row>
           </tbody>
         </tgroup>
       </informaltable></para>

diff --git a/docs/EN_US/ECLLanguageReference/ECLR_mods/ExtrSvcs-SERVICEStructure.xml b/docs/EN_US/ECLLanguageReference/ECLR_mods/ExtrSvcs-SERVICEStructure.xml
@@ -8,7 +8,8 @@
 
   <para><emphasis>servicename </emphasis><emphasis role="bold">:= SERVICE [ :
   </emphasis><emphasis>defaultkeywords</emphasis><emphasis role="bold">
-  ]</emphasis><emphasis role="bold"> </emphasis><emphasis></emphasis></para>
+  [,TIME[(</emphasis><emphasis>label<emphasis
+  role="bold">)]]]</emphasis></emphasis></para>
 
   <para><emphasis> prototype </emphasis>:
   <emphasis>keywordlist</emphasis>;<emphasis role="bold"> </emphasis></para>
@@ -37,6 +38,20 @@
             service.</entry>
           </row>
 
+          <row>
+            <entry><emphasis role="bold">TIME</emphasis></entry>
+
+            <entry>Tracks timing of all function calls in the SERVICE
+            structure and reports them back as metrics to the user. </entry>
+          </row>
+
+          <row>
+            <entry><emphasis>label</emphasis></entry>
+
+            <entry>Optional. A string constant containing the name to
+            associate with the timer. If omitted, the default is used.</entry>
+          </row>
+
           <row>
             <entry><emphasis>prototype</emphasis></entry>
 
@@ -62,7 +77,7 @@
 
   <para>Example:</para>
 
-  <programlisting>  email := SERVICE
+  <programlisting>  email := SERVICE :TIME('MyTime')
     simpleSend( STRING address,
             STRING template,
             STRING subject) : LIBRARY='ecl2cw',
@@ -122,5 +137,6 @@
   END;
 </programlisting>
 
-  <para>See Also: <link linkend="External_Service_Implementation">External Service Implementation</link>, <link linkend="CONST">CONST</link></para>
+  <para>See Also: <link linkend="External_Service_Implementation">External
+  Service Implementation</link>, <link linkend="CONST">CONST</link></para>
 </sect1>
diff --git a/docs/EN_US/ECLLanguageReference/ECLR_mods/SpecStruc-EMBED.xml b/docs/EN_US/ECLLanguageReference/ECLR_mods/SpecStruc-EMBED.xml
@@ -11,18 +11,24 @@
   role="bold">) := EMBED(<indexterm>
       <primary>EMBED</primary>
     </indexterm></emphasis> <emphasis>language</emphasis> <emphasis
-  role="bold">)</emphasis></para>
+  role="bold">[:TIME</emphasis> [(<emphasis>label</emphasis>)]<emphasis
+  role="bold">]</emphasis></para>
 
-  <para><emphasis>code</emphasis></para>
+  <para><emphasis> code</emphasis></para>
 
   <para><emphasis role="bold">ENDEMBED<indexterm>
       <primary>ENDEMBED</primary>
     </indexterm>;</emphasis></para>
 
+  <para><emphasis role="bold"></emphasis></para>
+
   <para><emphasis>resulttype funcname</emphasis> <emphasis
   role="bold">(</emphasis> <emphasis>parameterlist</emphasis> <emphasis
   role="bold">) := EMBED(</emphasis> <emphasis>language, code</emphasis>
-  <emphasis role="bold">);</emphasis></para>
+  <emphasis role="bold">[: TIME</emphasis>
+  [(<emphasis>label</emphasis>)]<emphasis role="bold">]); </emphasis></para>
+
+  <para><emphasis role="bold"></emphasis></para>
 
   <informaltable colsep="1" frame="all" rowsep="1">
     <tgroup cols="2">
@@ -66,6 +72,20 @@
 
           <entry>The source code to embed.</entry>
         </row>
+
+        <row>
+          <entry><emphasis role="bold">TIME</emphasis></entry>
+
+          <entry>Tracks timing of an external function call or embedded source
+          code and reports them back as metrics to the user.</entry>
+        </row>
+
+        <row>
+          <entry><emphasis>label</emphasis></entry>
+
+          <entry>Optional. A string constant containing the name to associate
+          with the timer. If omitted, the default is used.</entry>
+        </row>
       </tbody>
     </tgroup>
   </informaltable>
@@ -104,21 +124,28 @@ ENDEMBED</programlisting></para>
   corruption and/or security issues, so great care and forethought are
   advised--consult with Technical Support before using.</emphasis></para>
 
-  <para>Example:</para>
+  <para>Examples:</para>
 
   <programlisting lang="ECL">//First form: a structure
 IMPORT Python3 AS Python;  //make Python language available
 
-INTEGER addone(INTEGER p) := EMBED(Python)
+INTEGER addone(INTEGER p) := EMBED(Python :TIME('MyTime'))
 # Python code that returns one more than the value passed to it
 if p &lt; 10:
   return p+1
 else:
   return 0
 ENDEMBED;
+addone(3);
+addone(11);
+</programlisting>
+
+  <para></para>
 
-//Second form: a function
-INTEGER addtwo(INTEGER p) := EMBED(Python, 'p+2');  </programlisting>
+  <programlisting>//Second form: a function
+IMPORT Python3 as Python;
+INTEGER addtwo(INTEGER p) := EMBED(Python, 'p+2' : TIME('MyTime'));  
+addtwo(27);</programlisting>
 
   <para>See Also: <link linkend="BEGINCplus_Structure">BEGINC++
   Structure</link>, <link linkend="IMPORT">IMPORT</link>, <link