/*
 * task.h -- worker task management
 *
 * Copyright (c) 2021-2022 David Demelier <markand@malikania.fr>
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#ifndef SCIWORKERD_TASK_H
#define SCIWORKERD_TASK_H

/**
 * \file task.h
 * \brief Worker task management.
 */

#include <sys/types.h>

struct pollfd;
struct task;

/**
 * \brief Task status.
 */
enum taskstatus {
	TASKSTATUS_PENDING,     /*!< not started yet. */
	TASKSTATUS_RUNNING,     /*!< currently running. */
	TASKSTATUS_EXITED,      /*!< process exited normally. */
	TASKSTATUS_KILLED       /*!< process killed killed. */
};

/**
 * \brief Task termination code.
 */
struct taskcode {
	int exitcode;           /*!< Normal exit code (if sigcode == 0). */
	int sigcode;            /*!< Signal termination code (exitcode == 0). */
};

/**
 * Construct a new task with the given tag.
 *
 * The task is just initialized, you need to call setup and start before
 * continuing
 *
 * \pre tag != NULL
 * \param tag the task tag
 * \return a new initialized task
 */
struct task *
task_new(const char *tag);

/**
 * Create a temporary file containing the script code to execute for this task.
 *
 * \pre self != NULL
 * \pre script != NULL
 * \param self the task object
 * \param script the script code to execute
 * \return 0 on success or -1 on error
 */
int
task_setup(struct task *self, const char *script);

/**
 * Fork the process to start the task.
 *
 * \pre self != NULL
 * \param self the task object
 * \return the child PID on success or -1 on error
 */
pid_t
task_start(struct task *self);

/**
 * Wait for the task to complete.
 *
 * You should usually call this function when you're sure that the task is over
 * otherwise it would block until it's complete.
 *
 * \pre self != NULL
 * \param self the task object
 * \return 0 on success or -1 one error
 */
int
task_wait(struct task *self);

/**
 * Send a termination signal to the task.
 *
 * \pre self != NULL
 * \param self the task object
 * \return 0 on success or -1 one error
 */
int
task_kill(struct task *self);

/**
 * Prepare the pollfd structure with the task pipe.
 *
 * \pre self != NULL
 * \param self the task object
 * \param fd the pollfd structure to fill
 */
void
task_prepare(struct task *self, struct pollfd *fd);

/**
 * Synchronize the child output.
 *
 * The following return values are possible:
 *
 * == 0: child exited
 * >= 0: data has been received, keep going
 *  < 0: I/O error, you should kill and wait
 *
 * \pre self != NULL
 * \param self the task object
 * \param fd the pollfd structure result
 * \return various condition as described
 */
int
task_sync(struct task *self, const struct pollfd *fd);

/**
 * Tells when the task has been started.
 *
 * \pre self != NULL
 * \param self the task object
 */
time_t
task_uptime(const struct task *self);

/**
 * Returns the task PID.
 *
 * \pre self != NULL
 * \param self the task object
 * \return the task PID
 * \warning the task must be running
 */
pid_t
task_pid(const struct task *self);

/**
 * Return the task console output.
 *
 * \pre self != NULL
 * \param self the task object
 * \return the console output or NULL if none
 */
const char *
task_console(const struct task *self);

/**
 * Get the task status.
 *
 * \pre self != NULL
 * \param self the task object
 * \return the current task status
 */
enum taskstatus
task_status(const struct task *self);

/**
 * Get the task exit or signal code
 *
 * \pre self != NULL
 * \param self the task object
 * \return the task exit/signal codes
 */
struct taskcode
task_code(const struct task *self);

/**
 * Free the task and its resources.
 *
 * \pre self != NULL
 * \param self the task object
 * \warning the task must not be running
 */
void
task_free(struct task *self);

#endif /* !SCIWORKERD_TASK_H */