Merge pull request #43 from bodo-hugo-barwich/no-29_automated-documen…

…tation

Extend Documentation on Process::SubProcess::Group

lib/Process/SubProcess.pm

@@ -1,6 +1,6 @@
 #---------------------------------
 # @author Bodo (Hugo) Barwich
-# @version 2023-08-25
+# @version 2023-09-22
 # @package SubProcess Management
 # @subpackage Process/SubProcess.pm
 
@@ -44,7 +44,7 @@ use IO::Select;
 use IPC::Open3;
 use Symbol qw(gensym);
 
-our $VERSION = '2.1.5';
+our $VERSION = '2.1.6';
 
 =head1 DESCRIPTION
 
@@ -243,6 +243,10 @@ If the process is expected to run longer it is useful to set it to avoid excessi
 It is also important for multiple process execusions, because other processes will not
 be checked before the read has not timed out.
 
+C<debug> - show internal processing information
+
+C<quiet> - do not print any warnings or errors
+
 See L<Method C<setName()>|/"setName ( NAME )">
 
 See L<Method C<setCommand()>|/"setCommand ( COMMAND )">
@@ -1204,6 +1208,12 @@ And then checks the process with the C<Check()> method.
 It is used by the B<EXECUTIONTIMEOUT> functionality to ensure that the process does not
 run longer than required.
 
+This will include an Error Message "I<Process terminating ...>"
+and set the Process C<ERROR CODE> to C< 4 >.
+
+Enabling the C<DEBUG> option will additionally include an B<Activity Information> from
+which method C<Terminate()> was called.
+
 See L<Method C<Check()>|/"Check ()">
 
 See L<Method C<setTimeout()>|/"setTimeout ()">
@@ -1238,6 +1248,33 @@ sub Terminate {
     }       #if($self->isRunning)
 }
 
