289 lines
7 KiB
C
289 lines
7 KiB
C
/******************************************************************************
|
|
* @file background_task.h
|
|
* @brief Tâche générique exécutée en arrière-plan.
|
|
******************************************************************************/
|
|
|
|
#ifndef LABFY_INVESTIGATION_BACKGROUND_TASK_H
|
|
#define LABFY_INVESTIGATION_BACKGROUND_TASK_H
|
|
|
|
#include <gio/gio.h>
|
|
|
|
/**
|
|
* @brief Représentation opaque d'une tâche asynchrone.
|
|
*/
|
|
typedef struct BackgroundTask BackgroundTask;
|
|
|
|
/**
|
|
* @brief États possibles d'une tâche.
|
|
*/
|
|
typedef enum
|
|
{
|
|
BACKGROUND_TASK_STATE_PENDING,
|
|
BACKGROUND_TASK_STATE_RUNNING,
|
|
BACKGROUND_TASK_STATE_COMPLETED,
|
|
BACKGROUND_TASK_STATE_FAILED,
|
|
BACKGROUND_TASK_STATE_CANCELLED
|
|
} BackgroundTaskState;
|
|
|
|
/**
|
|
* @brief Codes d'erreur propres au module BackgroundTask.
|
|
*/
|
|
typedef enum
|
|
{
|
|
BACKGROUND_TASK_ERROR_INVALID_ARGUMENT,
|
|
BACKGROUND_TASK_ERROR_ALREADY_STARTED,
|
|
BACKGROUND_TASK_ERROR_WORKER_PROTOCOL
|
|
} BackgroundTaskError;
|
|
|
|
/**
|
|
* @brief Domaine d'erreur du module BackgroundTask.
|
|
*/
|
|
#define BACKGROUND_TASK_ERROR \
|
|
background_task_error_quark()
|
|
|
|
/**
|
|
* @brief Fonction exécutée dans un thread secondaire.
|
|
*
|
|
* En cas de succès, la fonction retourne TRUE et peut placer un résultat
|
|
* dans result.
|
|
*
|
|
* En cas d'échec, elle retourne FALSE et renseigne normalement error.
|
|
*
|
|
* @param task Tâche en cours d'exécution.
|
|
* @param cancellable Objet d'annulation associé à la tâche.
|
|
* @param worker_data Données privées du worker.
|
|
* @param result Emplacement recevant le résultat alloué.
|
|
* @param error Emplacement recevant une erreur.
|
|
*
|
|
* @return TRUE en cas de succès, sinon FALSE.
|
|
*/
|
|
typedef gboolean (*BackgroundTaskWorker)(
|
|
BackgroundTask *task,
|
|
GCancellable *cancellable,
|
|
gpointer worker_data,
|
|
gpointer *result,
|
|
GError **error
|
|
);
|
|
|
|
/**
|
|
* @brief Callback appelé lorsque la tâche est terminée.
|
|
*
|
|
* Ce callback est appelé après la mise à jour de l'état final.
|
|
*
|
|
* @param task Tâche terminée.
|
|
* @param user_data Données privées du callback.
|
|
*/
|
|
typedef void (*BackgroundTaskCompletionCallback)(
|
|
BackgroundTask *task,
|
|
gpointer user_data
|
|
);
|
|
|
|
/**
|
|
* @brief Retourne le domaine d'erreur du module.
|
|
*
|
|
* @return Quark GLib du domaine d'erreur.
|
|
*/
|
|
GQuark background_task_error_quark(void);
|
|
|
|
/**
|
|
* @brief Crée une nouvelle tâche en attente.
|
|
*
|
|
* @param title Titre non vide de la tâche.
|
|
*
|
|
* @return Nouvelle tâche, ou NULL si le titre est invalide.
|
|
*/
|
|
BackgroundTask *background_task_new(
|
|
const char *title
|
|
);
|
|
|
|
/**
|
|
* @brief Ajoute une référence à une tâche.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return La tâche fournie, ou NULL.
|
|
*/
|
|
BackgroundTask *background_task_ref(
|
|
BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Libère une référence à une tâche.
|
|
*
|
|
* La fonction accepte task == NULL.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*/
|
|
void background_task_unref(
|
|
BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Démarre l'exécution asynchrone d'une tâche.
|
|
*
|
|
* Si le démarrage réussit, la tâche devient propriétaire de worker_data
|
|
* et completion_data.
|
|
*
|
|
* Si le démarrage échoue, l'appelant conserve leur propriété.
|
|
*
|
|
* Le futur résultat produit par le worker sera détruit avec
|
|
* result_destroy lors de la destruction de la tâche.
|
|
*
|
|
* @param task Tâche à démarrer.
|
|
* @param worker Fonction exécutée dans un thread secondaire.
|
|
* @param worker_data Données transmises au worker.
|
|
* @param worker_data_destroy Fonction de destruction de worker_data.
|
|
* @param result_destroy Fonction de destruction du futur résultat.
|
|
* @param completion_callback Callback final facultatif.
|
|
* @param completion_data Données transmises au callback final.
|
|
* @param completion_data_destroy Fonction de destruction associée.
|
|
* @param error Emplacement facultatif recevant une erreur.
|
|
*
|
|
* @return TRUE si la tâche a été lancée, sinon FALSE.
|
|
*/
|
|
gboolean background_task_start(
|
|
BackgroundTask *task,
|
|
BackgroundTaskWorker worker,
|
|
gpointer worker_data,
|
|
GDestroyNotify worker_data_destroy,
|
|
GDestroyNotify result_destroy,
|
|
BackgroundTaskCompletionCallback completion_callback,
|
|
gpointer completion_data,
|
|
GDestroyNotify completion_data_destroy,
|
|
GError **error
|
|
);
|
|
|
|
/**
|
|
* @brief Demande l'annulation coopérative de la tâche.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*/
|
|
void background_task_cancel(
|
|
BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Indique si une annulation a été demandée.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return TRUE si l'annulation a été demandée, sinon FALSE.
|
|
*/
|
|
gboolean background_task_is_cancelled(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Met à jour la progression d'une tâche en cours.
|
|
*
|
|
* La progression est automatiquement limitée à l'intervalle
|
|
* compris entre 0.0 et 1.0.
|
|
*
|
|
* @param task Tâche concernée.
|
|
* @param progress Nouvelle progression.
|
|
* @param status_message Message facultatif, copié par le module.
|
|
*/
|
|
void background_task_report_progress(
|
|
BackgroundTask *task,
|
|
double progress,
|
|
const char *status_message
|
|
);
|
|
|
|
/**
|
|
* @brief Retourne le titre immuable d'une tâche.
|
|
*
|
|
* Le pointeur retourné est emprunté.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return Titre de la tâche, ou NULL.
|
|
*/
|
|
const char *background_task_get_title(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Retourne l'état courant d'une tâche.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return État courant de la tâche.
|
|
*/
|
|
BackgroundTaskState background_task_get_state(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Retourne la progression courante.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return Progression comprise entre 0.0 et 1.0.
|
|
*/
|
|
double background_task_get_progress(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Copie le message de progression courant.
|
|
*
|
|
* L'appelant doit libérer la chaîne avec g_free().
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return Nouvelle chaîne, ou NULL.
|
|
*/
|
|
char *background_task_dup_status_message(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Retourne la date de démarrage monotone en microsecondes.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return Date de démarrage, ou 0 si la tâche n'a pas démarré.
|
|
*/
|
|
gint64 background_task_get_started_at_us(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Retourne la date de fin monotone en microsecondes.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return Date de fin, ou 0 si la tâche n'est pas terminée.
|
|
*/
|
|
gint64 background_task_get_finished_at_us(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Retourne une copie de l'erreur finale.
|
|
*
|
|
* L'appelant doit libérer l'erreur avec g_error_free().
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return Nouvelle copie de l'erreur, ou NULL.
|
|
*/
|
|
GError *background_task_dup_error(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
/**
|
|
* @brief Retourne le résultat final de la tâche.
|
|
*
|
|
* Le pointeur retourné est emprunté et ne doit pas être libéré.
|
|
* Il n'est exploitable qu'après l'état BACKGROUND_TASK_STATE_COMPLETED.
|
|
*
|
|
* @param task Tâche concernée.
|
|
*
|
|
* @return Résultat final, ou NULL.
|
|
*/
|
|
gpointer background_task_get_result(
|
|
const BackgroundTask *task
|
|
);
|
|
|
|
#endif
|