jobs.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2009-2010, 2014 johannes hanika.
    Copyright (C) 2010 Henrik Andersson.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2014, 2016 Tobias Ellinghaus.
    Copyright (C) 2015 Bruce Guenter.
    Copyright (C) 2015-2016 Roman Lebedev.
    Copyright (C) 2019 Edgardo Hoszowski.
    Copyright (C) 2020 Hanno Schwalm.
    Copyright (C) 2020 Pascal Obry.
    Copyright (C) 2022, 2025-2026 Aurélien PIERRE.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2026 Guillaume Stutin.
    
    darktable 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, either version 3 of the License, or
    (at your option) any later version.
    
    darktable 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 darktable.  If not, see <http://www.gnu.org/licenses/>.
*/
 
#ifndef DT_CONTROL_JOBS_H
#define DT_CONTROL_JOBS_H
 
#include <glib.h>
#include <inttypes.h>
#include <stddef.h>
 
#define DT_CONTROL_DESCRIPTION_LEN 256
// reserved workers
#define DT_CTL_WORKER_RESERVED 1
#define DT_CTL_WORKER_DARKROOM 0    // dev zoom 1
 
typedef enum dt_job_state_t
{
  DT_JOB_STATE_INITIALIZED = 0,
  DT_JOB_STATE_QUEUED,
  DT_JOB_STATE_RUNNING,
  DT_JOB_STATE_FINISHED,
  DT_JOB_STATE_CANCELLED,
  DT_JOB_STATE_DISCARDED,
  DT_JOB_STATE_DISPOSED
} dt_job_state_t;
 
typedef enum dt_job_queue_t
{
  DT_JOB_QUEUE_USER_FG = 0,     // gui actions, ...
  DT_JOB_QUEUE_SYSTEM_FG = 1,   // thumbnail creation, ..., may be pushed out of the queue
  DT_JOB_QUEUE_USER_BG = 2,     // imports, ...
  DT_JOB_QUEUE_USER_EXPORT = 3, // exports. only one of these jobs will ever be scheduled at a time
  DT_JOB_QUEUE_SYSTEM_BG = 4,   // some lua stuff that may not be pushed out of the queue, ...
  DT_JOB_QUEUE_MAX = 5
} dt_job_queue_t;
 
typedef struct _dt_job_t dt_job_t;
 
typedef int32_t (*dt_job_execute_callback)(dt_job_t *);
typedef void (*dt_job_state_change_callback)(dt_job_t *, dt_job_state_t state);
typedef void (*dt_job_destroy_callback)(void *data);
 
dt_job_t *dt_control_job_create(dt_job_execute_callback execute, const char *msg, ...) __attribute__((format(printf, 2, 3)));
void dt_control_job_dispose(dt_job_t *job);
void dt_control_job_set_state_callback(dt_job_t *job, dt_job_state_change_callback cb);
void dt_control_job_cancel(dt_job_t *job);
dt_job_state_t dt_control_job_get_state(dt_job_t *job);
void dt_control_job_wait(dt_job_t *job);
void dt_control_job_set_params(dt_job_t *job, void *params, dt_job_destroy_callback callback);
void dt_control_job_set_params_with_size(dt_job_t *job, void *params, size_t params_size,
                                         dt_job_destroy_callback callback);
void *dt_control_job_get_params(const dt_job_t *job);
 
void dt_control_job_add_progress(dt_job_t *job, const char *message, gboolean cancellable);
void dt_control_job_set_progress_message(dt_job_t *job, const char *message);
void dt_control_job_set_progress(dt_job_t *job, double value);
double dt_control_job_get_progress(dt_job_t *job);
 
struct dt_control_t;
void dt_control_jobs_init(struct dt_control_t *control);
// Cancel/dispose every still-queued job and empty the queues. MUST run while the modules that
// own job callbacks (state_changed_cb, params_destroy) are still loaded -- call it from
// dt_control_shutdown(), after the worker threads are joined but before dt_lib_cleanup() unloads
// the plug-in .so files. Otherwise a leftover job disposed at the very end (dt_control_jobs_cleanup)
// fires a callback into an unmapped library -> SIGSEGV.
void dt_control_jobs_drain(struct dt_control_t *control);
void dt_control_jobs_cleanup(struct dt_control_t *control);
 
int32_t dt_control_workers_alive(void);
 
typedef void (*dt_control_running_jobs_foreach_callback_t)(const char *description, dt_job_queue_t queue,
                                                           gboolean reserved, void *data);
 
void dt_control_running_jobs_foreach(struct dt_control_t *control,
                                     dt_control_running_jobs_foreach_callback_t callback, void *data);
 
int32_t dt_control_queued_jobs_count(struct dt_control_t *control);
 
int dt_control_add_job(struct dt_control_t *control, dt_job_queue_t queue_id, dt_job_t *job);
int32_t dt_control_add_job_res(struct dt_control_t *s, dt_job_t *job, int32_t res);
 
int32_t dt_control_get_threadid();
 
// Flush all non-running jobs queued in the queue matching the ID
void dt_control_flush_jobs_queue(struct dt_control_t *control, dt_job_queue_t queue_id);
 
/* No trailing include of the per-subsystem job headers here: each of them includes this
 * header back (for dt_job_t), which formed a 5-node include cycle. Consumers of a
 * specific job factory include the matching control/jobs header explicitly. */
 
#endif // DT_CONTROL_JOBS_H
 
// clang-format off
// modelines: These editor modelines have been set for all relevant files by tools/update_modelines.py
// vim: shiftwidth=2 expandtab tabstop=2 cindent
// kate: tab-indents: off; indent-width 2; replace-tabs on; indent-mode cstyle; remove-trailing-spaces modified;
// clang-format on