pixelpipe_cache.h File Reference

Pixelpipe cache for storing intermediate results in the pixelpipe. More...

#include "system/memory_arena.h"
#include "system/atomic.h"
#include "pixel/format.h"
#include <inttypes.h>
#include <glib.h>
#include <stddef.h>

Include dependency graph for pixelpipe_cache.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	dt_pixel_cache_stats_entry_t
struct	dt_pixel_cache_entry_t
struct	dt_pixelpipe_cache_observer_t
	The supervisor's view of the cache. All four may be NULL; active gates the other three so the cache pays one predicted-false branch when nobody is watching. More...

Macros
#define	DT_PIXELPIPE_CACHE_HASH_INVALID   ((uint64_t)-1)

Typedefs
typedef struct dt_dev_pixelpipe_cache_t	dt_dev_pixelpipe_cache_t
typedef enum dt_dev_pixelpipe_cache_writable_status_t	dt_dev_pixelpipe_cache_writable_status_t
typedef struct dt_pixel_cache_stats_entry_t	dt_pixel_cache_stats_entry_t
typedef struct dt_pixel_cache_entry_t	dt_pixel_cache_entry_t
typedef void(*	dt_pixelpipe_cache_warn_handler_t) (const char *message)
	Tell the user something went wrong. Called with an already-translated, already-formatted string; the cache does not know what a toast is.
typedef void(*	dt_pixelpipe_cache_ready_handler_t) (uint64_t hash, uint64_t producer_node_key)
	A cacheline finished and is readable.
typedef struct dt_pixelpipe_cache_observer_t	dt_pixelpipe_cache_observer_t
	The supervisor's view of the cache. All four may be NULL; ::active gates the other three so the cache pays one predicted-false branch when nobody is watching.

Enumerations
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 }

Functions
gboolean	dt_dev_pixelpipe_cache_init (size_t max_memory, const gboolean verbose, const gboolean verbose_detail)
	Reserve the cache's arena and start it.
gboolean	dt_dev_pixelpipe_cache_is_ready (void)
	Has the pixelpipe cache been initialised? Callers that run before dt_dev_pixelpipe_cache_init() succeeds, or after its cleanup, ask this rather than testing a handle they should not hold.
void	dt_dev_pixelpipe_cache_cleanup (void)
void	dt_dev_pixelpipe_cache_get_usage (size_t *current, size_t *max)
size_t	dt_pixelpipe_cache_get_largest_free_run (void)
size_t	dt_dev_pixelpipe_cache_get_vram_total (void)
GArray *	dt_dev_pixelpipe_cache_get_entries_stats (void)
const char *	dt_pixelpipe_cache_set_current_module (const char *module)
	Set the current module name for cache diagnostics (thread-local).
struct dt_pixel_cache_entry_t *	dt_dev_pixelpipe_cache_get_entry (const uint64_t hash)
	Get an internal reference to the cache entry matching hash. If you are going to access this entry more than once, keeping the reference and using it instead of hashes will prevent redundant lookups.
struct dt_pixel_cache_entry_t *	dt_dev_pixelpipe_cache_get_entry_by_data (void *data)
int	dt_dev_pixelpipe_cache_get (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)
	Get a cache line from the cache.
dt_dev_pixelpipe_cache_writable_status_t	dt_dev_pixelpipe_cache_get_writable (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)
	Acquire a writable cache line for module output.
void *	dt_dev_pixelpipe_cache_borrow_cl_payload (struct dt_pixel_cache_entry_t *entry, int devid, int width, int height, int bpp)
	Borrow a cached OpenCL payload attached to a cache entry.
void	dt_dev_pixelpipe_cache_return_cl_payload (struct dt_pixel_cache_entry_t *entry, void *mem)
	Return a borrowed cached OpenCL payload to its cache entry.
void	dt_dev_pixelpipe_cache_flush_entry_clmem (struct dt_pixel_cache_entry_t *entry)
	Flush all reusable OpenCL payloads cached on one cache entry.
gboolean	dt_dev_pixelpipe_cache_restore_host_payload (struct dt_pixel_cache_entry_t *entry, int preferred_devid, void **data)
	Materialize a host payload for a live cache entry from its cached device payload.
void *	dt_dev_pixelpipe_cache_get_pinned_image (void *host_ptr, struct dt_pixel_cache_entry_t *entry_hint, int devid, int width, int height, int bpp, int flags, gboolean *out_reused)
	Acquire a pinned OpenCL image for a host buffer tracked by the pixelpipe cache.
void	dt_dev_pixelpipe_cache_put_pinned_image (void *host_ptr, struct dt_pixel_cache_entry_t *entry_hint, void **mem)
	Release or cache a pinned OpenCL image acquired with dt_dev_pixelpipe_cache_get_pinned_image().
gboolean	dt_dev_pixelpipe_cache_flush_host_pinned_image (void *host_ptr, struct dt_pixel_cache_entry_t *entry_hint, int devid)
	Drop cached pinned OpenCL images associated with a given host buffer.
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)
	Allocate or reuse an OpenCL buffer for one cache entry payload.
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)
	Allocate a temporary device-only OpenCL image, retrying once after cache flush.
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)
	Release or cache an OpenCL image associated with one cache entry.
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)
	Synchronize between host memory and a pinned OpenCL image.
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)
	Resynchronize one OpenCL input payload back into its cache-backed host buffer.
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)
	Prepare the OpenCL input image corresponding to one cache-backed module input.
struct dt_pixel_cache_entry_t *	dt_dev_pixelpipe_cache_ref_entry_for_host_ptr (void *host_ptr)
	Resolve and retain the cache entry owning a host pointer.
gboolean	dt_dev_pixelpipe_cache_ref_entry_by_hash (const uint64_t hash, void **data, struct dt_pixel_cache_entry_t **entry)
	Resolve and retain an existing cache entry by hash.
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)
	Peek the size (in bytes) reserved for the host buffer of a cache entry.
void *	dt_pixel_cache_alloc (struct dt_pixel_cache_entry_t *entry)
	Actually allocate the memory buffer attached to the cache entry once you create it with dt_dev_pixelpipe_cache_get(). Sizes and everything are already saved in the entry, and the cache will have the needed space reserved.
void *	dt_pixelpipe_cache_alloc_align_cache_impl (size_t size, int id, const char *name)
	Allocate aligned memory tracked by the pixelpipe cache. This allows LRU cache entries to be evicted if needed to make room.
void	dt_pixelpipe_cache_free_align_cache (void **mem, const char *message)
	Free aligned memory allocated with dt_pixelpipe_cache_alloc_align_cache.
gboolean	dt_dev_pixelpipe_cache_peek (const uint64_t hash, void **data, struct dt_pixel_cache_entry_t **entry, const int preferred_devid, void **cl_mem_output)
	Non-owning lookup of an existing cache line.
void	dt_dev_pixelpipe_cache_flush (const int id)
	Remove cache lines matching id. Entries locked in read/write or having reference count greater than 0 are not removed.
int	dt_dev_pixelpipe_cache_invalidate_hashes (const uint64_t *hashes, const size_t count)
	Invalidate cache lines matching an explicit list of hashes.
void	dt_dev_pixelpipe_cache_flush_clmem (const int devid)
	Release cached OpenCL buffers for a single device.
