supervisor.h

Go to the documentation of this file.

/*
    This file is part of Ansel.
    Copyright (C) 2026 Aurélien Pierre.
 
    Ansel 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.
 
    Ansel 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 Ansel.  If not, see <http://www.gnu.org/licenses/>.
*/
 
#pragma once
 
#include <glib.h>
#include <stdint.h>
 
#include "common/darktable.h"
 
struct dt_image_t;
struct dt_iop_module_t;
struct dt_develop_blend_params_t;
struct dt_masks_form_t;
 
#ifdef __cplusplus
extern "C" {
#endif
 
// CRUD verb for an event.
typedef enum dt_sv_op_t
{
  DT_SV_CREATE = 0,
  DT_SV_UPDATE,
  DT_SV_READ,
  DT_SV_DELETE,
} dt_sv_op_t;
 
// Lifecycle, called once from dt_init()/dt_cleanup().
void dt_supervisor_init(void);
void dt_supervisor_cleanup(void);
 
// Runtime capture flag, set by the GUI (the supervisor window). The supervisor
// captures events whenever this is set OR `-d supervisor` is active. Read via
// the inline gate below; set via dt_supervisor_set_recording().
extern gint dt_supervisor_recording;
 
// Fast gate. TRUE when `-d supervisor` is enabled OR the GUI is recording. Guard
// call sites with this so the per-event metadata gathering is skipped when off.
static inline gboolean dt_supervisor_active(void)
{
  return (darktable.unmuted & DT_DEBUG_SUPERVISOR) || g_atomic_int_get(&dt_supervisor_recording);
}
 
typedef struct dt_sv_link_t
{
  char label[16]; // edge name, e.g. "params", "input", "node", "rekeyed_to"
  uint64_t hash;
} dt_sv_link_t;
 
typedef struct dt_sv_logged_event_t
{
  uint64_t seq;   // monotonic capture sequence, for incremental GUI updates
  double ts;
  char thread[24];
  char op[12];
  char domain[16];
  char mnemonic[64]; // human label for the row (module, imgid, widget, pipe, …)
  char cache_name[32]; // cacheline "name" tag (e.g. "raster mask"), empty for plain module outputs
  uint64_t hash;  // the event's own object hash
  GArray *links;  // of dt_sv_link_t
  gchar *json;    // the full NDJSON record (compact), for the detail view
} dt_sv_logged_event_t;
 
// Toggle runtime capture into the in-memory log (the stderr NDJSON dump stays
// governed by `-d supervisor`).
void dt_supervisor_set_recording(gboolean on);
 
// GUI thread: deep-copy snapshot of the retained log, oldest-first. Free with
// dt_supervisor_events_free(). Empty (not NULL) when nothing was captured.
GPtrArray *dt_supervisor_events_snapshot(void);
 
// Incremental snapshot: only events captured after `after_seq` (oldest-first).
// `out_last_seq` receives the highest seq returned (or `after_seq` if none), so
// a poller can advance its cursor. Free with dt_supervisor_events_free().
GPtrArray *dt_supervisor_events_snapshot_since(uint64_t after_seq, uint64_t *out_last_seq);
 
// Number of events currently retained.
guint dt_supervisor_events_count(void);
 
void dt_supervisor_events_free(GPtrArray *events);
 
// Drop all retained events.
void dt_supervisor_events_clear(void);
 
uint64_t dt_supervisor_node_key(int pipe_type, const char *op_name, int multi_priority);
 
// Key under which thumbnail events for (imgid, mip) are registered. Lets the GUI
// memory view navigate from a mipmap cache item to its thumbnail event.
uint64_t dt_supervisor_thumbnail_key(int32_t imgid, int mip);
 
// Key under which mipmap cache objects (imgid, mip) are registered. Distinct
// from the thumbnail key; used by the GUI memory view to navigate from a mipmap
// cache item to the mipmap object's properties.
uint64_t dt_supervisor_mipmap_key(int32_t imgid, int mip);
 
// Key under which image cache objects (the canonical dt_image_t for an imgid)
// are registered. Distinct from the mipmap key.
uint64_t dt_supervisor_image_key(int32_t imgid);
 
// `module`/`params` are optional: when the module exposes introspection, the
// parameters are rendered human-legibly under "parameters" (pass NULL/NULL to skip).
// `blend_params`, when given, is rendered under "blendop" (skipped when blending
// is disabled).
void dt_supervisor_history(dt_sv_op_t op, uint64_t param_hash, const char *op_name,
                           int multi_priority, const char *multi_name, int iop_order,
                           int history_index, int32_t imgid, gboolean enabled,
                           const struct dt_iop_module_t *module, const void *params,
                           const struct dt_develop_blend_params_t *blend_params, GList *forms);
 
// Key under which a mask form is registered (by its formid).
uint64_t dt_supervisor_form_key(int formid);
 
void dt_supervisor_form(dt_sv_op_t op, const struct dt_masks_form_t *form);
 
void dt_supervisor_node(dt_sv_op_t op, uint64_t node_hash, uint64_t param_hash,
                        uint64_t predecessor_hash, const char *op_name, int multi_priority,
                        int iop_order, int pipe_type, int32_t imgid);
 
void dt_supervisor_cacheline_create(uint64_t hash, uint64_t node_hash, uint64_t param_hash,
                                    uint64_t input_hash, const char *op_name, int multi_priority,
                                    int iop_order, int pipe_type, int32_t imgid, int roi_w,
                                    int roi_h, int devid, size_t size, const char *name);
 
// Cacheline read — every cache hit. Hash-only hot path; resolves from memory.
void dt_supervisor_cacheline_read(uint64_t hash, size_t size);
 
// Cacheline eviction/free — flips `alive` to FALSE, keeps the entry as memory.
void dt_supervisor_cacheline_delete(uint64_t hash, size_t size, int owner_pipe_id, const char *name);
 
void dt_supervisor_rekey(uint64_t old_hash, uint64_t new_hash);
 
void dt_supervisor_backbuf(dt_sv_op_t op, uint64_t hash, uint64_t history_hash, int w, int h,
                           int bpp, int pipe_type, int devid);
 
void dt_supervisor_widget(dt_sv_op_t op, const char *widget_tag, uint64_t consumed_hash,
                          int pipe_type, int32_t imgid);
 
void dt_supervisor_thumbnail(dt_sv_op_t op, int32_t imgid, int width, int height, int mip,
                             gboolean success);
 
void dt_supervisor_mipmap(dt_sv_op_t op, int32_t imgid, int mip);
 
void dt_supervisor_image(dt_sv_op_t op, int32_t imgid, const struct dt_image_t *img);
 
void dt_supervisor_cache_wait(dt_sv_op_t op, uint64_t request_id, uint64_t awaited_hash,
                              const char *owner_tag, const char *op_name, int multi_priority,
                              int pipe_type, int32_t imgid, gboolean request_emitted, const char *note);
 
gchar *dt_supervisor_describe(uint64_t hash);
 
#ifdef __cplusplus
}
#endif