From b62ab817c64daaf6873b83a7b083146415f51b23 Mon Sep 17 00:00:00 2001
From: Andrew Johnson <anj@aps.anl.gov>
Date: Tue, 31 Dec 2019 22:21:03 -0600
Subject: [PATCH] Replace EPICS::IOC->kill() with exit() and close() methods

---
 modules/database/src/tools/EPICS/IOC.pm  | 61 ++++++++++++++++--------
 modules/database/test/std/rec/netget.plt |  6 +--
 2 files changed, 43 insertions(+), 24 deletions(-)

diff --git a/modules/database/src/tools/EPICS/IOC.pm b/modules/database/src/tools/EPICS/IOC.pm
index 1cdae3d14..157aea0ca 100644
--- a/modules/database/src/tools/EPICS/IOC.pm
+++ b/modules/database/src/tools/EPICS/IOC.pm
@@ -29,7 +29,7 @@ EPICS::IOC - Manage an EPICS IOC
     my @records = $ioc->dbl;
     my @values = map { $ioc->dbgf($_); } @records;
 
-    $ioc->kill;
+    $ioc->exit;
 
 =head1 DESCRIPTION
 
@@ -58,7 +58,8 @@ use IO::Select;
 
 Calling C<new> creates an C<EPICS::IOC> object that can be used to start and
 interact with a single IOC. After this IOC has been shut down (by calling its
-C<kill> method) the C<EPICS::IOC> object may be reused for another IOC.
+C<exit> or C<close> methods) the C<EPICS::IOC> object may be reused for another
+IOC.
 
 =back
 
@@ -162,9 +163,9 @@ sub pid {
 
 =item started ()
 
-Returns a true value if the IOC has been started and not yet killed. This state
-will not change if the IOC dies by itself, it indicates that the start method
-has been called without the kill method.
+Returns a true value if the IOC has been started and not yet closed. This state
+will not change if the IOC dies by itself, it indicates that the C<start>
+method has been called but not the C<close> method.
 
 =cut
 
@@ -253,7 +254,7 @@ sub _getlines {
 =item _geterrors ( )
 
 Returns a list of lines output by the IOC to stderr since last called. Only
-complete lines are included, and trailing newlines have been removed.
+complete lines are included, with trailing newline char's removed.
 
 NOTE: This doesn't work on Windows because it uses select which Perl doesn't
 support on that OS, but it doesn't seem to cause any problems for short-lived
@@ -324,25 +325,43 @@ sub cmd {
     return @response;
 }
 
-=item kill ()
+=item exit ()
 
-The C<kill> method attempts to stop an IOC that is still running in several
-ways. First it sends an C<exit> command to the IOC shell. Next it closes the
-IOC's stdin stream which will trigger an end-of-file on that stream, and it
-fetches any remaining lines from the IOC's stdout stream before closing both
-that and the stderr stream. Finally (unless running on MS-Windows) it sends a
-SIGTERM signal to the child process and waits for it to clean up.
+The C<exit> method attempts to stop and clean up after an IOC that is still
+running. It sends an C<exit> command to the IOC shell (without waiting for a
+response), then calls the C<close> method to finish the task of shutting down
+the IOC process and tidying up after it.
 
 =cut
 
-sub kill {
-    my $self = shift;
+sub exit {
+    my $self = $_[0];
 
     return ()
         unless $self->started;
 
     $self->_send("exit\n"); # Don't wait
 
+    goto &close;
+}
+
+=item close ()
+
+The C<close> method first closes the IOC's stdin stream, which will trigger an
+end-of-file to the IOC shell, then it fetches any remaining lines from the
+IOC's stdout stream before closing both that and the stderr stream. Finally
+(unless we're running on MS-Windows) it sends a SIGTERM signal to the child
+process and waits for it to clean up. A list containing the final output from
+the IOC's stdout stream is returned.
+
+=cut
+
+sub close {
+    my $self = shift;
+
+    return ()
+        unless $self->started;
+
     close $self->{stdin};
     $self->{stdin} = gensym;
 
@@ -354,7 +373,7 @@ sub kill {
     close $self->{stderr};
     $self->{stderr} = gensym;
 
-    if ($^O ne "MSWin32") {
+    if ($^O ne 'MSWin32') {
         kill 'TERM', $self->{pid};
         waitpid $self->{pid}, 0;
     }
@@ -365,15 +384,15 @@ sub kill {
 
 =item DESTROY ()
 
-C<EPICS::IOC> objects have a destructor which calls the C<kill> method, but it
-is not recommended that this be relied on to terminate an IOC process. Better to
-use an C<END {}> block and/or trap the necessary signals to explicitly kill the
-IOC.
+C<EPICS::IOC> objects have a destructor which calls the C<exit> method, but it
+is not recommended that this be relied on to terminate an IOC process. Better
+to use an C<END {}> block and/or trap the necessary signals and explicitly
+C<exit> or C<close> the IOC.
 
 =cut
 
 sub DESTROY {
-    shift->kill;
+    shift->exit;
 }
 
 
diff --git a/modules/database/test/std/rec/netget.plt b/modules/database/test/std/rec/netget.plt
index fcc75442e..f050aa5c6 100644
--- a/modules/database/test/std/rec/netget.plt
+++ b/modules/database/test/std/rec/netget.plt
@@ -31,7 +31,7 @@ my $ioc = EPICS::IOC->new();
 $ioc->debug(1);
 
 $SIG{__DIE__} = $SIG{INT} = $SIG{QUIT} = sub {
-    $ioc->kill;
+    $ioc->exit;
     BAIL_OUT('Caught signal');
 };
 
@@ -41,7 +41,7 @@ $SIG{__DIE__} = $SIG{INT} = $SIG{QUIT} = sub {
 sub kill_bail {
     my $doing = shift;
     return sub {
-        $ioc->kill;
+        $ioc->exit;
         BAIL_OUT("Timeout $doing");
     }
 }
@@ -137,4 +137,4 @@ SKIP: {
     } 10, kill_bail('doing pvget');
 }
 
-$ioc->kill;
+$ioc->exit;