void	dt_dev_pixelpipe_cache_flush_clmem_for_pipe (const int devid)
	Like dt_dev_pixelpipe_cache_flush_clmem(), for callers that do not hold the device lock (dt_opencl_reserve_device_by_id()) (e.g. a pipe's own cleanup after dt_dev_pixelpipe_process() already released it). Takes the lock itself, then delegates. No-op if devid < 0 or OpenCL isn't available.
int	dt_dev_pixelpipe_cache_remove (const gboolean force, struct dt_pixel_cache_entry_t *entry)
	Arbitrarily remove the cache entry matching hash. Entries having a reference count > 0 (inter-thread locked) or being having their read/write lock locked will be ignored. If force is TRUE, we ignore reference count, but not locks.
void	dt_dev_pixelpipe_cache_print (void)
int	dt_dev_pixel_pipe_cache_remove_lru (void)
void	dt_dev_pixelpipe_cache_ref_count_entry (gboolean lock, struct dt_pixel_cache_entry_t *entry)
	Increase/Decrease the reference count on the cache line as to prevent LRU item removal. This function should be called within a read/write lock-protected section to avoid changing an entry while or after it is deleted in parallel.
void	dt_dev_pixelpipe_cache_wrlock_entry (gboolean lock, struct dt_pixel_cache_entry_t *entry)
	Lock or release the write lock on the entry.
void	dt_dev_pixelpipe_cache_rdlock_entry (gboolean lock, struct dt_pixel_cache_entry_t *entry)
	Lock or release the read lock on the entry.
void	dt_dev_pixelpipe_cache_flag_auto_destroy (struct dt_pixel_cache_entry_t *entry)
	Flag the cache entry as "auto_destroy". This is useful for short-lived/disposable cache entries, that won't be needed in the future. These will be freed out of the typical LRU, aged-based garbage collection. The thread that tagged this entry as "auto_destroy" is responsible for freeing it as soon as it is done with it, using dt_dev_pixelpipe_cache_auto_destroy_apply(). If not manually freed this way, the entry will be caught using the generic LRU garbage collection.
void	dt_dev_pixelpipe_cache_auto_destroy_apply (struct dt_pixel_cache_entry_t *entry)
	Free the entry if it has the flag "auto_destroy". See dt_dev_pixelpipe_cache_flag_auto_destroy(). This only removes entries whose reference count already dropped to 0 and whose lock is currently free. Call it right after the final consumer releases its refcount, from the same control flow that flagged the entry for auto-destruction. If another consumer still owns the entry, this becomes a no-op and generic cache eviction or a later explicit retry will reap it once ownership reaches 0.
void	dt_dev_pixelpipe_cache_unref_hash (const uint64_t hash)
	Find the entry matching hash, and decrease its ref_count if found.
int	dt_dev_pixelpipe_cache_rekey (const uint64_t old_hash, const uint64_t new_hash, struct dt_pixel_cache_entry_t *entry)
	Change the hash/key of an existing cache line in place, without freeing, reallocating or invalidating the underlying entry.
void	dt_dev_pixelpipe_cache_set_handlers (dt_pixelpipe_cache_warn_handler_t warn, dt_pixelpipe_cache_ready_handler_t ready, const dt_pixelpipe_cache_observer_t *observer)
	Install the handlers. Call once, from the orchestrator, before any pipe runs.

Detailed Description

Pixelpipe cache for storing intermediate results in the pixelpipe.

This cache can be used locally (in the pixelpipe) or globally (in the whole app). Current implementation is global, using darktable.pipeline_threadsafe mutex lock to protect cache entries addition/removal accross threads. The mutex lock protects the whole recursive pixelpipe, so no internal locking is needed nor implemented here.

Definition in file pixelpipe_cache.h.

Macro Definition Documentation

DT_PIXELPIPE_CACHE_HASH_INVALID

#define DT_PIXELPIPE_CACHE_HASH_INVALID   ((uint64_t)-1)

Definition at line 51 of file pixelpipe_cache.h.

Typedef Documentation

dt_dev_pixelpipe_cache_t

typedef struct dt_dev_pixelpipe_cache_t dt_dev_pixelpipe_cache_t

Definition at line 65 of file pixelpipe_cache.h.

dt_dev_pixelpipe_cache_writable_status_t

typedef enum dt_dev_pixelpipe_cache_writable_status_t dt_dev_pixelpipe_cache_writable_status_t

dt_pixel_cache_entry_t

typedef struct dt_pixel_cache_entry_t dt_pixel_cache_entry_t

dt_pixel_cache_stats_entry_t

typedef struct dt_pixel_cache_stats_entry_t dt_pixel_cache_stats_entry_t

dt_pixelpipe_cache_observer_t

typedef struct dt_pixelpipe_cache_observer_t dt_pixelpipe_cache_observer_t

The supervisor's view of the cache. All four may be NULL; ::active gates the other three so the cache pays one predicted-false branch when nobody is watching.

dt_pixelpipe_cache_ready_handler_t

typedef void(* dt_pixelpipe_cache_ready_handler_t) (uint64_t hash, uint64_t producer_node_key)

A cacheline finished and is readable.

Parameters

hash	its content hash,
producer_node_key	which node published it. Waiters key on both.

Definition at line 799 of file pixelpipe_cache.h.

dt_pixelpipe_cache_warn_handler_t

typedef void(* dt_pixelpipe_cache_warn_handler_t) (const char *message)

Tell the user something went wrong. Called with an already-translated, already-formatted string; the cache does not know what a toast is.

Definition at line 795 of file pixelpipe_cache.h.

Enumeration Type Documentation

dt_dev_pixelpipe_cache_writable_status_t

enum dt_dev_pixelpipe_cache_writable_status_t

Enumerator
DT_DEV_PIXELPIPE_CACHE_WRITABLE_ERROR
DT_DEV_PIXELPIPE_CACHE_WRITABLE_EXACT_HIT
DT_DEV_PIXELPIPE_CACHE_WRITABLE_CREATED
DT_DEV_PIXELPIPE_CACHE_WRITABLE_REKEYED

Definition at line 67 of file pixelpipe_cache.h.

Function Documentation

dt_dev_pixel_pipe_cache_remove_lru()

int dt_dev_pixel_pipe_cache_remove_lru

(

void

)

remove the least used cache entry

Returns

0 on success, 1 on error

Definition at line 753 of file pixelpipe_cache.c.

References _non_thread_safe_pixel_pipe_cache_remove_lru(), _pixelpipe_cache, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), error(), and dt_dev_pixelpipe_cache_t::lock.

Referenced by dt_tiling_piece_fits_host_memory().

dt_dev_pixelpipe_cache_alloc_cl_device_buffer()

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
	)

Allocate a temporary device-only OpenCL image, retrying once after cache flush.

Parameters

devid	OpenCL device id.
roi	Buffer dimensions.
bpp	Bytes per pixel.
module	Module for debug messages.
message	Human-readable allocation context.
keep	Optional OpenCL buffer that must not be flushed during retry.

Returns

void* OpenCL image (cl_mem) or NULL on failure.

dt_dev_pixelpipe_cache_auto_destroy_apply()

void dt_dev_pixelpipe_cache_auto_destroy_apply

(

struct dt_pixel_cache_entry_t *

entry

)

Free the entry if it has the flag "auto_destroy". See dt_dev_pixelpipe_cache_flag_auto_destroy(). This only removes entries whose reference count already dropped to 0 and whose lock is currently free. Call it right after the final consumer releases its refcount, from the same control flow that flagged the entry for auto-destruction. If another consumer still owns the entry, this becomes a no-op and generic cache eviction or a later explicit retry will reap it once ownership reaches 0.

Parameters

cache

Definition at line 2834 of file pixelpipe_cache.c.

References _pixel_cache_message(), _pixelpipe_cache, dt_pixel_cache_entry_t::auto_destroy, dt_atomic_get_int(), dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_pthread_rwlock_trywrlock(), dt_pthread_rwlock_unlock(), dt_dev_pixelpipe_cache_t::entries, FALSE, dt_pixel_cache_entry_t::hash, IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, dt_pixel_cache_entry_t::lock, dt_pixel_cache_entry_t::refcount, and TRUE.

Referenced by _abort_module_shutdown_cleanup(), dt_dev_pixelpipe_cleanup(), and dt_dev_pixelpipe_process_rec().

dt_dev_pixelpipe_cache_borrow_cl_payload()

void * dt_dev_pixelpipe_cache_borrow_cl_payload	(	struct dt_pixel_cache_entry_t *	entry,
		int	devid,
		int	width,
		int	height,
		int	bpp
	)

Borrow a cached OpenCL payload attached to a cache entry.

This reopens a cached cl_mem image already tracked by the cache entry and increments its internal borrow counter so cache flush/eviction paths will keep it alive until the caller returns it with dt_dev_pixelpipe_cache_return_cl_payload().

Parameters

