WIP: Add a process manager "class"

In many places there's a need to keep track of sub-processes
spawned by the main process. Such processes need to be looked up
by various parameters, interacted with, and, eventually,
terminated.

Having a common, reliable and fast implementation with high test
coverage that holds the various pieces of information about
sub-processes together is beneficial.

Ticket: CFE-3572
Changelog: None

Author: vpodzime

libutils/proc_manager.h

@@ -0,0 +1,123 @@
+/*
+  Copyright 2021 Northern.tech AS
+
+  This file is part of CFEngine 3 - written and maintained by Northern.tech AS.
+
+  This program is free software; you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by the
+  Free Software Foundation; version 3.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
+
+  To the extent this program is licensed as part of the Enterprise
+  versions of CFEngine, the applicable Commercial Open Source License
+  (COSL) may apply to this file if you as a licensee so wish it. See
+  included file COSL.txt.
+*/
+
+#ifndef CFENGINE_PROC_MANAGER_H
+#define CFENGINE_PROC_MANAGER_H
+
+#include <sys/types.h>
+
+/**
+ * Struct to hold information about a subprocess.
+ */
+struct _Subprocess {
+    char *id;             /** unique ID of the subprocess                  [always not %NULL] */
+    char *cmd;            /** command used to create the subprocess        [can be %NULL] */
+    char *description;    /** human-friendly description of the subprocess [can be %NULL] */
+    pid_t pid;            /** PID of the subprocess                        [always >= 0] */
+    int in_fd;            /** FD of the input to the subprocess            [-1 if N/A] */
+    int out_fd;           /** FD of the output from the subprocess         [-1 if N/A] */
+    char lookup_fd;       /** which FD to use for lookup by FD             ['i', 'o' or '\0'] */
+};
+typedef struct _Subprocess Subprocess;
+
+/**
+ * Destroy a subprocess.
+ */
+void SubprocessDestroy(Subprocess *proc);
+
+typedef struct _ProcManager ProcManager;
+
+/**
+ * Function to terminate a subprocess.
+ *
+ * @param subprocess_pid PID of the subprocess to terminate
+ * @param in_fd          FD of the input to the subprocess
+ * @param out_fd         FD of the output from the subprocess
+ * @param data           custom data passed to the function through the termination functions
+ * @return               whether the termination was successful or not
+ */
+typedef bool (*ProcessTerminator) (pid_t subprocess_pid, int in_fd, int out_fd, void *data);
+
+/**
+ * Get a new ProcManager.
+ */
+ProcManager *ProcManagerNew();
+
+/**
+ * Destroy a ProcManager.
+ */
+void ProcManagerDestroy();
+
+/**
+ * Add a subprocess to a ProcManager.
+ *
+ * @param manager     the ProcManager to add the process to        [cannot be %NULL]
+ * @param id          ID of the process to add                     [string(pid) is used if %NULL]
+ * @param cmd         command used to create the subprocess        [can be %NULL]
+ * @param description human-friendly description of the subprocess [can be %NULL]
+ * @param pid         PID of the subprocess                        [required to be >=0]
+ * @param in_fd       FD of the input to the subprocess            [-1 if N/A]
+ * @param out_fd      FD of the output from the subprocess         [-1 if N/A]
+ * @param lookup_fd   which FD to use for lookup by FD             ['i', 'o' or '\0']
+ *
+ * @note Ownership of #id, #cmd and #description is transferred to the #manager.
+ */
+bool ProcManagerAddProcess(ProcManager *manager,
+                           char *id, char *cmd, char *description,
+                           pid_t pid, int in_fd, int out_fd, char lookup_fd);
+
+/**
+ * Getter functions for #ProcManager.
+ */
+Subprocess *ProcManagerGetProcessByPID(ProcManager *manager, pid_t pid);
+Subprocess *ProcManagerGetProcessById(ProcManager *manager, const char *id);
+Subprocess *ProcManagerGetProcessByFD(ProcManager *manager, int fd);
+
+/**
+ * Functions to get and remove subprocesses from a #ProcManager.
+ *
+ * @note Destroy the returned #Subprocess with SubprocessDestroy().
+ */
+Subprocess *ProcManagerPopProcessByPID(ProcManager *manager, pid_t pid);
+Subprocess *ProcManagerPopProcessById(ProcManager *manager, const char *id);
+Subprocess *ProcManagerPopProcessByFD(ProcManager *manager, int fd);
+
+/**
+ * Termination functions for ProcManager.
+ *
+ * @param data            arbitrary data passed to the #terminator function
+ *
+ * If the #terminator function returns %false, the default hard termination is
+ * attempted (closing FDs and doing kill -9). Once the subprocess is terminated,
+ * or the hard termination is attempted, the subprocess is removed from the
+ * #ProcManager.
+ */
+bool ProcManagerTerminateProcessById(ProcManager *manager, const char *id,
+                                     ProcessTerminator *terminator, void *data);
+bool ProcManagerTerminateProcessByFD(ProcManager *manager, int fd,
+                                     ProcessTerminator *terminator, void *data);
+bool ProcManagerTerminateAllProcesses(ProcManager *manager,
+                                      ProcessTerminator *terminator, void *data);
+
+#endif  /* CFENGINE_PROC_MANAGER_H */