1

#ifndef CACHE_H

     2

#define CACHE_H

     3

     6

/*

     7

 * The interface to the internal caching mechanism.

     8

 *

     9

 * This presents a pretty generic API, which allows the actual implementation to change, or to compare multiple

    10

 * different implementations.

    11

 *

    12

 */

    13

    14

    15

/*

    16

 * The handle used to access the global cache.

    17

 */

    18

struct cache;

    19

    20

/*

    21

 * A cache request/operation.

    22

 */

    23

struct cache_req;

    24

    25

/*

    26

 * The actual implementation of the cache.

    27

 */

    28

struct cache_engine;

    29

    30

/*

    31

 * What we use as keys in the cache. Key is a pointer to an arbitrary char buffer, length is the size of the key

    32

 * in bytes. If this is given as zero, it will be calcuated using strlen(). Zero-length keys are invalid.

    33

 */

    36

    size_t length;

    37

};

    38

    39

/*

    40

 * The various states that a cache request can be in

    41

 */

    42

enum cache_req_state {

    43

    CACHE_STATE_INVALID,

    44

    45

    CACHE_STATE_LOOKUP,

    48

    CACHE_STATE_WRITE,

    49

    CACHE_STATE_WRITE_PAUSE,

    50

    CACHE_STATE_READ,

    51

    52

    CACHE_STATE_DONE,

    53

    CACHE_STATE_ERROR,

    54

};

    55

    56

/*

    58

 * Transitions between states

    60

enum cache_req_event {

    61

    // LOOKUP -> OPEN

    62

    CACHE_EVENT_HIT,

    63

    CACHE_EVENT_MISS,

    65

    // OPEN -> WRITE

    66

    CACHE_EVENT_BEGIN_WRITE,

    67

    68

    // OPEN -> READ

    69

    CACHE_EVENT_BEGIN_READ,

    70

    71

    // WRITE -> PAUSE_WRITE

    72

    CACHE_EVENT_PAUSE_WRITE,

    73

    74

    // PAUSE_WRITE -> WRITE

    75

    CACHE_EVENT_RESUME_WRITE,

    76

    77

    // READ -> READ

    78

    CACHE_EVENT_DATA_AVAILABLE,

    79

    80

    // READ -> DONE

    81

    CACHE_EVENT_DONE,

    82

    83

    // * -> ERROR

    84

    CACHE_EVENT_ERROR,

    85

};

    87

    88

/*

    89

 * The callback used for cache_reqs

    90

 */

    93

    94

    95

    96

    97

    98

    99

/*

   100

 * Open up a cache using the given engine (which can be configured with engine-specific params).

   101

 */

   102

struct cache *cache_open (struct cache_engine *engine);

   103

   104

/*

   105

 * Create a new request. The given callback function will be called at the various stages in the request, and can then

   106

 * drive the request forward.

   107

 */

   109

   110

/*

   111

 * Get the request's state.

   112

 */ 

   119

   120

/*

   121

 * Get information about the amount of data in this cache entry.

   122

 *      size        - the total size of the cache entry. -1 if unknown

   123

 *      offset      - how many bytes of data the cache entry contains

   124

 *      available   - how many unread bytes are available

   125

 */

   126

void cache_req_available (struct cache_req *req, ssize_t *size, ssize_t *offset, ssize_t *available);

   127

   128

/*

   134

 * Add some data into this cache entry, reading from the given fd. This is only valid for cache_req's in

   135

 * CACHE_REQ_WRITE mode.

   136

 *

   137

 * If you know the amount of data that should be pushed, you can supply it in size. If size is given as 0, all

   138

 * available data will be consumed. Size will be updated to the number of bytes pushed into the cache.

   139

 *

   140

 * (size == 0) is valid if req is in the WRITE_PAUSE state (either before or after the call).

   141

 */

   142

int cache_req_push (struct cache_req *req, int fd, size_t *size);

   143

   144

/*

   145

 * Get some data from this cache entry, writing it into the given fd. This is valid for all cache_req's in

   146

 * CACHE_REQ_READ and CACHE_REQ_WRITE mode.

   147

 *

   148

 * If the value of size is given (nonzero), then the given amount of data will be written to the fd from the cache.

   149

 * If the cache contains less data than given, this is an error. If the value of size is zero, as much data as possible

   150

 * will be written to the fd. Size will be updated to the number of bytes pulled from the cache.

   151

 */

   152

int cache_req_pull (struct cache_req *req, int fd, size_t *size);

   153

   154

/*

   155

 * Abort the given cache request (external failure). This is only needed for CACHE_REQ_WRITE requests, and is invalid

   156

 * for other requests. Any dependant cache requests will fail.

   157

 */

   158

void cache_req_abort (struct cache_req *req);

   159

   160

/*

   161

 * Indicate that the given cache write request is complete. This is only valid for CACHE_REQ_WRITE requests, and is

   162

 * invalid for other requests. Any dependant cache requests will complete.

   163

 */

   164

int cache_req_done (struct cache_req *req);

   165

   166

/*

   167

 * Release the given cache request. Only valid after calling req_abort/req_done, or getting EVENT_DONE/EVENT_ERROR.

   168

 */

   169

void cache_req_release (struct cache_req *req);

   170

   171

#endif /* CACHE_H */