entry	Cache entry owning the payload.
host_ptr	Host pointer key for pinned payloads, or NULL for device-only payloads.
devid	OpenCL device id.
width	Image width.
height	Image height.
bpp	Bytes per pixel.
flags	Tracked OpenCL flags used when the payload was cached.

Returns

void* Borrowed cl_mem, or NULL if no matching cached payload exists.

Definition at line 810 of file pixelpipe_cache.c.

References bpp, dt_pixel_cache_entry_t::cl_mem_list, dt_pixel_cache_entry_t::cl_mem_lock, dt_opencl_get_image_element_size(), dt_opencl_get_image_height(), dt_opencl_get_image_width(), dt_opencl_get_mem_context_id(), dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), height, and width.

Referenced by pixelpipe_process_on_GPU().

dt_dev_pixelpipe_cache_cleanup()

void dt_dev_pixelpipe_cache_cleanup

(

void

)

Definition at line 2185 of file pixelpipe_cache.c.

References _pixelpipe_cache, dt_dev_pixelpipe_cache_t::arena, dt_cache_arena_cleanup(), dt_pthread_mutex_destroy(), dt_dev_pixelpipe_cache_t::entries, dt_dev_pixelpipe_cache_t::external_entries, garbage_collection, dt_dev_pixelpipe_cache_t::lock, and pressure_shedding.

Referenced by dt_cleanup().

dt_dev_pixelpipe_cache_flag_auto_destroy()

void dt_dev_pixelpipe_cache_flag_auto_destroy

(

struct dt_pixel_cache_entry_t *

entry

)

Flag the cache entry as "auto_destroy". This is useful for short-lived/disposable cache entries, that won't be needed in the future. These will be freed out of the typical LRU, aged-based garbage collection. The thread that tagged this entry as "auto_destroy" is responsible for freeing it as soon as it is done with it, using dt_dev_pixelpipe_cache_auto_destroy_apply(). If not manually freed this way, the entry will be caught using the generic LRU garbage collection.

Parameters

cache

Definition at line 2818 of file pixelpipe_cache.c.

References _pixel_cache_message(), _pixelpipe_cache, dt_pixel_cache_entry_t::auto_destroy, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, and TRUE.

Referenced by _abort_module_shutdown_cleanup(), dt_dev_pixelpipe_cache_peek(), dt_dev_pixelpipe_cleanup(), and dt_dev_pixelpipe_process_rec().

dt_dev_pixelpipe_cache_flush()

void dt_dev_pixelpipe_cache_flush

(

const int

id

)

Remove cache lines matching id. Entries locked in read/write or having reference count greater than 0 are not removed.

Parameters

cache
id	ID of the pipeline owning the cache line, or -1 to remove all lines.

Definition at line 2618 of file pixelpipe_cache.c.

References _for_each_remove(), _pixelpipe_cache, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, and dt_dev_pixelpipe_cache_t::lock.

Referenced by dt_dev_pixelpipe_reset_all().

dt_dev_pixelpipe_cache_flush_clmem()

void dt_dev_pixelpipe_cache_flush_clmem

(

const int

devid

)

Release cached OpenCL buffers for a single device.

This is intentionally a lightweight VRAM-pressure/retry helper: it drops cached cl_mem objects without taking per-entry write locks. Realtime paths rely on it to free scratch OpenCL buffers without stalling in-flight renders.

Parameters

devid

Device to flush, or a negative value for a no-op (e.g. a pipe that never used OpenCL). The caller must already hold the device lock (dt_opencl_reserve_device_by_id()) – this is the case for the pixelpipe currently running on that device. Callers that don't hold it (e.g. cleaning up a pipe after it finished) must use dt_dev_pixelpipe_cache_flush_clmem_for_pipe() instead.

Definition at line 582 of file pixelpipe_cache.c.

References _cache_entry_clmem_flush_device(), _cache_print, _pixelpipe_cache, _verbose, _verbose_detail, dt_atomic_get_int(), DT_DEBUG_OPENCL, dt_opencl_events_wait_for(), dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_pthread_rwlock_trywrlock(), dt_pthread_rwlock_unlock(), dt_dev_pixelpipe_cache_t::entries, dt_pixel_cache_entry_t::hash, key, dt_dev_pixelpipe_cache_t::lock, dt_pixel_cache_entry_t::lock, dt_pixel_cache_entry_t::refcount, and value.

Referenced by _dt_opencl_alloc_image2d(), dt_dev_pixelpipe_cache_flush_clmem_for_pipe(), dt_opencl_alloc_device_buffer_with_flags(), and pixelpipe_process_on_GPU().

dt_dev_pixelpipe_cache_flush_clmem_for_pipe()

void dt_dev_pixelpipe_cache_flush_clmem_for_pipe

(

const int

devid

)

Like dt_dev_pixelpipe_cache_flush_clmem(), for callers that do not hold the device lock (dt_opencl_reserve_device_by_id()) (e.g. a pipe's own cleanup after dt_dev_pixelpipe_process() already released it). Takes the lock itself, then delegates. No-op if devid < 0 or OpenCL isn't available.

Definition at line 652 of file pixelpipe_cache.c.

References dt_dev_pixelpipe_cache_flush_clmem(), dt_opencl_is_inited(), dt_opencl_release_device(), and dt_opencl_reserve_device_by_id().

Referenced by _studio_dev_teardown(), dt_dev_pixelpipe_cleanup(), and leave().

dt_dev_pixelpipe_cache_flush_entry_clmem()

void dt_dev_pixelpipe_cache_flush_entry_clmem

(

struct dt_pixel_cache_entry_t *

entry

)

Flush all reusable OpenCL payloads cached on one cache entry.

Borrowed payloads are preserved until all borrowers returned them.

Parameters

entry

Cache entry whose cached cl_mem payloads should be flushed.

Definition at line 936 of file pixelpipe_cache.c.

References dt_pixel_cache_entry_t::cl_mem_list, dt_pixel_cache_entry_t::cl_mem_lock, dt_free, dt_opencl_release_mem_object(), dt_pthread_mutex_lock(), and dt_pthread_mutex_unlock().

Referenced by _free_cache_entry(), dt_dev_pixelpipe_cache_rekey(), and dt_dev_pixelpipe_process_rec().

dt_dev_pixelpipe_cache_flush_host_pinned_image()

gboolean dt_dev_pixelpipe_cache_flush_host_pinned_image	(	void *	host_ptr,
		struct dt_pixel_cache_entry_t *	entry_hint,
		int	devid
	)

Drop cached pinned OpenCL images associated with a given host buffer.

This is meant for host buffers that remain alive and continue to be mutated by the CPU (for example, privately owned working patches). Reusing a stale CL_MEM_USE_HOST_PTR image for such buffers can hide later host-side edits on some drivers. Flushing the cached pinned images forces the next use to rebind the host storage.

Parameters

cache	Pixelpipe cache.
host_ptr	Host-backed image data.
entry_hint	Optional owning cache entry for regular cache lines, or NULL.
devid	Device id to flush, or -1 for all cached devices for that host buffer.

Returns

gboolean TRUE if at least one pinned image was flushed, FALSE otherwise.

Definition at line 1051 of file pixelpipe_cache.c.

References _cache_entry_clmem_flush_host_pinned_locked(), _cache_entry_clmem_has_host_pinned_locked(), _cache_entry_for_host_ptr_locked(), _pixelpipe_cache, dt_dev_pixelpipe_cache_ref_count_entry(), dt_opencl_events_wait_for(), dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), FALSE, IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, and TRUE.

Referenced by _rasterize_pending_dab_batch(), _rekey_shared_base_patch(), dt_dev_pixelpipe_gpu_flush_host_pinned_images(), dt_drawlayer_cache_flush_process_patch_to_base(), and dt_drawlayer_cache_populate_process_patch_from_base().

dt_dev_pixelpipe_cache_get()

int dt_dev_pixelpipe_cache_get	(	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
	)

Get a cache line from the cache.

WARNING: This internally increases the reference count, so you have to manually decrease it using dt_dev_pixelpipe_ref_count_entry() once the cache line content has been consumed or it will never be freed.

