Home /Modules/compression/sleela_compressor_plugin.h

sleela_compressor_plugin.h

compression/include/sleela_compressor_plugin.h · 147 line(s) · c

#ifndef SLEELA_COMPRESSOR_PLUGIN_H
#define SLEELA_COMPRESSOR_PLUGIN_H

/*
 * SLeeLa compressor plugin interface.
 *
 * Every individual algorithm under compression/compressors/<name>/ implements
 * this one small vtable. The Compression Manager
 * (sleela_compression_manager.h) loads these plugins, tracks their lifecycle,
 * and dispatches probe/compress/decompress calls to them. SLeeLa never links
 * an individual compressor directly -- it calls the manager, and the manager
 * calls the plugin. This keeps every algorithm interchangeable and lets one be
 * loaded or unloaded at runtime without touching the caller.
 *
 * A compressor here is metadata + an explicit capability contract. A plugin
 * whose backend is not present reports its state (e.g.
 * SLEELA_COMPRESSION_BACKEND) and fails cleanly from compress/decompress rather
 * than faking success.
 */

#include <stddef.h>
#include <stdint.h>

#include "sleela_compression.h"   /* sleela_compressor_id, sleela_compressor_state */

#ifdef __cplusplus
extern "C" {
#endif

/* Result codes shared by every plugin entry point and by the manager. */
typedef enum sleela_compression_result {
    SLEELA_COMPRESSION_OK = 0,              /* success                                        */
    SLEELA_COMPRESSION_ERR_UNSUPPORTED = -1,/* capability not available (e.g. backend absent) */
    SLEELA_COMPRESSION_ERR_INVALID = -2,    /* bad arguments                                  */
    SLEELA_COMPRESSION_ERR_FORMAT = -3,     /* input is not this algorithm's format           */
    SLEELA_COMPRESSION_ERR_IO = -4,         /* read/write/allocation failure                  */
    SLEELA_COMPRESSION_ERR_STATE = -5,      /* plugin not loaded / wrong lifecycle state      */
    SLEELA_COMPRESSION_ERR_BUFFER = -6      /* output buffer too small (see required bytes)   */
} sleela_compression_result;

/*
 * A byte buffer the plugins operate over. Compression and decompression are
 * byte-in / byte-out; `data` points at `len` bytes. For a decompress result the
 * plugin owns `data` until unload() or a plugin-provided free, exactly like the
 * codec PCM boundary owns decoded samples.
 */
typedef struct sleela_byte_buffer {
    uint8_t *data;   /* bytes (ownership documented per entry point)  */
    size_t   len;    /* number of valid bytes                          */
} sleela_byte_buffer;

/* Opaque per-instance state a plugin may allocate in load() and free in unload(). */
typedef struct sleela_compressor_instance sleela_compressor_instance;

/*
 * The compressor plugin vtable. All function pointers are optional except
 * describe(); a NULL compress/decompress means "not provided" and the manager
 * returns SLEELA_COMPRESSION_ERR_UNSUPPORTED for that direction.
 */
typedef struct sleela_compressor_plugin {
    /* Static identity/metadata -- must always be present. */
    const sleela_compressor_handler *(*describe)(void);

    /* Lifecycle. load() is called by the manager when the algorithm is loaded
     * and may allocate instance state; unload() releases it. Either may be NULL. */
    sleela_compression_result (*load)(sleela_compressor_instance **out_instance);
    void (*unload)(sleela_compressor_instance *instance);

    /* Identify whether `data` (first `len` bytes) is this algorithm's format.
     * Returns SLEELA_COMPRESSION_OK when recognized, SLEELA_COMPRESSION_ERR_FORMAT if not. */
    sleela_compression_result (*probe)(sleela_compressor_instance *instance,
                                       const uint8_t *data, size_t len);

    /* Compress `input` into this algorithm's format. On success *out is filled
     * and owned by the plugin until unload() or a plugin-provided free; a plugin
     * that lacks its backend returns SLEELA_COMPRESSION_ERR_UNSUPPORTED. */
    sleela_compression_result (*compress)(sleela_compressor_instance *instance,
                                          const uint8_t *input, size_t input_len,
                                          sleela_byte_buffer *out);

    /* Decompress this algorithm's format back to raw bytes. Ownership of *out as
     * for compress(). */
    sleela_compression_result (*decompress)(sleela_compressor_instance *instance,
                                            const uint8_t *input, size_t input_len,
                                            sleela_byte_buffer *out);
} sleela_compressor_plugin;

/*
 * Runtime-pluggable backend for an algorithm whose state is
 * SLEELA_COMPRESSION_BACKEND.
 *
 * A plugin ships the contract (probe + metadata) but delegates the actual
 * compress/decompress to a backend a host registers at runtime. When an
 * approved library (zlib, libzstd, liblz4, libbz2, liblzma, brotli, ...) is
 * available, the host builds a small adapter exposing these two function
 * pointers and registers it for the algorithm's id; the plugin's
 * compress/decompress then dispatch to it. With no backend registered, the
 * plugin reports SLEELA_COMPRESSION_ERR_UNSUPPORTED -- never a false success.
 *
 * This keeps the in-tree code free of third-party dependencies while making the
 * "wire a real backend" path concrete and testable.
 */
typedef struct sleela_compression_backend {
    const char *name;   /* adapter/library name, for diagnostics          */
    sleela_compression_result (*compress)(const uint8_t *input, size_t input_len,
                                          sleela_byte_buffer *out);
    sleela_compression_result (*decompress)(const uint8_t *input, size_t input_len,
                                            sleela_byte_buffer *out);
} sleela_compression_backend;

/* Register (or clear, with backend==NULL) the backend for an algorithm id.
 * Returns SLEELA_COMPRESSION_OK, or SLEELA_COMPRESSION_ERR_INVALID for an
 * out-of-range id. The registry is process-global; a host wires backends at
 * startup. */
sleela_compression_result sleela_compression_backend_register(sleela_compressor_id id,
                                                              const sleela_compression_backend *backend);

/* The backend currently registered for an algorithm id, or NULL if none. */
const sleela_compression_backend *sleela_compression_backend_get(sleela_compressor_id id);

/*
 * Each individual algorithm exposes exactly one accessor returning its plugin
 * vtable (a stable singleton). The manager calls these to build its table.
 * Declared here; defined in compression/compressors/<name>/<name>.c (+ .cpp).
 */
const sleela_compressor_plugin *sleela_compressor_plugin_store(void);
const sleela_compressor_plugin *sleela_compressor_plugin_rle(void);
const sleela_compressor_plugin *sleela_compressor_plugin_huffman(void);
const sleela_compressor_plugin *sleela_compressor_plugin_lzw(void);
const sleela_compressor_plugin *sleela_compressor_plugin_deflate(void);
const sleela_compressor_plugin *sleela_compressor_plugin_zlib(void);
const sleela_compressor_plugin *sleela_compressor_plugin_gzip(void);
const sleela_compressor_plugin *sleela_compressor_plugin_bzip2(void);
const sleela_compressor_plugin *sleela_compressor_plugin_lzma(void);
const sleela_compressor_plugin *sleela_compressor_plugin_xz(void);
const sleela_compressor_plugin *sleela_compressor_plugin_zstd(void);
const sleela_compressor_plugin *sleela_compressor_plugin_lz4(void);
const sleela_compressor_plugin *sleela_compressor_plugin_brotli(void);
const sleela_compressor_plugin *sleela_compressor_plugin_snappy(void);
const sleela_compressor_plugin *sleela_compressor_plugin_zip(void);

#ifdef __cplusplus
}
#endif

#endif /* SLEELA_COMPRESSOR_PLUGIN_H */