pixelpipe_cache.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2009-2010 johannes hanika.
    Copyright (C) 2010-2011 Henrik Andersson.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2012, 2014, 2016 Tobias Ellinghaus.
    Copyright (C) 2014 Ulrich Pegelow.
    Copyright (C) 2016 Roman Lebedev.
    Copyright (C) 2020 Pascal Obry.
    Copyright (C) 2020 Ralf Brown.
    Copyright (C) 2022 Hanno Schwalm.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2023, 2025-2026 Aurélien PIERRE.
    
    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/>.
*/
 
#pragma once
 
#include "common/memory_arena.h"
#include "common/atomic.h"
#include "develop/format.h"
#include <inttypes.h>
#include <glib.h>
#include <stddef.h>
 
struct dt_dev_pixelpipe_t;
struct dt_iop_module_t;
struct dt_iop_roi_t;
 
#define DT_PIXELPIPE_CACHE_HASH_INVALID ((uint64_t)-1)
 
 
typedef struct dt_dev_pixelpipe_cache_t
{
  GHashTable *entries;
  // External (temporary) buffers keyed by address hash, separate from pipeline cache entries.
  GHashTable *external_entries;
  uint64_t next_serial;
  uint64_t queries;
  uint64_t hits;
  size_t max_memory;
  size_t current_memory;
  dt_pthread_mutex_t lock; // mutex to protect the cache entries
  dt_cache_arena_t arena;
} dt_dev_pixelpipe_cache_t;
 
typedef enum dt_dev_pixelpipe_cache_writable_status_t
{
  DT_DEV_PIXELPIPE_CACHE_WRITABLE_ERROR = -1,
  DT_DEV_PIXELPIPE_CACHE_WRITABLE_EXACT_HIT = -2,
  DT_DEV_PIXELPIPE_CACHE_WRITABLE_CREATED = 1,
  DT_DEV_PIXELPIPE_CACHE_WRITABLE_REKEYED = 2
} dt_dev_pixelpipe_cache_writable_status_t;
 
dt_dev_pixelpipe_cache_t *dt_dev_pixelpipe_cache_init(size_t max_memory);
void dt_dev_pixelpipe_cache_cleanup(dt_dev_pixelpipe_cache_t *cache);
 
/* Public for by-value snapshots in pipeline pieces (for example realtime
 * output cacheline reuse/rekey). Ownership still belongs to pixelpipe_cache.
 * External code must treat this as metadata only and never free internals. */
typedef struct dt_pixel_cache_entry_t
{
  uint64_t hash;            // unique identifier of the entry
  uint64_t serial;          // stable identity across rekeys, changes on fresh allocations
  void *data;               // buffer holding pixels... or anything else
  size_t size;              // size of the data buffer
  int64_t age;              // timestamp of creation. Oldest entry will be the first freed if it's not locked
  char *name;               // name of the cache entry, for debugging
  int id;                   // id of the pipeline owning this entry. Used when flushing, a pipe can only flush its own.
  dt_atomic_int refcount;   // reference count for the cache entry, to avoid freeing it while still in use
  dt_pthread_rwlock_t lock; // read/write lock to avoid threads conflicts
  gboolean auto_destroy;    // TRUE for auto-destruction the next time it's used. Used for short-lived entries (transient states).
  gboolean external_alloc;  // TRUE for external buffers tracked in the cache
  int hits;                 // number of times this entry was hit (utility score)
  dt_dev_pixelpipe_cache_t *cache; // reference to parent cache object
  GList *cl_mem_list;       // reusable OpenCL pinned buffers tied to this entry
  dt_pthread_mutex_t cl_mem_lock;
} dt_pixel_cache_entry_t;
 
const char *dt_pixelpipe_cache_set_current_module(const char *module);
 
struct dt_pixel_cache_entry_t *dt_dev_pixelpipe_cache_get_entry(dt_dev_pixelpipe_cache_t *cache,
                                                                const uint64_t hash);
 
/*
 * @brief Find a cache entry that holds the exact data buffer pointer `data`.
 *
 * This searches both regular and external cache tables under the cache mutex.
 * It does not change refcounts or locks on the returned entry; the caller must
 * manage lifetime if needed.
 */