WARNING: if the cache line was newly allocated, a write lock is put on straight away. You will have to release it from the same calling thread next, to avoid dead locks.

Parameters

cache
hash	State checksum of the cache line.
size	Buffer size in bytes.
name	Name of the cache line (for debugging).
id	ID of the pipeline owning the cache line.
data	Pointer to the buffer pointer (returned).
alloc	Whether or not we should actually alloc the buffer, or simply reserve it. If FALSE use dt_pixel_cache_alloc() when you actually need the buffer.
cache_entry	a reference to the cache entry, to be reused later. Can be NULL. The caller doesn't own the data and shouldn't free it.

Returns

int 1 if the cache line was freshly allocated, 0 if it was found in the cache.

Definition at line 2291 of file pixelpipe_cache.c.

References _cache_print, _non_thread_safe_cache_ref_count_entry(), _non_thread_safe_cache_remove(), _non_threadsafe_cache_get_entry(), _observe_read(), _pixel_cache_message(), _pixelpipe_cache, _pixelpipe_cache_create_entry_locked(), _pixelpipe_cache_finalize_entry(), dt_pixel_cache_entry_t::auto_destroy, dt_pixel_cache_entry_t::data, DT_DEBUG_PIPECACHE, dt_dev_pixelpipe_cache_wrlock_entry(), dt_pixel_cache_alloc(), DT_PIXELPIPE_CACHE_HASH_INVALID, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, FALSE, dt_dev_pixelpipe_cache_t::hits, dt_pixel_cache_entry_t::hits, IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, name, dt_dev_pixelpipe_cache_t::queries, size, dt_pixel_cache_entry_t::size, and TRUE.

Referenced by dt_develop_blend_process(), dt_develop_blend_process_cl(), dt_drawlayer_cache_patch_alloc_shared(), process(), and process_cl().

dt_dev_pixelpipe_cache_get_cl_buffer()

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
	)

Allocate or reuse an OpenCL buffer for one cache entry payload.

This is the cache-owned buffer acquisition helper used by the OpenCL pixelpipe backend:

• if !IS_NULL_PTR(host_ptr), it may reuse or allocate a pinned CL_MEM_USE_HOST_PTR image,
• if IS_NULL_PTR(host_ptr), it may reuse or allocate a device-only scratch image,
• allocation failures may trigger a cache-side cl_mem flush and one retry.

Parameters

	devid	OpenCL device id.
	host_ptr	Host backing store for pinned images, or NULL for device-only images.
	roi	Buffer dimensions.
	bpp	Bytes per pixel.
	module	Module for debug messages.
	message	Human-readable allocation context.
	entry	Owning cache entry.
[out]	out_reused	Optional flag set TRUE when the buffer came from cache reuse.
	keep	Optional OpenCL buffer that must not be flushed during retry.

Returns

void* OpenCL image (cl_mem) or NULL on failure.

dt_dev_pixelpipe_cache_get_entries_stats()

GArray * dt_dev_pixelpipe_cache_get_entries_stats

(

void

)

Definition at line 3003 of file pixelpipe_cache.c.

References _pixelpipe_cache, dt_pixel_cache_stats_entry_t::cl_bytes, dt_pixel_cache_stats_entry_t::cl_count, dt_pixel_cache_entry_t::cl_mem_list, dt_pixel_cache_entry_t::cl_mem_lock, dt_atomic_get_int(), dt_opencl_get_mem_object_size(), dt_pthread_mutex_lock(), dt_pthread_mutex_trylock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, FALSE, dt_pixel_cache_stats_entry_t::hash, dt_pixel_cache_entry_t::hash, dt_pixel_cache_stats_entry_t::hits, dt_pixel_cache_entry_t::hits, IS_NULL_PTR, key, dt_dev_pixelpipe_cache_t::lock, dt_pixel_cache_stats_entry_t::name, dt_pixel_cache_entry_t::name, out, dt_pixel_cache_stats_entry_t::refcount, dt_pixel_cache_entry_t::refcount, dt_pixel_cache_stats_entry_t::size, dt_pixel_cache_entry_t::size, and value.

Referenced by _rebuild_memory().

dt_dev_pixelpipe_cache_get_entry()

struct dt_pixel_cache_entry_t * dt_dev_pixelpipe_cache_get_entry

(

const uint64_t

hash

)

Get an internal reference to the cache entry matching hash. If you are going to access this entry more than once, keeping the reference and using it instead of hashes will prevent redundant lookups.

Parameters

cache
hash

Returns

struct dt_pixel_cache_entry_t*

Definition at line 244 of file pixelpipe_cache.c.

References _non_threadsafe_cache_get_entry(), _pixelpipe_cache, DT_PIXELPIPE_CACHE_HASH_INVALID, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, and dt_dev_pixelpipe_cache_t::lock.

Referenced by dt_dev_pixelpipe_cleanup(), dt_dev_pixelpipe_process_rec(), and dt_dev_retrieve_rawdetail_mask().

dt_dev_pixelpipe_cache_get_entry_by_data()

struct dt_pixel_cache_entry_t * dt_dev_pixelpipe_cache_get_entry_by_data

(

void *

data

)

Definition at line 255 of file pixelpipe_cache.c.

References _pixelpipe_cache, dt_pixel_cache_entry_t::data, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, dt_dev_pixelpipe_cache_t::external_entries, key, dt_dev_pixelpipe_cache_t::lock, and value.

dt_dev_pixelpipe_cache_get_pinned_image()

void * dt_dev_pixelpipe_cache_get_pinned_image	(	void *	host_ptr,
		struct dt_pixel_cache_entry_t *	entry_hint,
		int	devid,
		int	width,
		int	height,
		int	bpp,
		int	flags,
		gboolean *	out_reused
	)

Acquire a pinned OpenCL image for a host buffer tracked by the pixelpipe cache.

This is the public helper for modules that manage their own host buffers but still want the pixelpipe cache to own the reusable pinned cl_mem images. The helper accepts an optional cache-entry hint for normal cache lines. If that hint is NULL, it will try to resolve the host pointer against the cache's privately-owned external allocations.

On reuse, the helper synchronizes host memory to the OpenCL image before returning.

Parameters

	cache	Pixelpipe cache.
	host_ptr	Host-backed image data.
	entry_hint	Optional owning cache entry for regular cache lines, or NULL.
	devid	OpenCL device id.
	width	Image width.
	height	Image height.
	bpp	Bytes per pixel.
	flags	OpenCL allocation flags (must include CL_MEM_USE_HOST_PTR).
[out]	out_reused	Optional flag set TRUE when an existing pinned image was reused.

Returns

void* OpenCL image (cl_mem) or NULL on failure.

Definition at line 958 of file pixelpipe_cache.c.

References _cache_entry_for_host_ptr_locked(), _cache_print, _pixel_cache_clmem_get(), _pixel_cache_clmem_remove(), _pixelpipe_cache, bpp, DT_DEBUG_OPENCL, dt_opencl_alloc_device_use_host_pointer(), dt_opencl_is_pinned_memory(), dt_opencl_map_image(), dt_opencl_release_mem_object(), dt_opencl_unmap_mem_object(), dt_opencl_use_pinned_memory(), dt_opencl_write_host_to_device(), dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), FALSE, flags, height, IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, TRUE, and width.

Referenced by _blend_layer_over_input_cl(), and _drawlayer_acquire_source_image().

dt_dev_pixelpipe_cache_get_usage()

void dt_dev_pixelpipe_cache_get_usage	(	size_t *	current,
		size_t *	max
	)

Definition at line 2991 of file pixelpipe_cache.c.

References _pixelpipe_cache, dt_dev_pixelpipe_cache_t::current_memory, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, max, and dt_dev_pixelpipe_cache_t::max_memory.

Referenced by _rebuild_memory(), dt_get_available_mem(), and dt_tiling_piece_fits_host_memory().

dt_dev_pixelpipe_cache_get_vram_total()

size_t dt_dev_pixelpipe_cache_get_vram_total

(

void

)

Definition at line 3046 of file pixelpipe_cache.c.

References dt_opencl_get_device_max_global_mem(), dt_opencl_get_num_devices(), dt_opencl_is_enabled(), and i.

