1

#ifndef CACHE_H

     2

#define CACHE_H

     3

     4

/*

     5

 * The interface to the internal caching mechanism.

     6

 *

     7

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

     8

 * different implementations.

     9

 *

    10

 */

    11

    12

    13

/*

    14

 * The handle used to access the global cache.

    15

 */

    16

struct cache;

    17

    18

/*

    19

 * A cache request/operation.

    20

 */

    21

struct cache_req;

    22

    23

/*

    24

 * The actual implementation of the cache.

    25

 */

    26

struct cache_engine;

    27

    28

/*

    29

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

    30

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

    31

 */

    32

struct cache_key_t {

    33

    const char *buf;

    34

    size_t length;

    35

};

    36

    37

/*

    38

 * The various states that a cache request can be in

    39

 */

    40

enum cache_req_state {

    41

    CACHE_STATE_INVALID,

    42

    43

    CACHE_STATE_LOOKUP,

    44

    45

    CACHE_STATE_OPEN,

    46

    47

    CACHE_STATE_WRITE,

    48

    CACHE_STATE_WRITE_PAUSE,

    49

    CACHE_STATE_READ,

    50

    51

    CACHE_STATE_DONE,

    52

    CACHE_STATE_ERROR,

    53

};

    54

    55

/*

    56

 * Transitions between states

    57

 */

    58

enum cache_req_event {

    59

    // LOOKUP -> OPEN

    60

    CACHE_EVENT_HIT,

    61

    CACHE_EVENT_MISS,

    62

    63

    // OPEN -> WRITE

    64

    CACHE_EVENT_BEGIN_WRITE,

    65

    66

    // OPEN -> READ

    67

    CACHE_EVENT_BEGIN_READ,

    68

    69

    // WRITE -> PAUSE_WRITE

    70

    CACHE_EVENT_PAUSE_WRITE,

    71

    72

    // PAUSE_WRITE -> WRITE

    73

    CACHE_EVENT_RESUME_WRITE,

    74

    75

    // READ -> READ

    76

    CACHE_EVENT_DATA_AVAILABLE,

    77

    78

    // READ -> DONE

    79

    CACHE_EVENT_DONE,

    80

    81

    // * -> ERROR

    82

    CACHE_EVENT_ERROR,

    83

};

    84

    85

/*

    86

 * The callback used for cache_reqs

    87

 */

    88

typedef (int) (*cache_callback) (struct cache_req *, enum cache_req_event, void *arg);

    89

    90

    91

    92

    93

    94

    95

/*

    96

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

    97

 */

    98

struct cache *cache_open (struct cache_engine *engine);

    99

   100

/*

   101

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

   102

 * drive the request forward.

   103

 */

   104

struct cache_req *cache_request (struct cache *cache, struct cache_key *key, cache_callback cb_func, void *cb_data);

   105

   106

/*

   107

 * Get the request's state.

   108

 */ 

   109

enum cache_req_state cache_request_state (struct cache_req *req);

   110

   111

/*

   112

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

   113

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

   114

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

   115

 *      available   - how many unread bytes are available

   116

 */

   117

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

   118

   119

/*

   120

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

   121

 * CACHE_REQ_WRITE mode.

   122

 *

   123

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

   124

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

   125

 *

   126

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

   127

 */

   128

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

   129

   130

/*

   131

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

   132

 * CACHE_REQ_READ and CACHE_REQ_WRITE mode.

   133

 *

   134

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

   135

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

   136

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

   137

 */

   138

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

   139

   140

/*

   141

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

   142

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

   143

 */

   144

void cache_req_abort (struct cache_req *req);

   145

   146

/*

   147

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

   148

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

   149

 */

   150

int cache_req_done (struct cache_req *req);

   151

   152

/*

   153

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

   154

 */

   155

void cache_req_release (struct cache_req *req);

   156

   157

#endif /* CACHE_H */