198 lines
5 KiB
C
198 lines
5 KiB
C
/******************************************************************************
|
||
* @file task_manager.h
|
||
* @brief Gestionnaire central des tâches exécutées en arrière-plan.
|
||
******************************************************************************/
|
||
|
||
#ifndef LABFY_INVESTIGATION_TASK_MANAGER_H
|
||
#define LABFY_INVESTIGATION_TASK_MANAGER_H
|
||
|
||
#include "core/background_task.h"
|
||
|
||
#include <glib.h>
|
||
|
||
/**
|
||
* @brief Représentation opaque du gestionnaire de tâches.
|
||
*/
|
||
typedef struct TaskManager TaskManager;
|
||
|
||
/**
|
||
* @brief Codes d’erreur du gestionnaire de tâches.
|
||
*/
|
||
typedef enum
|
||
{
|
||
TASK_MANAGER_ERROR_INVALID_ARGUMENT,
|
||
TASK_MANAGER_ERROR_ALREADY_ADDED
|
||
} TaskManagerError;
|
||
|
||
/**
|
||
* @brief Domaine d’erreur du gestionnaire de tâches.
|
||
*/
|
||
#define TASK_MANAGER_ERROR \
|
||
task_manager_error_quark()
|
||
|
||
/**
|
||
* @brief Callback appelé lorsque la collection de tâches change.
|
||
*
|
||
* Ce callback est utilisé lorsqu’une tâche est ajoutée, retirée,
|
||
* nettoyée ou lorsqu’une demande globale d’annulation est effectuée.
|
||
*
|
||
* Il est appelé sans que le mutex interne du gestionnaire soit verrouillé.
|
||
*
|
||
* @param task_manager Gestionnaire ayant changé.
|
||
* @param user_data Données associées au callback.
|
||
*/
|
||
typedef void (*TaskManagerChangedCallback)(
|
||
TaskManager *task_manager,
|
||
gpointer user_data
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne le domaine d’erreur du module.
|
||
*
|
||
* @return Quark GLib du domaine d’erreur.
|
||
*/
|
||
GQuark task_manager_error_quark(void);
|
||
|
||
/**
|
||
* @brief Crée un gestionnaire de tâches vide.
|
||
*
|
||
* @return Nouveau gestionnaire, ou NULL en cas d’échec.
|
||
*/
|
||
TaskManager *task_manager_new(void);
|
||
|
||
/**
|
||
* @brief Libère le gestionnaire et ses références sur les tâches.
|
||
*
|
||
* Cette fonction accepte task_manager == NULL.
|
||
*
|
||
* Les tâches continuent d’exister si d’autres composants possèdent
|
||
* encore leurs propres références.
|
||
*
|
||
* @param task_manager Gestionnaire à libérer.
|
||
*/
|
||
void task_manager_free(
|
||
TaskManager *task_manager
|
||
);
|
||
|
||
/**
|
||
* @brief Ajoute une tâche au gestionnaire.
|
||
*
|
||
* Le gestionnaire prend une référence supplémentaire sur la tâche.
|
||
* L’appelant conserve la propriété de sa propre référence.
|
||
*
|
||
* Une même instance de BackgroundTask ne peut pas être ajoutée deux fois.
|
||
*
|
||
* @param task_manager Gestionnaire concerné.
|
||
* @param task Tâche à ajouter.
|
||
* @param error Emplacement facultatif recevant une erreur.
|
||
*
|
||
* @return TRUE si la tâche est ajoutée, sinon FALSE.
|
||
*/
|
||
gboolean task_manager_add(
|
||
TaskManager *task_manager,
|
||
BackgroundTask *task,
|
||
GError **error
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne le nombre de tâches actuellement suivies.
|
||
*
|
||
* @param task_manager Gestionnaire concerné.
|
||
*
|
||
* @return Nombre de tâches.
|
||
*/
|
||
gsize task_manager_get_count(
|
||
const TaskManager *task_manager
|
||
);
|
||
|
||
/**
|
||
* @brief Retourne une référence vers une tâche selon son index.
|
||
*
|
||
* L’appelant doit libérer la référence retournée avec :
|
||
*
|
||
* @code
|
||
* background_task_unref(task);
|
||
* @endcode
|
||
*
|
||
* @param task_manager Gestionnaire concerné.
|
||
* @param index Index de la tâche.
|
||
*
|
||
* @return Nouvelle référence vers la tâche, ou NULL si l’index est invalide.
|
||
*/
|
||
BackgroundTask *task_manager_get_task(
|
||
const TaskManager *task_manager,
|
||
gsize index
|
||
);
|
||
|
||
/**
|
||
* @brief Retire une tâche du gestionnaire.
|
||
*
|
||
* La tâche n’est pas annulée automatiquement.
|
||
*
|
||
* La référence détenue par le gestionnaire est libérée.
|
||
*
|
||
* @param task_manager Gestionnaire concerné.
|
||
* @param task Tâche à retirer.
|
||
*
|
||
* @return TRUE si la tâche était présente et a été retirée, sinon FALSE.
|
||
*/
|
||
gboolean task_manager_remove(
|
||
TaskManager *task_manager,
|
||
BackgroundTask *task
|
||
);
|
||
|
||
/**
|
||
* @brief Retire toutes les tâches terminées.
|
||
*
|
||
* États concernés :
|
||
*
|
||
* - BACKGROUND_TASK_STATE_COMPLETED ;
|
||
* - BACKGROUND_TASK_STATE_FAILED ;
|
||
* - BACKGROUND_TASK_STATE_CANCELLED.
|
||
*
|
||
* Les tâches en attente ou en cours sont conservées.
|
||
*
|
||
* @param task_manager Gestionnaire concerné.
|
||
*
|
||
* @return Nombre de tâches retirées.
|
||
*/
|
||
gsize task_manager_remove_finished(
|
||
TaskManager *task_manager
|
||
);
|
||
|
||
/**
|
||
* @brief Demande l’annulation de toutes les tâches en cours.
|
||
*
|
||
* L’annulation reste coopérative.
|
||
*
|
||
* Les tâches ne sont pas retirées du gestionnaire.
|
||
*
|
||
* @param task_manager Gestionnaire concerné.
|
||
*/
|
||
void task_manager_cancel_all(
|
||
TaskManager *task_manager
|
||
);
|
||
|
||
/**
|
||
* @brief Définit le callback signalant un changement du gestionnaire.
|
||
*
|
||
* Le gestionnaire devient propriétaire de user_data après cet appel.
|
||
*
|
||
* Lorsqu’un nouveau callback remplace l’ancien, les anciennes données
|
||
* sont détruites avec leur fonction de destruction.
|
||
*
|
||
* Le callback peut être désactivé en fournissant callback == NULL.
|
||
*
|
||
* @param task_manager Gestionnaire concerné.
|
||
* @param callback Nouveau callback, ou NULL.
|
||
* @param user_data Données transmises au callback.
|
||
* @param user_data_destroy Fonction de destruction associée.
|
||
*/
|
||
void task_manager_set_changed_callback(
|
||
TaskManager *task_manager,
|
||
TaskManagerChangedCallback callback,
|
||
gpointer user_data,
|
||
GDestroyNotify user_data_destroy
|
||
);
|
||
|
||
#endif
|