Referenced by _rebuild_memory().

dt_dev_pixelpipe_cache_get_writable()

dt_dev_pixelpipe_cache_writable_status_t dt_dev_pixelpipe_cache_get_writable	(	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
	)

Acquire a writable cache line for module output.

This is the cache-side companion of pixelpipe output computation. The caller already decided that the published output for hash is not immediately reusable and needs to be overwritten.

The cache then resolves how to provide that writable line:

• if an entry already exists at hash, that hash is already published and must not be overwritten. The caller must exact-hit it instead of recomputing,
• else, if allow_rekey_reuse is TRUE and reuse_hint still points to a live cacheline with the right size, that old cacheline is rekeyed to hash, write-locked, and returned,
• else, a new cacheline is created.

In all successful cases:

• the returned entry refcount is incremented,
• the returned entry is write-locked,
• and alloc may materialize the host buffer if requested.

The caller must later release the write lock and refcount from the same control flow.

Parameters

	cache	Pixelpipe cache.
	hash	Target output hash for the module output.
	size	Required buffer size in bytes.
	name	Debug label for the cache line.
	id	Owning pipeline id.
	alloc	Whether a host buffer must be materialized immediately.
	allow_rekey_reuse	Whether the cache may reuse the piece-local cached output line by rekeying it.
	reuse_hint	Snapshot of the previously attached piece cacheline metadata, or NULL.
[out]	data	Returned host pointer when available.
[out]	entry	Returned cache entry.

Returns

dt_dev_pixelpipe_cache_writable_status_t DT_DEV_PIXELPIPE_CACHE_WRITABLE_CREATED when creating a new entry, DT_DEV_PIXELPIPE_CACHE_WRITABLE_REKEYED when rekeying reuse_hint, DT_DEV_PIXELPIPE_CACHE_WRITABLE_EXACT_HIT when a published entry already exists at hash and the caller must exact-hit it, DT_DEV_PIXELPIPE_CACHE_WRITABLE_ERROR on error.

dt_dev_pixelpipe_cache_init()

gboolean dt_dev_pixelpipe_cache_init	(	size_t	max_memory,
		const gboolean	verbose,
		const gboolean	verbose_detail
	)

Reserve the cache's arena and start it.

constructs a new cache with given cache line count (entries) and float buffer entry size in bytes.

Parameters

[out]	returns	0 if fail to allocate mem cache.
	max_memory	arena size in bytes. A session constant: the orchestrator decides it from the resource plan and retries smaller on failure, which is resource policy.
	verbose	whether the cache traces at all (was -d pipecache).
	verbose_detail	whether it traces in detail (was -d verbose). Ignored when verbose is FALSE, matching the old two-level gate.

Both flags are read ONCE, here, from the session's debug flags by the orchestrator. The cache does not consult them at runtime: a cache that changes what it does halfway through a session because a global moved is harder to reason about than one told at startup, and it keeps the debug machinery out of a storage module.

Definition at line 2138 of file pixelpipe_cache.c.

References _free_cache_entry(), _memory_pressure_shedder(), _pixelpipe_cache, _verbose, _verbose_detail, dt_dev_pixelpipe_cache_t::arena, dt_dev_pixelpipe_cache_t::current_memory, dt_cache_arena_init(), dt_dev_pixelpipe_cache_flush_old(), dt_free, dt_free_gpointer(), dt_pthread_mutex_destroy(), dt_pthread_mutex_init(), dt_dev_pixelpipe_cache_t::entries, dt_dev_pixelpipe_cache_t::external_entries, FALSE, garbage_collection, dt_dev_pixelpipe_cache_t::hits, IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, dt_dev_pixelpipe_cache_t::max_memory, dt_dev_pixelpipe_cache_t::next_serial, pressure_shedding, dt_dev_pixelpipe_cache_t::queries, dt_dev_pixelpipe_cache_t::sys_available_est, dt_dev_pixelpipe_cache_t::sys_probe_time_us, dt_dev_pixelpipe_cache_t::sys_probe_valid, and TRUE.

Referenced by dt_init().

dt_dev_pixelpipe_cache_invalidate_hashes()

int dt_dev_pixelpipe_cache_invalidate_hashes	(	const uint64_t *	hashes,
		const size_t	count
	)

Invalidate cache lines matching an explicit list of hashes.

Entries which are not in use are removed immediately. Entries still referenced or locked are left untouched because they may be published backbuffers owned by another pipeline.

This targets shared cache states independently of the pipeline which created them, while preserving every cache line not named by hashes.

Parameters

cache	Pixelpipe cache to update.
hashes	Cache keys to invalidate.
count	Number of keys in hashes.

Returns

int Number of matching entries which could not be removed.

Definition at line 2626 of file pixelpipe_cache.c.

References _non_thread_safe_cache_remove(), _non_threadsafe_cache_get_entry(), _pixelpipe_cache, DT_PIXELPIPE_CACHE_HASH_INVALID, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, FALSE, IS_NULL_PTR, k, and dt_dev_pixelpipe_cache_t::lock.

Referenced by dt_dev_pixelpipe_process().

dt_dev_pixelpipe_cache_is_ready()

gboolean dt_dev_pixelpipe_cache_is_ready

(

void

)

Has the pixelpipe cache been initialised? Callers that run before dt_dev_pixelpipe_cache_init() succeeds, or after its cleanup, ask this rather than testing a handle they should not hold.

The application-wide pixelpipe cache singleton. DECLARED here because it is this module's object; BOUND by the orchestrator (darktable.c), so this header never needs to see the application struct.

Definition at line 96 of file pixelpipe_cache.c.

References _pixelpipe_cache, and IS_NULL_PTR.

Referenced by dt_cleanup(), and dt_init().

dt_dev_pixelpipe_cache_peek()

gboolean dt_dev_pixelpipe_cache_peek	(	const uint64_t	hash,
		void **	data,
		struct dt_pixel_cache_entry_t **	entry,
		const int	preferred_devid,
		void **	cl_mem_output
	)

Non-owning lookup of an existing cache line.

This does not create a new cache line and does not change reference counts or entry locks. Callers that need lifetime guarantees must retain the entry explicitly with dt_dev_pixelpipe_cache_ref_count_entry() and/or dt_dev_pixelpipe_cache_rdlock_entry().

If !IS_NULL_PTR(cl_mem_output), the lookup becomes authoritative for exact-hit consumers:

• write-locked / auto-destroy entries are rejected,
• host data is restored from cached device state when possible,
• device data is restored into cl_mem_output when requested,
• broken entries with neither authoritative RAM nor vRAM payload are removed.

Definition at line 2506 of file pixelpipe_cache.c.

References _cache_lookup_existing(), _cache_print, _cache_try_restore_device_payload(), _pixelpipe_cache, _trace_exact_hit(), dt_pixel_cache_entry_t::auto_destroy, DT_DEBUG_PIPECACHE, dt_dev_pixelpipe_cache_flag_auto_destroy(), dt_dev_pixelpipe_cache_remove(), dt_dev_pixelpipe_cache_restore_host_payload(), dt_pixel_cache_entry_get_data(), DT_PIXELPIPE_CACHE_HASH_INVALID, dt_pthread_rwlock_tryrdlock(), dt_pthread_rwlock_unlock(), FALSE, IS_NULL_PTR, dt_pixel_cache_entry_t::lock, and TRUE.

Referenced by dt_dev_pixelpipe_cache_peek_gui(), dt_dev_pixelpipe_process(), and dt_dev_retrieve_rawdetail_mask().

dt_dev_pixelpipe_cache_prepare_cl_input()

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
	)

Prepare the OpenCL input image corresponding to one cache-backed module input.

This centralizes the decision tree for:

• continuing from an already-live GPU payload,
• reopening or allocating a pinned input image from host RAM,
• taking the read lock required by true zero-copy buffers,
• and pushing host→device sync only when needed.

Parameters

	pipe	Current pixelpipe.
	module	Module being processed.
	input	Host input pointer.
[in,out]	cl_mem_input	OpenCL input image.
	roi_in	Buffer dimensions.
	in_bpp	Bytes per pixel.
	input_entry	Owning cache entry.
