#ifndef CACHE_ENGINE_H
#define CACHE_ENGINE_H

struct cache_engine {
    /*
     * Allocate a `struct cache`-compatible struct and return it via cache_ptr.
     */
    int (*fn_init) (struct cache_engine *, struct cache **);
    
    /*
     * Allocate a `struct cache_op`-compatible struct and return it via cache_ptr.
     *
     * Begin the index lookup.
     */
    int (*fn_op_start) (struct cache *, struct cache_op **, struct cache_key *);
    
    /*
     * Return some information about the available data.
     */
    int (*fn_op_available) (struct cache_op *, size_t *size, size_t *offset);
    
    /*
     * Prepare to read from this cache entry.
     */
    int (*fn_op_begin_read) (struct cache_op *);

    /*
     * Prepare to write to this cache entry.
     *
     * size_hint, if nonzero, provides a guess at the size of the cache entry that can be used to optimize stuff
     */
    int (*fn_op_begin_write) (struct cache_op *, size_t size_hint);
    
    /*
     * Read some data from the given fd into this cache entry. Size may contain a non-zero value to hint at how many
     * bytes should be read, or zero to just read a suitable amount. Should be updated to how many bytes were actually
     * written (may be zero if writes are currently paused).
     */
    int (*fn_op_push) (struct cache_op *, int fd, size_t *size);
    
    /*
     * Write some data into the given fd from this cache entry. Size either specifies how many bytes to read (and
     * should not be more than is available), or zero to read as much as possible. Offset is the offset from the
     * beginning of the cache entry, and should be updated to what the next unread byte would be. Size should be
     * updated to how many bytes was read.
     */
    int (*fn_op_pull) (struct cache_op *, int fd, size_t *offset, size_t *size);

    /*
     * No more calls to fn_op_push will take place. The cache entry now contains the complete data.
     */
    int (*fn_op_done) (struct cache_op *);

    /*
     * The op is not needed for any operations anymore. Free any resources and memory associated with this op,
     * including the op itself.
     */
    int (*fn_op_close) (struct cache_op *);
};

#endif /* CACHE_ENGINE_H */