dzl-task-cache: Dazzle Reference Manual

## dzl-task-cache dzl-task-cache |

## Functions

void | (*DzlTaskCacheCallback) ()
DzlTaskCache * | dzl_task_cache_new ()
void | dzl_task_cache_set_name ()
void | dzl_task_cache_get_async ()
gpointer | dzl_task_cache_get_finish ()
gboolean | dzl_task_cache_evict ()
void | dzl_task_cache_evict_all ()
gpointer | dzl_task_cache_peek ()
GPtrArray * | dzl_task_cache_get_values ()

## Properties

gpointer | key-copy-func | Write / Construct Only
gpointer | key-destroy-func | Write / Construct Only
gpointer | key-equal-func | Write / Construct Only
gpointer | key-hash-func | Write / Construct Only
gpointer | populate-callback | Write / Construct Only
gpointer | populate-callback-data | Write / Construct Only
gpointer | populate-callback-data-destroy | Write / Construct Only
gint64 | time-to-live | Write / Construct Only
gpointer | value-copy-func | Write / Construct Only
gpointer | value-destroy-func | Write / Construct Only

## Types and Values

#define | DZL_TYPE_TASK_CACHE
| DzlTaskCache

## Object Hierarchy

        GObject
        ╰── DzlTaskCache

## Description

## Functions

### DzlTaskCacheCallback ()

    void
    (*DzlTaskCacheCallback) (DzlTaskCache *self,
                             gconstpointer key,
                             GTask *task,
                             gpointer user_data);

DzlTaskCacheCallback is the prototype for a function to be executed to populate an item in the cache.

This function will be executed when a fault (cache miss) occurs from a caller requesting an item from the cache.

The callee may complete the operation asynchronously, but MUST return either a GObject using `g_task_return_pointer()` or a GError using `g_task_return_error()` or `g_task_return_new_error()`.

#### Parameters

self | An DzlTaskCache. |
key | the key to fetch |
task | the task to be completed |
user_data | user_data registered at initialization. |

### dzl_task_cache_new ()

    DzlTaskCache *
    dzl_task_cache_new (GHashFunc key_hash_func,
                        GEqualFunc key_equal_func,
                        GBoxedCopyFunc key_copy_func,
                        GBoxedFreeFunc key_destroy_func,
                        GBoxedCopyFunc value_copy_func,
                        GBoxedFreeFunc value_free_func,
                        gint64 time_to_live_msec,
                        DzlTaskCacheCallback populate_callback,
                        gpointer populate_callback_data,
                        GDestroyNotify populate_callback_data_destroy);

[skip]

### dzl_task_cache_set_name ()

    void
    dzl_task_cache_set_name (DzlTaskCache *self,
                             const gchar *name);

### dzl_task_cache_get_async ()

    void
    dzl_task_cache_get_async (DzlTaskCache *self,
                              gconstpointer key,
                              gboolean force_update,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

### dzl_task_cache_get_finish ()

    gpointer
    dzl_task_cache_get_finish (DzlTaskCache *self,
                               GAsyncResult *result,
                               GError **error);

Finish a call to `dzl_task_cache_get_async()`.

#### Returns

The result from the cache.

[transfer full]

### dzl_task_cache_evict ()

    gboolean
    dzl_task_cache_evict (DzlTaskCache *self,
                          gconstpointer key);

### dzl_task_cache_evict_all ()

    void
    dzl_task_cache_evict_all (DzlTaskCache *self);

### dzl_task_cache_peek ()

    gpointer
    dzl_task_cache_peek (DzlTaskCache *self,
                         gconstpointer key);

Peeks to see `key` is contained in the cache and returns the matching GObject if it does.

The reference count of the resulting GObject is not incremented. For that reason, it is important to remember that this function may only be called from the main thread.

#### Parameters

self | An DzlTaskCache |
key | The key for the cache |

#### Returns

A GObject or `NULL` if the key was not found in the cache.

[type GObject.Object][nullable][transfer none]

### dzl_task_cache_get_values ()

    GPtrArray *
    dzl_task_cache_get_values (DzlTaskCache *self);

Gets all the values in the cache.

The caller owns the resulting GPtrArray, which itself owns a reference to the children.

[skip]

#### Returns

The values.

[transfer container]

## Types and Values

### DZL_TYPE_TASK_CACHE

    #define DZL_TYPE_TASK_CACHE (dzl_task_cache_get_type())

### DzlTaskCache

    typedef struct _DzlTaskCache DzlTaskCache;

## Property Details

### The `“key-copy-func”` property

      “key-copy-func”            gpointer

Key Copy Func.

Owner: DzlTaskCache

Flags: Write / Construct Only

### The `“key-destroy-func”` property

      “key-destroy-func”         gpointer

Key Destroy Func.

Owner: DzlTaskCache

Flags: Write / Construct Only

### The `“key-equal-func”` property

      “key-equal-func”           gpointer

Key Equal Func.

Owner: DzlTaskCache

Flags: Write / Construct Only

### The `“key-hash-func”` property

      “key-hash-func”            gpointer

Key Hash Func.

Owner: DzlTaskCache

Flags: Write / Construct Only

### The `“populate-callback”` property

      “populate-callback”        gpointer

Populate Callback.

Owner: DzlTaskCache

Flags: Write / Construct Only

### The `“populate-callback-data”` property

      “populate-callback-data”   gpointer

Populate Callback Data.

Owner: DzlTaskCache

Flags: Write / Construct Only

### The `“populate-callback-data-destroy”` property

      “populate-callback-data-destroy” gpointer

Populate Callback Data Destroy.

Owner: DzlTaskCache

Flags: Write / Construct Only

### The `“time-to-live”` property

      “time-to-live”             gint64

This is the number of milliseconds before an item should be evicted from the cache.

A value of zero indicates no eviction.

Owner: DzlTaskCache

Flags: Write / Construct Only

Allowed values: >= 0

Default value: 30000

### The `“value-copy-func”` property

      “value-copy-func”          gpointer

Value Copy Func.

Owner: DzlTaskCache

Flags: Write / Construct Only

### The `“value-destroy-func”` property

      “value-destroy-func”       gpointer

Value Destroy Func.

Owner: DzlTaskCache

Flags: Write / Construct Only