[out]	locked_input_entry	Returned cache entry that stayed read-locked for zero-copy safety.
	keep	Optional OpenCL buffer that must not be flushed during retry.

Returns

int 0 on success, 1 on failure.

dt_dev_pixelpipe_cache_print()

void dt_dev_pixelpipe_cache_print

(

void

)

print out cache lines/hashes (debug).

Definition at line 2980 of file pixelpipe_cache.c.

References _cache_print, _pixelpipe_cache, _verbose, dt_dev_pixelpipe_cache_t::current_memory, DT_DEBUG_PIPECACHE, dt_dev_pixelpipe_cache_t::entries, dt_dev_pixelpipe_cache_t::hits, dt_dev_pixelpipe_cache_t::max_memory, and dt_dev_pixelpipe_cache_t::queries.

Referenced by dt_dev_pixelpipe_process().

dt_dev_pixelpipe_cache_put_pinned_image()

void dt_dev_pixelpipe_cache_put_pinned_image	(	void *	host_ptr,
		struct dt_pixel_cache_entry_t *	entry_hint,
		void **	mem
	)

Release or cache a pinned OpenCL image acquired with dt_dev_pixelpipe_cache_get_pinned_image().

If the image is still a host-backed pinned allocation and an owning cache entry can be resolved, it is returned to that cache entry for reuse. Otherwise it is released.

Parameters

	cache	Pixelpipe cache.
	host_ptr	Host-backed image data.
	entry_hint	Optional owning cache entry for regular cache lines, or NULL.
[in,out]	mem	Pointer to the cl_mem handle (cleared on return).

Todo:

: is it safe to cache non-pinned vRAM buffers (aka no CL_MEM_USE_HOST_PTR in flags) ?

Definition at line 1032 of file pixelpipe_cache.c.

References _cache_print, _pixel_cache_clmem_put(), _verbose, _verbose_detail, DT_DEBUG_OPENCL, IS_NULL_PTR, and state.

Referenced by _blend_layer_over_input_cl().

dt_dev_pixelpipe_cache_rdlock_entry()

void dt_dev_pixelpipe_cache_rdlock_entry	(	gboolean	lock,
		struct dt_pixel_cache_entry_t *	entry
	)

Lock or release the read lock on the entry.

Parameters

cache
lock	TRUE to lock, FALSE to release
entry	The cache entry object to lock.

Definition at line 2802 of file pixelpipe_cache.c.

References _pixel_cache_message(), dt_pthread_rwlock_rdlock(), dt_pthread_rwlock_unlock(), dt_pixel_cache_entry_t::lock, lock, and TRUE.

Referenced by _build_preview_fallback_surface(), _draw_preview_fallback(), _lib_navigation_draw_callback(), _pixelpipe_pick_from_image(), _process_histogram(), _process_vectorscope(), _refresh_preview_cursor_sample(), _refresh_preview_module_histogram_for_hash(), _sample_picker_from_cache(), color_picker_apply(), dt_dev_get_raster_mask(), dt_dev_pixelpipe_cache_prepare_cl_input(), dt_dev_pixelpipe_process_rec(), dt_dev_render_locked_surface(), dt_dev_resync_mipmap_cache(), dt_drawlayer_cache_patch_rdlock(), dt_drawlayer_cache_patch_rdunlock(), dt_imageio_export_with_flags(), dt_iop_autoset_advance(), gui_post_expose(), mouse_moved(), pixelpipe_process_on_CPU(), pixelpipe_process_on_GPU(), scrolled(), and update_histogram().

dt_dev_pixelpipe_cache_ref_count_entry()

void dt_dev_pixelpipe_cache_ref_count_entry	(	gboolean	lock,
		struct dt_pixel_cache_entry_t *	entry
	)

Increase/Decrease the reference count on the cache line as to prevent LRU item removal. This function should be called within a read/write lock-protected section to avoid changing an entry while or after it is deleted in parallel.

WARNING: cache entries whose reference count is greater than 0 will never be deleted from cache.

Parameters

cache
lock	TRUE to lock, FALSE to unlock

Definition at line 2769 of file pixelpipe_cache.c.

References _non_thread_safe_cache_ref_count_entry(), _pixelpipe_cache, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::lock, and lock.

Referenced by _abort_module_shutdown_cleanup(), _blend_layer_over_input_cl(), _cache_try_rekey_reuse_locked(), _develop_cacheline_ready_callback(), _develop_history_resync_callback(), _refresh_global_histogram_backbuf_for_hash(), _refresh_preview_cursor_sample(), _refresh_preview_module_histogram_for_hash(), _retain_base_patch_loaded_ref(), _retain_base_patch_stroke_ref(), _sample_picker_from_cache(), _update_backbuf_cache_reference(), color_picker_apply(), dt_dev_get_raster_mask(), dt_dev_pixelpipe_cache_flush_host_pinned_image(), dt_dev_pixelpipe_cache_unref_hash(), dt_dev_pixelpipe_process_rec(), dt_dev_resync_mipmap_cache(), dt_dev_retrieve_rawdetail_mask(), dt_develop_blend_process(), dt_develop_blend_process_cl(), dt_drawlayer_cache_patch_alloc_shared(), dt_drawlayer_cache_patch_clear(), dt_drawlayer_release_all_base_patch_extra_refs(), dt_imageio_export_with_flags(), dt_iop_autoset_advance(), gui_cleanup(), gui_focus(), gui_post_expose(), invalidate_luminance_cache(), mouse_moved(), process(), scrolled(), and update_histogram().

dt_dev_pixelpipe_cache_ref_entry_by_hash()

gboolean dt_dev_pixelpipe_cache_ref_entry_by_hash	(	const uint64_t	hash,
		void **	data,
		struct dt_pixel_cache_entry_t **	entry
	)

Resolve and retain an existing cache entry by hash.

This is the race-free counterpart to dt_dev_pixelpipe_cache_peek() for GUI code that needs to keep a cacheline past the lookup call. The cache lock is held while the entry is found and its refcount is incremented, so normal cache eviction cannot destroy the returned entry before the caller takes its own read lock.

The function never creates or allocates a cache entry. Release a successful result with dt_dev_pixelpipe_cache_ref_count_entry(cache, FALSE, entry).

Parameters

cache	Pixelpipe cache.
hash	Cacheline hash to resolve.
data	Returned current host buffer pointer, if requested.
entry	Returned retained cache entry, if requested.

Returns

TRUE when an existing non-auto-destroy entry was retained.

Definition at line 323 of file pixelpipe_cache.c.

References _non_thread_safe_cache_ref_count_entry(), _non_threadsafe_cache_get_entry(), _observe_read(), _pixelpipe_cache, _pixelpipe_cache_finalize_entry(), dt_pixel_cache_entry_t::auto_destroy, DT_PIXELPIPE_CACHE_HASH_INVALID, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, FALSE, dt_dev_pixelpipe_cache_t::hits, dt_pixel_cache_entry_t::hits, IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, dt_dev_pixelpipe_cache_t::queries, dt_pixel_cache_entry_t::size, and TRUE.

Referenced by _develop_cacheline_ready_callback(), _develop_history_resync_callback(), dt_dev_get_raster_mask(), dt_dev_pixelpipe_process(), dt_dev_pixelpipe_process_rec(), dt_dev_resync_mipmap_cache(), dt_imageio_export_with_flags(), and gui_focus().

dt_dev_pixelpipe_cache_ref_entry_for_host_ptr()

struct dt_pixel_cache_entry_t * dt_dev_pixelpipe_cache_ref_entry_for_host_ptr

(

void *

host_ptr

)

Resolve and retain the cache entry owning a host pointer.

This helper searches both regular and external pixelpipe cache tables for the entry whose host buffer pointer exactly matches host_ptr.

On success it increments the entry refcount before returning, so callers can safely use the entry across asynchronous OpenCL operations. Release it with: dt_dev_pixelpipe_cache_ref_count_entry(cache, FALSE, entry).

Parameters

cache	Pixelpipe cache.
host_ptr	Host buffer pointer to resolve.

