✨ Add support for gracefully killing processes with specific interrupts (#685)

<!--
Copyright (C) 2020-2022 Arm Limited or its affiliates and Contributors.
All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->
### Description

<!--
Please add any detail or context that would be useful to a reviewer.
-->

Add support for gracefully killing processes with specific interrupts

### Test Coverage

<!--
Please put an `x` in the correct box e.g. `[x]` to indicate the testing
coverage of this change.
-->

- [x]  This change is covered by existing or additional automated tests.
- [ ] Manual testing has been performed (and evidence provided) as
automated testing was not feasible.
- [ ] Additional tests are not required for this change (e.g.
documentation update).

Author: joshjennings98

changes/20250821120026.feature

@@ -0,0 +1 @@
+:sparkles: `proc` Add support for gracefully killing processes with specific interrupts

utils/proc/interrupt.go

@@ -47,13 +47,29 @@ func InterruptProcess(ctx context.Context, pid int, signal InterruptType) (err e
 	return
 }
 
-// TerminateGracefullyWithChildren follows the pattern set by [kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) and terminates processes gracefully by first sending a SIGTERM and then a SIGKILL after the grace period has elapsed.
+// TerminateGracefullyWithChildren follows the pattern set by [kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) and terminates processes gracefully by first sending a SIGINT+SIGTERM and then a SIGKILL after the grace period has elapsed.
 // It does not attempt to terminate the process group. If you wish to terminate the process group directly then send -pgid to TerminateGracefully but
 // this does not guarantee that the group will be terminated gracefully.
 // Instead, this function lists each child and attempts to kill them gracefully concurrently. It will then attempt to gracefully terminate itself.
 // Due to the multi-stage process and the fact that the full grace period must pass for each stage specified above, the total maximum length of this
 // function will be 2*gracePeriod not gracePeriod.
 func TerminateGracefullyWithChildren(ctx context.Context, pid int, gracePeriod time.Duration) (err error) {
+	return terminateGracefullyWithChildren(ctx, pid, gracePeriod, TerminateGracefully)
+}
+
+// TerminateGracefullyWithChildrenWithSpecificInterrupts follows the pattern set by [kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) and terminates processes gracefully by first sending the specified interrupts and then a SIGKILL after the grace period has elapsed.
+// It does not attempt to terminate the process group. If you wish to terminate the process group directly then send -pgid to TerminateGracefully but
+// this does not guarantee that the group will be terminated gracefully.
+// Instead, this function lists each child and attempts to kill them gracefully concurrently. It will then attempt to gracefully terminate itself.
+// Due to the multi-stage process and the fact that the full grace period must pass for each stage specified above, the total maximum length of this
+// function will be 2*gracePeriod not gracePeriod.
+func TerminateGracefullyWithChildrenWithSpecificInterrupts(ctx context.Context, pid int, gracePeriod time.Duration, interrupts ...InterruptType) (err error) {
+	return terminateGracefullyWithChildren(ctx, pid, gracePeriod, func(ctx context.Context, pid int, gracePeriod time.Duration) error {
+		return TerminateGracefullyWithSpecificInterrupts(ctx, pid, gracePeriod, interrupts...)
+	})
+}
+
+func terminateGracefullyWithChildren(ctx context.Context, pid int, gracePeriod time.Duration, terminate func(context.Context, int, time.Duration) error) (err error) {
 	err = parallelisation.DetermineContextError(ctx)
 	if err != nil {
 		return
@@ -77,34 +93,39 @@ func TerminateGracefullyWithChildren(ctx context.Context, pid int, gracePeriod t
 	}
 
 	if len(children) == 0 {
-		err = TerminateGracefully(ctx, pid, gracePeriod)
+		err = terminate(ctx, pid, gracePeriod)
 		return
 	}
 
 	childGroup, terminateCtx := errgroup.WithContext(ctx)
 	childGroup.SetLimit(len(children))
 	for _, child := range children {
 		if child.IsRunning() {
-			childGroup.Go(func() error { return TerminateGracefullyWithChildren(terminateCtx, child.Pid(), gracePeriod) })
+			childGroup.Go(func() error {
+				return terminateGracefullyWithChildren(terminateCtx, child.Pid(), gracePeriod, terminate)
+			})
 		}
 	}
 	err = childGroup.Wait()
 	if err != nil {
 		return
 	}
 
-	err = TerminateGracefully(ctx, pid, gracePeriod)
+	err = terminate(ctx, pid, gracePeriod)
 	return
 }
 
-func terminateGracefully(ctx context.Context, pid int, gracePeriod time.Duration) (err error) {
-	err = InterruptProcess(ctx, pid, SigInt)
-	if err != nil {
+func terminateGracefully(ctx context.Context, pid int, gracePeriod time.Duration, interrupts ...InterruptType) (err error) {
+	if len(interrupts) == 0 {
+		err = commonerrors.New(commonerrors.ErrInvalid, "at least one interrupt must be provided")
 		return
 	}
-	err = InterruptProcess(ctx, pid, SigTerm)
-	if err != nil {
-		return
+
+	for _, interrupt := range interrupts {
+		err = InterruptProcess(ctx, pid, interrupt)
+		if err != nil {
+			return
+		}
 	}
 
 	return parallelisation.RunActionWithParallelCheck(ctx,
@@ -119,10 +140,18 @@ func terminateGracefully(ctx context.Context, pid int, gracePeriod time.Duration
 		}, 200*time.Millisecond)
 }
 
-// TerminateGracefully follows the pattern set by [kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) and terminates processes gracefully by first sending a SIGTERM and then a SIGKILL after the grace period has elapsed.
+// TerminateGracefully follows the pattern set by [kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) and terminates processes gracefully by first sending a SIGINT+SIGTERM and then a SIGKILL after the grace period has elapsed.
 func TerminateGracefully(ctx context.Context, pid int, gracePeriod time.Duration) (err error) {
 	defer func() { _ = InterruptProcess(context.Background(), pid, SigKill) }()
-	_ = terminateGracefully(ctx, pid, gracePeriod)
+	_ = terminateGracefully(ctx, pid, gracePeriod, SigInt, SigTerm)
+	err = InterruptProcess(ctx, pid, SigKill)
+	return
+}
+
+// TerminateGracefullyWithSpecificInterrupts follows the pattern set by [kubernetes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) and terminates processes gracefully by first sending the specified interrupts and then a SIGKILL after the grace period has elapsed.
+func TerminateGracefullyWithSpecificInterrupts(ctx context.Context, pid int, gracePeriod time.Duration, interrupts ...InterruptType) (err error) {
+	defer func() { _ = InterruptProcess(context.Background(), pid, SigKill) }()
+	_ = terminateGracefully(ctx, pid, gracePeriod, interrupts...)
 	err = InterruptProcess(ctx, pid, SigKill)
 	return
 }

utils/proc/interrupt_test.go

@@ -26,10 +26,22 @@ func TestTerminateGracefully(t *testing.T) {
 			name:     "TerminateGracefully",
 			testFunc: TerminateGracefully,
 		},
+		{
+			name: "TerminateGracefullyWithSpecificInterrupts",
+			testFunc: func(ctx context.Context, pid int, gracePeriod time.Duration) error {
+				return TerminateGracefullyWithSpecificInterrupts(ctx, pid, gracePeriod, SigInt)
+			},
+		},
 		{
 			name:     "TerminateGracefullyWithChildren",
 			testFunc: TerminateGracefullyWithChildren,
 		},
+		{
+			name: "TerminateGracefullyWithChildrenWithSpecificInterrupts",
+			testFunc: func(ctx context.Context, pid int, gracePeriod time.Duration) error {
+				return TerminateGracefullyWithChildrenWithSpecificInterrupts(ctx, pid, gracePeriod, SigInt)
+			},
+		},
 	} {
 		t.Run(test.name, func(t *testing.T) {
 			defer goleak.VerifyNone(t)