Luna/libos/include/os/Process.h

/**
 * @file Process.h
 * @author apio (cloudapio.eu)
 * @brief Functions to manipulate processes.
 *
 * @copyright Copyright (c) 2023, the Luna authors.
 *
 */

#pragma once
#include <luna/Result.h>
#include <luna/String.h>
#include <sys/types.h>
#include <sys/wait.h>

namespace os
{
    /**
     * @brief An object representing a process.
     */
    class Process
    {
      public:
        /**
         * @brief Create a new process, which is an identical copy of the current one.
         *
         * @return Result<pid_t> The child's process ID in the parent process, and 0 in the child process.
         */
        static Result<pid_t> fork();

        /**
         * @brief Replace the current process's executable with another one.
         *
         * @param path The new executable's path.
         * @param args The argument list to pass to the new executable.
         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
         * @return Result<void> Always an error, as this function does not return on success.
         */
        static Result<void> exec(StringView path, Slice<String> args, bool search_in_path = true);

        /**
         * @brief Replace the current process's executable with another one.
         *
         * @param path The new executable's path.
         * @param args The argument list to pass to the new executable.
         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
         * @return Result<void> Always an error, as this function does not return on success.
         */
        static Result<void> exec(StringView path, Slice<StringView> args, bool search_in_path = true);

        /**
         * @brief Replace the current process's executable with another one.
         *
         * @param path The new executable's path.
         * @param args The argument list to pass to the new executable.
         * @param env The environment to pass to the new executable, instead of the current environment.
         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
         * @return Result<void> Always an error, as this function does not return on success.
         */
        static Result<void> exec(StringView path, Slice<String> args, Slice<String> env, bool search_in_path = true);

        /**
         * @brief Spawn a new process from an executable file.
         *
         * @param path The new executable's path.
         * @param args The argument list to pass to the new process.
         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
         * @return Result<pid_t> An error, or the process ID of the new process.
         */
        static Result<pid_t> spawn(StringView path, Slice<String> args, bool search_in_path = true);

        /**
         * @brief Spawn a new process from an executable file.
         *
         * @param path The new executable's path.
         * @param args The argument list to pass to the new process.
         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
         * @return Result<pid_t> An error, or the process ID of the new process.
         */
        static Result<pid_t> spawn(StringView path, Slice<StringView> args, bool search_in_path = true);

        /**
         * @brief Spawn a new process from an executable file.
         *
         * @param path The new executable's path.
         * @param args The argument list to pass to the new process.
         * @param env The environment to pass to the new process, instead of the current environment.
         * @param search_in_path Determines whether to search in the system binary directories if path is just a name.
         * @return Result<pid_t> An error, or the process ID of the new process.
         */
        static Result<pid_t> spawn(StringView path, Slice<String> args, Slice<String> env, bool search_in_path = true);

        // To use as the child argument to wait() to wait for any child.
        static constexpr pid_t ANY_CHILD = -1;

        /**
         * @brief Wait for a child process to finish running.
         *
         * @param child The process ID of the child process, or ANY_CHILD to wait for any child.
         * @param status The child's exit status will be stored here. If you don't want it, use nullptr.
         * @param options Options to pass to waitpid(2).
         * @return Result<pid_t> The process ID of the child process that was waited for (may not be the same as the
         * child argument if ANY_CHILD was passed).
         */
        static Result<pid_t> wait(pid_t child, int* status, int options = 0);

        /**
         * @brief Send a signal to a process.
         *
         * @param pid The process ID of the process.
         * @param signo The signal number to send. Can be 0 to simply test for a process's existence.
         * @return Result<void> Whether the function succeeded.
         */
        static Result<void> kill(pid_t pid, int signo);

        /**
         * @brief Exit the current process.
         *
         * @param status The exit status code to return to the parent.
         */
        [[noreturn]] static void exit(int status);
    };
}