Returns

dt_pixel_cache_entry_t* Owning cache entry with retained refcount, or NULL.

Definition at line 1542 of file pixelpipe_cache.c.

References _cache_entry_for_host_ptr_locked(), _non_thread_safe_cache_ref_count_entry(), _pixelpipe_cache, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, and TRUE.

Referenced by _blend_layer_over_input_cl(), dt_drawlayer_cache_ensure_mask_buffer(), and dt_drawlayer_cache_ensure_process_patch_buffer().

dt_dev_pixelpipe_cache_rekey()

int dt_dev_pixelpipe_cache_rekey	(	const uint64_t	old_hash,
		const uint64_t	new_hash,
		struct dt_pixel_cache_entry_t *	entry
	)

Change the hash/key of an existing cache line in place, without freeing, reallocating or invalidating the underlying entry.

This is useful when a cache line remains the authoritative buffer but the caller needs its identity to follow a new logical snapshot (for example a new module-parameter hash). The entry contents, locks, refcount and storage are preserved; only the hash-table key and entry->hash are updated.

The operation fails if:

• the source entry cannot be found,
• or another different entry already exists at new_hash.

Parameters

cache
old_hash	Current key of the entry.
new_hash	Desired new key.
entry	Optional direct entry reference. May be NULL.

Returns

int 0 on success, 1 on error.

Definition at line 2890 of file pixelpipe_cache.c.

References _cache_debug_module_name(), _cache_print, _non_threadsafe_cache_get_entry(), _observe_rekey(), _pixelpipe_cache, dt_pixel_cache_entry_t::auto_destroy, dt_pixel_cache_entry_t::cl_mem_list, dt_pixel_cache_entry_t::cl_mem_lock, dt_pixel_cache_entry_t::data, dt_atomic_get_int(), DT_DEBUG_PIPECACHE, dt_dev_pixelpipe_cache_flush_entry_clmem(), dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, dt_pixel_cache_entry_t::hash, IS_NULL_PTR, dt_dev_pixelpipe_cache_t::lock, dt_pixel_cache_entry_t::refcount, and dt_pixel_cache_entry_t::serial.

Referenced by _rekey_shared_base_patch().

dt_dev_pixelpipe_cache_release_cl_buffer()

void dt_dev_pixelpipe_cache_release_cl_buffer	(	void **	cl_mem_buffer,
		dt_pixel_cache_entry_t *	cache_entry,
		void *	host_ptr,
		const gboolean	cache_device
	)

Release or cache an OpenCL image associated with one cache entry.

Pinned host-backed images and reusable device-only images are returned to the cache entry when possible. Otherwise the OpenCL object is released immediately and any stale cache bookkeeping for it is dropped.

Parameters

[in,out]	cl_mem_buffer	Pointer to the cl_mem handle. Cleared on return.
	entry	Owning cache entry, or NULL when the buffer is not cache-backed.
	host_ptr	Host pointer backing pinned images, or NULL for device-only images.
	cache_device	Whether device-only images may be kept for reuse.

Release or cache an OpenCL image associated with one cache entry.

Parameters

[in,out]	cl_mem_buffer	Pointer to a cl_mem stored as void*.
	cache_entry	Pixelpipe cache entry the host pointer belongs to (may be NULL).
	host_ptr	Host pointer backing the OpenCL image (may be NULL).
	cache_device	Allow caching pure device-side buffers for scratch reuse.

This helper is a single point of truth for OpenCL image lifetime management in the pixelpipe:

• If the image is host-backed (CL_MEM_USE_HOST_PTR) and we have both cache_entry and host_ptr, we put it in the cache entry's cl_mem_list for reuse.
• Otherwise, we release it immediately.
• Pure device allocations may also be cached for scratch-pad reuse. When those cached cl_mem objects are later evicted, the cache layer is responsible for materializing host RAM first if no authoritative host buffer exists yet.

Additionally, when we release an image, we must ensure there is no stale pointer in cl_mem_list (for example, if some earlier path cached it and we are now deciding to free it). We call _pixel_cache_clmem_remove() before releasing to keep the cache bookkeeping coherent.

Definition at line 1221 of file pixelpipe_cache.c.

References _pixel_cache_clmem_put(), _pixel_cache_clmem_remove(), dt_opencl_release_mem_object(), and IS_NULL_PTR.

Referenced by _abort_module_shutdown_cleanup(), _blend_layer_over_input_cl(), _drawlayer_acquire_source_image(), _gpu_early_cpu_fallback_if_unsupported(), and pixelpipe_process_on_GPU().

dt_dev_pixelpipe_cache_remove()

int dt_dev_pixelpipe_cache_remove	(	const gboolean	force,
		struct dt_pixel_cache_entry_t *	entry
	)

Arbitrarily remove the cache entry matching hash. Entries having a reference count > 0 (inter-thread locked) or being having their read/write lock locked will be ignored. If force is TRUE, we ignore reference count, but not locks.

Parameters

cache
force

Definition at line 392 of file pixelpipe_cache.c.

References _non_thread_safe_cache_remove(), _pixelpipe_cache, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, error(), and dt_dev_pixelpipe_cache_t::lock.

Referenced by _abort_module_shutdown_cleanup(), dt_dev_pixelpipe_cache_peek(), dt_dev_pixelpipe_process_rec(), dt_develop_blend_process(), dt_develop_blend_process_cl(), process(), and process_cl().

dt_dev_pixelpipe_cache_restore_cl_buffer()

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
	)

Resynchronize one OpenCL input payload back into its cache-backed host buffer.

Parameters

pipe	Current pixelpipe.
input	Host cache buffer.
cl_mem_input	OpenCL image holding the authoritative pixels.
roi_in	Buffer dimensions.
module	Module for debug logs.
in_bpp	Bytes per pixel.
input_entry	Owning cache entry.
message	Human-readable sync context.

Returns

float* input on success, NULL on failure.

dt_dev_pixelpipe_cache_restore_host_payload()

gboolean dt_dev_pixelpipe_cache_restore_host_payload	(	struct dt_pixel_cache_entry_t *	entry,
		int	preferred_devid,
		void **	data
	)

Materialize a host payload for a live cache entry from its cached device payload.

Recursive pixelpipe stages reopen transient upstream cache entries directly, before those entries become valid exact-hits. When such an entry only carries a GPU payload, the caller may still need a host pointer for CPU fallback or for a non-OpenCL module. This helper keeps the recovery local to the cache layer:

• allocate host RAM for entry when needed,
• copy the most relevant cached device payload back to host,
• return the restored host pointer through data.

The function leaves the cache entry owned by the caller. It does not change refcounts.

Parameters

	cache	Pixelpipe cache.
	entry	Live cache entry to restore.
	preferred_devid	Preferred OpenCL device id, or -1 for any.
[out]	data	Restored host pointer, or NULL on failure.

Returns

gboolean TRUE when host data is available after the call, FALSE otherwise.

Definition at line 2486 of file pixelpipe_cache.c.

References _cache_entry_materialize_host_data(), _pixelpipe_cache, dt_pixel_cache_entry_get_data(), FALSE, IS_NULL_PTR, and TRUE.

Referenced by dt_dev_pixelpipe_cache_peek(), and dt_dev_pixelpipe_process_rec().

dt_dev_pixelpipe_cache_return_cl_payload()

void dt_dev_pixelpipe_cache_return_cl_payload	(	struct dt_pixel_cache_entry_t *	entry,
		void *	mem
	)

Return a borrowed cached OpenCL payload to its cache entry.

Parameters

entry	Cache entry owning the payload.
mem	Borrowed cl_mem to release back to cache bookkeeping.

Definition at line 838 of file pixelpipe_cache.c.

References dt_pixel_cache_entry_t::cl_mem_list, dt_pixel_cache_entry_t::cl_mem_lock, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), IS_NULL_PTR, and void().

Referenced by _gpu_early_cpu_fallback_if_unsupported(), and pixelpipe_process_on_GPU().

dt_dev_pixelpipe_cache_set_handlers()