+=pod
+
+=over 4
+
+=item Kill ()
+
+This method sends a C<KILL> signal to the process if it is running.
+
+It is used by the B<EXECUTIONTIMEOUT> functionality to ensure that the process does not
+run longer than required.
+
+Any not yet read output will get lost.
+
+This will include an Error Message "I<Process killing ...>"
+and set the Process C<ERROR CODE> to C< 4 > and the C<EXIT CODE> to C< 9 >.
+
+Enabling the C<DEBUG> option will additionally include an B<Error Message> from
+which method C<Kill()> was called.
+
+See L<Method C<Check()>|/"Check ()">
+
+See L<Method C<setTimeout()>|/"setTimeout ()">
+
+=back
+
+=cut
+
 sub Kill {
     my $self   = shift;
     my $sprcnm = $self->getNameComplete;

lib/Process/SubProcess/Group.pm

@@ -1,6 +1,6 @@
 #---------------------------------
 # @author Bodo (Hugo) Barwich
-# @version 2023-08-25
+# @version 2023-09-22
 # @package SubProcess Management
 # @subpackage Process/SubProcess/Group.pm
 
@@ -58,6 +58,39 @@ in an object oriented manner.
 #----------------------------------------------------------------------------
 #Constructors
 
+=head1 CONSTRUCTOR
+
+=over 4
+
+=item new ( [ CONFIGURATIONS ] )
+
+This is the constructor for a new SubProcess.
+
+B<Parameters:>
+
+C<CONFIGURATIONS> are passed in a hash like fashion, using key and value pairs.
+
+B<Recognized Configurations:>
+
+C<check> - Time in seconds when to check a process for new output.
+This is calculated based on the count of processes to manage.
+
+C<read | readtimeout> - Time in seconds to wait for the process output.
+If the process is expected to run longer it is useful to set it to avoid excessive checks.
+It is also important for multiple process execusions, because other processes will not
+be checked before the read has not timed out.
+
+C<timeout> - Time in seconds to wait for the process to finish. After this time the process will
+be terminated
+
+C<debug> - show internal processing information
+
+C<quiet> - do not print any warnings or errors
+
+=back
+
+=cut
+
 sub new {
 
     #Take the Method Parameters
@@ -118,6 +151,10 @@ sub DESTROY {
 #----------------------------------------------------------------------------
 #Administration Methods
 
+=head1 Administration Methods
+
+=cut
+
 sub add {
     my $self = shift;
 
@@ -214,6 +251,35 @@ sub add {
     return $rsprc;
 }
 
+=pod
+
+=over 4
+
+=item setCheckInterval ( INTERVAL )
+
+This method calculates the C<READTIMEOUT> for each C<Process::SubProces> object according to
+the amount of existing objects. The value of the C<READTIMEOUT> for each Process will be rounded
+to a whole number.
+
+B<Example:>
+
+The B<Process Group> manages 3 B<Processes>. Processes "I<A>", "I<B>" and "I<C>".
+Process "I<A>" should be checked every B<6 seconds>. So, setting C<setCheckInterval(6)> will
+set the C<READTIMEOUT> of Processes "I<A>", "I<B>" and "I<C>" to B<2 seconds>.
+This way after cycling over the processes the Process "I<A>" will be checked again
+after 6 seconds.
+
+B<Parameters:>
+
+C<INTERVAL> - is an integer that specifies the interval in which each process should
+be checked.
+
+See L<Method C<Process::SubProcess::setArrProcess()>|SubProcess/"setReadTimeout ( TIMEOUT )">
+
+=back
+
+=cut
+
 sub setCheckInterval {
     my $self = shift;
 

t/test_runner.t

@@ -335,16 +335,16 @@ subtest 'Runner Plain Text Boundary' => sub {
 
 subtest 'Runner Timeout Error' => sub {
 
-  $itestpause = 3;
+  $itestpause = 5;
 
-  $srunnerresult = `$Config{perlpath} ${spath}${srunnerscript} -n "script - times out" -c "${spath}${stestscript} $itestpause" -t 2`;
+  $srunnerresult = `$Config{perlpath} ${spath}${srunnerscript} -n "script - times out" -c "${spath}${stestscript} $itestpause" -t 1`;
   $irunnerstatus = $?;
 
   print("Runner Result:\n'$srunnerresult'\n");
   print("Runner EXIT CODE: '$irunnerstatus'\n");
 
   isnt($srunnerresult, undef, "Runner Result is returned");
-  ok($irunnerstatus =~ qr/^-?\d$/, "Runner EXIT CODE is numeric");
+  ok($irunnerstatus =~ qr/^-?\d+$/, "Runner EXIT CODE is numeric");
   is($irunnerstatus, 0, "Runner EXIT CODE '0' is correct");
 
   $sscriptsummary = undef;
@@ -404,7 +404,7 @@ subtest 'Runner Exit Code' => sub {
 	  print("Runner EXIT CODE: '$irunnerstatus'\n");
 
 	  isnt($srunnerresult, undef, "Runner Result is returned");
-	  ok($irunnerstatus =~ qr/^-?\d$/, "Runner EXIT CODE is numeric");
+	  ok($irunnerstatus =~ qr/^-?\d+$/, "Runner EXIT CODE is numeric");
 	  is($irunnerstatus, $iteststatus, "Runner EXIT CODE '$iteststatus' is correct");
 
 	  $sscriptsummary = undef;
@@ -460,7 +460,7 @@ subtest 'Runner Exit Code' => sub {
     print("Runner EXIT CODE: '$irunnerstatus'\n");
 
     isnt($srunnerresult, undef, "Runner Result is returned");
-    ok($irunnerstatus =~ qr/^-?\d$/, "Runner EXIT CODE is numeric");
+    ok($irunnerstatus =~ qr/^-?\d+$/, "Runner EXIT CODE is numeric");
     is($irunnerstatus, 4, "Runner EXIT CODE '4' is correct");
 
     $sscriptsummary = undef;