struct dt_pixel_cache_entry_t *dt_dev_pixelpipe_cache_get_entry_by_data(dt_dev_pixelpipe_cache_t *cache,
                                                                        void *data);
 
 
int dt_dev_pixelpipe_cache_get(dt_dev_pixelpipe_cache_t *cache, const uint64_t hash, const size_t size,
                               const char *name, const int id, const gboolean alloc,
                               void **data,
                               struct dt_pixel_cache_entry_t **entry);
 
dt_dev_pixelpipe_cache_writable_status_t
dt_dev_pixelpipe_cache_get_writable(dt_dev_pixelpipe_cache_t *cache, const uint64_t hash,
                                    const size_t size, const char *name, const int id,
                                    const gboolean alloc, const gboolean allow_rekey_reuse,
                                    const struct dt_pixel_cache_entry_t *reuse_hint,
                                    void **data,
                                    struct dt_pixel_cache_entry_t **entry);
 
void *dt_dev_pixelpipe_cache_borrow_cl_payload(struct dt_pixel_cache_entry_t *entry,
                                               int devid, int width, int height, int bpp);
 
void dt_dev_pixelpipe_cache_return_cl_payload(struct dt_pixel_cache_entry_t *entry, void *mem);
 
void dt_dev_pixelpipe_cache_flush_entry_clmem(struct dt_pixel_cache_entry_t *entry);
 
gboolean dt_dev_pixelpipe_cache_restore_host_payload(dt_dev_pixelpipe_cache_t *cache,
                                                     struct dt_pixel_cache_entry_t *entry,
                                                     int preferred_devid, void **data);
 
void *dt_dev_pixelpipe_cache_get_pinned_image(dt_dev_pixelpipe_cache_t *cache, void *host_ptr,
                                              struct dt_pixel_cache_entry_t *entry_hint, int devid,
                                              int width, int height, int bpp, int flags,
                                              gboolean *out_reused);
 
void dt_dev_pixelpipe_cache_put_pinned_image(dt_dev_pixelpipe_cache_t *cache, void *host_ptr,
                                             struct dt_pixel_cache_entry_t *entry_hint, void **mem);
 
gboolean dt_dev_pixelpipe_cache_flush_host_pinned_image(dt_dev_pixelpipe_cache_t *cache, void *host_ptr,
                                                        struct dt_pixel_cache_entry_t *entry_hint, int devid);
 
void *dt_dev_pixelpipe_cache_get_cl_buffer(int devid, void *host_ptr, const struct dt_iop_roi_t *roi,
                                           size_t bpp, struct dt_iop_module_t *module,
                                           const char *message, struct dt_pixel_cache_entry_t *entry,
                                           gboolean *out_reused, void *keep);
 
void *dt_dev_pixelpipe_cache_alloc_cl_device_buffer(int devid, const struct dt_iop_roi_t *roi, size_t bpp,
                                                    const struct dt_iop_module_t *module,
                                                    const char *message, void *keep);
 
void dt_dev_pixelpipe_cache_release_cl_buffer(void **cl_mem_buffer, struct dt_pixel_cache_entry_t *entry,
                                              void *host_ptr, gboolean cache_device);
 
int dt_dev_pixelpipe_cache_sync_cl_buffer(int devid, void *host_ptr, void *cl_mem_buffer,
                                          const struct dt_iop_roi_t *roi, int cl_mode, size_t bpp,
                                          struct dt_iop_module_t *module, const char *message);
 
float *dt_dev_pixelpipe_cache_restore_cl_buffer(struct dt_dev_pixelpipe_t *pipe, float *input,
                                                void *cl_mem_input, const struct dt_iop_roi_t *roi_in,
                                                struct dt_iop_module_t *module, size_t in_bpp,
                                                struct dt_pixel_cache_entry_t *input_entry,
                                                const char *message);
 