void dt_dev_pixelpipe_cache_set_handlers	(	dt_pixelpipe_cache_warn_handler_t	warn,
		dt_pixelpipe_cache_ready_handler_t	ready,
		const dt_pixelpipe_cache_observer_t *	observer
	)

Install the handlers. Call once, from the orchestrator, before any pipe runs.

Parameters

warn	may be NULL – the warning is then dropped, not printed somewhere else.
ready	may be NULL.
observer	BORROWED, not copied: it must outlive the cache. Pass NULL to detach.

Definition at line 107 of file pixelpipe_cache.c.

References _observer, _ready_handler, and _warn_handler.

Referenced by dt_init().

dt_dev_pixelpipe_cache_sync_cl_buffer()

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
	)

Synchronize between host memory and a pinned OpenCL image.

Parameters

devid	OpenCL device id.
host_ptr	Host pointer to read from / write to.
cl_mem_buffer	OpenCL image.
roi	Buffer dimensions.
cl_mode	CL_MAP_WRITE for host→device, CL_MAP_READ for device→host.
bpp	Bytes per pixel.
module	Module for debug logs.
message	Human-readable sync context.

Returns

int 0 on success, 1 on failure.

dt_dev_pixelpipe_cache_unref_hash()

void dt_dev_pixelpipe_cache_unref_hash

(

const uint64_t

hash

)

Find the entry matching hash, and decrease its ref_count if found.

Parameters

cache
hash

Definition at line 2876 of file pixelpipe_cache.c.

References _non_threadsafe_cache_get_entry(), _pixelpipe_cache, dt_dev_pixelpipe_cache_ref_count_entry(), DT_PIXELPIPE_CACHE_HASH_INVALID, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), dt_dev_pixelpipe_cache_t::entries, FALSE, dt_dev_pixelpipe_cache_t::lock, and dt_dev_pixelpipe_cache_t::queries.

Referenced by _clear_histogram_backbuf(), _refresh_global_histogram_backbuf_for_hash(), _studio_dev_teardown(), _update_backbuf_cache_reference(), dt_dev_clear_rawdetail_mask(), dt_dev_pixelpipe_cleanup(), dt_dev_pixelpipe_process(), and leave().

dt_dev_pixelpipe_cache_wrlock_entry()

void dt_dev_pixelpipe_cache_wrlock_entry	(	gboolean	lock,
		struct dt_pixel_cache_entry_t *	entry
	)

Lock or release the write lock on the entry.

Parameters

cache
lock	TRUE to lock, FALSE to release

Definition at line 2779 of file pixelpipe_cache.c.

References _pixel_cache_message(), _ready_handler, DT_PIXELPIPE_CACHE_HASH_INVALID, dt_pthread_rwlock_unlock(), dt_pthread_rwlock_wrlock(), dt_pixel_cache_entry_t::hash, dt_pixel_cache_entry_t::lock, lock, dt_pixel_cache_entry_t::producer_node_key, and TRUE.

Referenced by _cache_entry_materialize_host_data(), _cache_try_rekey_reuse_locked(), _gpu_early_cpu_fallback_if_unsupported(), _gpu_init_input(), _pixelpipe_cache_create_entry_locked(), dt_dev_pixelpipe_cache_get(), dt_dev_pixelpipe_cache_restore_cl_buffer(), dt_dev_pixelpipe_process_rec(), dt_develop_blend_process(), dt_develop_blend_process_cl(), dt_drawlayer_cache_patch_alloc_shared(), dt_drawlayer_cache_patch_wrlock(), dt_drawlayer_cache_patch_wrunlock(), process(), and process_cl().

dt_pixel_cache_alloc()

void * dt_pixel_cache_alloc

(

struct dt_pixel_cache_entry_t *

entry

)

Actually allocate the memory buffer attached to the cache entry once you create it with dt_dev_pixelpipe_cache_get(). Sizes and everything are already saved in the entry, and the cache will have the needed space reserved.

Parameters

cache
entry	the cache entry

Returns

void* Pointer to the allocated data buffer.

Definition at line 1857 of file pixelpipe_cache.c.

References _arena_alloc_with_defrag(), _log_arena_allocation_failure(), _pixelpipe_cache, dt_pixel_cache_entry_t::data, FALSE, dt_pixel_cache_entry_t::hash, IS_NULL_PTR, dt_pixel_cache_entry_t::name, and dt_pixel_cache_entry_t::size.

Referenced by _cache_entry_materialize_host_data(), _gpu_early_cpu_fallback_if_unsupported(), _gpu_init_input(), dt_dev_pixelpipe_cache_get(), dt_dev_pixelpipe_cache_get_writable(), dt_pixel_cache_new_entry(), pixelpipe_process_on_CPU(), and pixelpipe_process_on_GPU().

dt_pixel_cache_entry_get_data()

void * dt_pixel_cache_entry_get_data

(

struct dt_pixel_cache_entry_t *

entry

)

Peek the host data pointer of a cache entry without allocating.

Definition at line 1876 of file pixelpipe_cache.c.

References dt_pixel_cache_entry_t::data.

Referenced by _cache_entry_materialize_host_data(), color_picker_apply(), dt_dev_lock_pipe_surface(), dt_dev_pixelpipe_cache_gpu_device_buffer(), dt_dev_pixelpipe_cache_peek(), dt_dev_pixelpipe_cache_restore_host_payload(), dt_dev_pixelpipe_process_rec(), gui_post_expose(), mouse_moved(), pixelpipe_process_on_CPU(), pixelpipe_process_on_GPU(), scrolled(), and update_histogram().

dt_pixel_cache_entry_get_size()

size_t dt_pixel_cache_entry_get_size

(

struct dt_pixel_cache_entry_t *

entry

)

Peek the size (in bytes) reserved for the host buffer of a cache entry.

The pixelpipe cache treats dt_pixel_cache_entry_t as an internal/private structure. External users (such as the pixelpipe implementation) should not access struct fields directly.

This accessor is intentionally "peek-only": it does not allocate and it does not change ownership.

Definition at line 1881 of file pixelpipe_cache.c.

References dt_pixel_cache_entry_t::size.

Referenced by _update_backbuf_cache_reference(), dt_dev_lock_pipe_surface(), and dt_dev_pixelpipe_process_rec().

dt_pixelpipe_cache_alloc_align_cache_impl()

void * dt_pixelpipe_cache_alloc_align_cache_impl	(	size_t	size,
		int	id,
		const char *	name
	)

Allocate aligned memory tracked by the pixelpipe cache. This allows LRU cache entries to be evicted if needed to make room.

Parameters

cache	Pixelpipe cache to manage.
size	Buffer size in bytes.
id	Pipeline type owning the buffer.
name	Human-readable name.

Returns

void* Pointer to the allocated buffer, or NULL on failure.

Definition at line 1919 of file pixelpipe_cache.c.

dt_pixelpipe_cache_free_align_cache()

void dt_pixelpipe_cache_free_align_cache	(	void **	mem,
		const char *	message
	)

Free aligned memory allocated with dt_pixelpipe_cache_alloc_align_cache.

Parameters

cache	Pixelpipe cache to manage.
mem	Pointer to the buffer pointer. Set to NULL on successful free.

Definition at line 1968 of file pixelpipe_cache.c.

dt_pixelpipe_cache_get_largest_free_run()

size_t dt_pixelpipe_cache_get_largest_free_run

(

void

)

Definition at line 1746 of file pixelpipe_cache.c.

References _arena_stats_bytes(), _pixelpipe_cache, dt_pthread_mutex_lock(), dt_pthread_mutex_unlock(), and dt_dev_pixelpipe_cache_t::lock.

Referenced by _default_process_tiling_ptp(), _default_process_tiling_roi(), and dt_tiling_piece_fits_host_memory().

dt_pixelpipe_cache_set_current_module()

const char * dt_pixelpipe_cache_set_current_module

(

const char *

module

)

Set the current module name for cache diagnostics (thread-local).

Parameters

module

Module op name or NULL to clear.

Returns

const char* Previous module name.

Definition at line 177 of file pixelpipe_cache.c.

References dt_pixelpipe_cache_current_module.

Referenced by dt_dev_pixelpipe_process_rec().