defaults.h

Go to the documentation of this file.

/*
 * SPDX-License-Identifier: MIT
 * Copyright (c) 2026 Jeremiah van Oosten
 *
 * vgl defaults: a thread pool, a filesystem reader, an HTTP reader and a disk cache that
 * implement the task and I/O interfaces of vgl/foundation.h, so that the common case needs no
 * callbacks (design document, section 7.5). This module is optional and linked separately, as
 * vgl_defaults: unlike the core library, it creates threads, opens files and connects to servers.
 *
 * A minimal host:
 *
 *     vgl_thread_pool* pool;
 *     vgl_thread_pool_create(NULL, &pool);
 *     vgl_file_reader_create_info reader_info = {.struct_size = sizeof(reader_info)};
 *     reader_info.pool = pool;
 *     vgl_file_reader* reader;
 *     vgl_file_reader_create(&reader_info, &reader);
 *
 *     vgl_task_interface tasks;
 *     vgl_io_interface io;
 *     vgl_thread_pool_task_interface_get(pool, &tasks);
 *     vgl_file_reader_io_interface_get(reader, &io);
 *     vgl_context_create_info info = {.struct_size = sizeof(info)};
 *     info.tasks = &tasks;
 *     info.io = &io;
 *     ...
 *     vgl_context_destroy(context);
 *     vgl_file_reader_destroy(reader);
 *     vgl_thread_pool_destroy(pool);
 *
 * Destroy the context first, then the reader, then the pool.
 */
#ifndef VGL_DEFAULTS_H
#define VGL_DEFAULTS_H
 
#include <vgl/base.h>
#include <vgl/foundation.h>
 
/* Symbol visibility of the defaults library, which is shared when vgl is. */
#if defined(VGL_SHARED)
#    if defined(_WIN32)
#        if defined(VGL_DEFAULTS_BUILDING)
#            define VGL_DEFAULTS_API __declspec(dllexport)
#        else
#            define VGL_DEFAULTS_API __declspec(dllimport)
#        endif
#    else
#        define VGL_DEFAULTS_API __attribute__((visibility("default")))
#    endif
#else
#    define VGL_DEFAULTS_API
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ---------------------------------------------------------------------------------------- */
/* Thread pool                                                                              */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_thread_pool vgl_thread_pool;
 
typedef struct vgl_thread_pool_create_info
{
    uint32_t struct_size;
    uint32_t thread_count;
    const vgl_allocator_interface* allocator;
    VGL_POINTER_PADDING(allocator_padding)
} vgl_thread_pool_create_info;
 
VGL_DEFAULTS_API vgl_result vgl_thread_pool_create(const vgl_thread_pool_create_info* info,
                                                   vgl_thread_pool** out_pool);
 
VGL_DEFAULTS_API vgl_result vgl_thread_pool_destroy(vgl_thread_pool* pool);
 
VGL_DEFAULTS_API vgl_result vgl_thread_pool_task_interface_get(vgl_thread_pool* pool,
                                                               vgl_task_interface* out_interface);
 
/* ---------------------------------------------------------------------------------------- */
/* File reader                                                                              */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_file_reader vgl_file_reader;
 
typedef struct vgl_file_reader_create_info
{
    uint32_t struct_size;
    uint32_t reserved;
    vgl_thread_pool* pool;
    VGL_POINTER_PADDING(pool_padding)
    const vgl_allocator_interface* allocator;
    VGL_POINTER_PADDING(allocator_padding)
} vgl_file_reader_create_info;
 
VGL_DEFAULTS_API vgl_result vgl_file_reader_create(const vgl_file_reader_create_info* info,
                                                   vgl_file_reader** out_reader);
 
VGL_DEFAULTS_API vgl_result vgl_file_reader_destroy(vgl_file_reader* reader);
 
VGL_DEFAULTS_API vgl_result vgl_file_reader_io_interface_get(vgl_file_reader* reader,
                                                             vgl_io_interface* out_interface);
 
/* ---------------------------------------------------------------------------------------- */
/* HTTP reader                                                                              */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_http_reader vgl_http_reader;
 
typedef struct vgl_http_reader_create_info
{
    uint32_t struct_size;
    uint32_t max_connection_count;
    const vgl_allocator_interface* allocator;
    VGL_POINTER_PADDING(allocator_padding)
    const vgl_io_interface* fallback;
    VGL_POINTER_PADDING(fallback_padding)
    double timeout;
    const char* user_agent;
    VGL_POINTER_PADDING(user_agent_padding)
} vgl_http_reader_create_info;
 
VGL_DEFAULTS_API vgl_result vgl_http_reader_create(const vgl_http_reader_create_info* info,
                                                   vgl_http_reader** out_reader);
 
VGL_DEFAULTS_API vgl_result vgl_http_reader_destroy(vgl_http_reader* reader);
 
VGL_DEFAULTS_API vgl_result vgl_http_reader_io_interface_get(vgl_http_reader* reader,
                                                             vgl_io_interface* out_interface);
 
/* ---------------------------------------------------------------------------------------- */
/* Disk cache                                                                               */
/* ---------------------------------------------------------------------------------------- */
 
typedef struct vgl_disk_cache vgl_disk_cache;
 
typedef struct vgl_disk_cache_create_info
{
    uint32_t struct_size;
    uint32_t reserved;
    const char* directory;
    VGL_POINTER_PADDING(directory_padding)
    const vgl_io_interface* source;
    VGL_POINTER_PADDING(source_padding)
    uint64_t budget;
    vgl_thread_pool* pool;
    VGL_POINTER_PADDING(pool_padding)
    const vgl_allocator_interface* allocator;
    VGL_POINTER_PADDING(allocator_padding)
} vgl_disk_cache_create_info;
 
typedef struct vgl_disk_cache_statistics
{
    uint32_t struct_size;
    uint32_t reserved;
    uint64_t hits;         
    uint64_t misses;       
    uint64_t offline_hits; 
    uint64_t entries;      
    uint64_t bytes;        
    uint64_t budget;       
    uint64_t evictions;    
} vgl_disk_cache_statistics;
 
VGL_DEFAULTS_API vgl_result vgl_disk_cache_create(const vgl_disk_cache_create_info* info,
                                                  vgl_disk_cache** out_cache);
 
VGL_DEFAULTS_API vgl_result vgl_disk_cache_destroy(vgl_disk_cache* cache);
 
VGL_DEFAULTS_API vgl_result vgl_disk_cache_io_interface_get(vgl_disk_cache* cache,
                                                            vgl_io_interface* out_interface);
 
VGL_DEFAULTS_API vgl_result
vgl_disk_cache_statistics_get(vgl_disk_cache* cache, vgl_disk_cache_statistics* out_statistics);
 
VGL_DEFAULTS_API vgl_result vgl_disk_cache_clear(vgl_disk_cache* cache);
 
#ifdef __cplusplus
}
#endif
 
#endif /* VGL_DEFAULTS_H */