int dt_dev_pixelpipe_cache_prepare_cl_input(struct dt_dev_pixelpipe_t *pipe,
                                            struct dt_iop_module_t *module,
                                            float *input, void **cl_mem_input,
                                            const struct dt_iop_roi_t *roi_in, size_t in_bpp,
                                            struct dt_pixel_cache_entry_t *input_entry,
                                            struct dt_pixel_cache_entry_t **locked_input_entry,
                                            void *keep);
 
struct dt_pixel_cache_entry_t *dt_dev_pixelpipe_cache_ref_entry_for_host_ptr(dt_dev_pixelpipe_cache_t *cache,
                                                                              void *host_ptr);
 
gboolean dt_dev_pixelpipe_cache_ref_entry_by_hash(dt_dev_pixelpipe_cache_t *cache,
                                                  const uint64_t hash,
                                                  void **data,
                                                  struct dt_pixel_cache_entry_t **entry);
 
void *dt_pixel_cache_entry_get_data(struct dt_pixel_cache_entry_t *entry);
 
size_t dt_pixel_cache_entry_get_size(struct dt_pixel_cache_entry_t *entry);
 
                      
void *dt_pixel_cache_alloc(dt_dev_pixelpipe_cache_t *cache, struct dt_pixel_cache_entry_t *entry);
 
void *dt_pixelpipe_cache_alloc_align_cache_impl(dt_dev_pixelpipe_cache_t *cache, size_t size, int id,
                                                const char *name);
 
void dt_pixelpipe_cache_free_align_cache(dt_dev_pixelpipe_cache_t *cache, void **mem, const char *message);
 
gboolean dt_dev_pixelpipe_cache_peek(dt_dev_pixelpipe_cache_t *cache, const uint64_t hash, void **data,
                                     struct dt_pixel_cache_entry_t **entry, const int preferred_devid,
                                     void **cl_mem_output);
 
void dt_dev_pixelpipe_cache_flush(dt_dev_pixelpipe_cache_t *cache, const int id);
 
int dt_dev_pixelpipe_cache_invalidate_hashes(dt_dev_pixelpipe_cache_t *cache,
                                             const uint64_t *hashes,
                                             const size_t count);
 
void dt_dev_pixelpipe_cache_flush_clmem(dt_dev_pixelpipe_cache_t *cache, const int devid);
 
void dt_dev_pixelpipe_cache_flush_clmem_for_pipe(dt_dev_pixelpipe_cache_t *cache, const int devid);
 
 
int dt_dev_pixelpipe_cache_remove(dt_dev_pixelpipe_cache_t *cache, const gboolean force,
                                  struct dt_pixel_cache_entry_t *entry);
 
 
void dt_dev_pixelpipe_cache_print(dt_dev_pixelpipe_cache_t *cache);
 
int dt_dev_pixel_pipe_cache_remove_lru(dt_dev_pixelpipe_cache_t *cache);
 
void dt_dev_pixelpipe_cache_ref_count_entry(dt_dev_pixelpipe_cache_t *cache, gboolean lock,
                                            struct dt_pixel_cache_entry_t *entry);
 
void dt_dev_pixelpipe_cache_wrlock_entry(dt_dev_pixelpipe_cache_t *cache, gboolean lock,
                                         struct dt_pixel_cache_entry_t *entry);
 
 
void dt_dev_pixelpipe_cache_rdlock_entry(dt_dev_pixelpipe_cache_t *cache, gboolean lock,
                                         struct dt_pixel_cache_entry_t *entry);
 
 
void dt_dev_pixelpipe_cache_flag_auto_destroy(dt_dev_pixelpipe_cache_t *cache,
                                              struct dt_pixel_cache_entry_t *entry);
 
void dt_dev_pixelpipe_cache_auto_destroy_apply(dt_dev_pixelpipe_cache_t *cache,
                                               struct dt_pixel_cache_entry_t *entry);
 
void dt_dev_pixelpipe_cache_unref_hash(dt_dev_pixelpipe_cache_t *cache, const uint64_t hash);
 
int dt_dev_pixelpipe_cache_rekey(dt_dev_pixelpipe_cache_t *cache, const uint64_t old_hash,
                                 const uint64_t new_hash, struct dt_pixel_cache_entry_t *entry);
 
// 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