1

#ifndef CACHE_H

     2

#define CACHE_H

     3

     4

#include <sys/types.h>

     5

     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

 */

    34

struct cache_key {

    35

    char *buf;

    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,

    46

    CACHE_STATE_HIT,

    47

    CACHE_STATE_MISS,

    48

    49

    CACHE_STATE_OPEN_READ,

    50

    CACHE_STATE_READ,

    51

    52

    CACHE_STATE_OPEN_WRITE,

    53

    CACHE_STATE_WRITE,

    54

    CACHE_STATE_WRITE_PAUSE,

    55

    56

    CACHE_STATE_ERROR,

    57

};

    58

    59

/*

    60

/ *

    61

 * Transitions between states

    62

 * /

    63

enum cache_req_event {

    64

    // LOOKUP -> OPEN

    65

    CACHE_EVENT_HIT,

    66

    CACHE_EVENT_MISS,

    67

    68

    // OPEN -> WRITE

    69

    CACHE_EVENT_BEGIN_WRITE,

    70

    71

    // OPEN -> READ

    72

    CACHE_EVENT_BEGIN_READ,

    73

    74

    // WRITE -> PAUSE_WRITE

    75

    CACHE_EVENT_PAUSE_WRITE,

    76

    77

    // PAUSE_WRITE -> WRITE

    78

    CACHE_EVENT_RESUME_WRITE,

    79

    80

    // READ -> READ

    81

    CACHE_EVENT_DATA_AVAILABLE,

    82

    83

    // READ -> DONE

    84

    CACHE_EVENT_DONE,

    85

    86

    // * -> ERROR

    87

    CACHE_EVENT_ERROR,

    88

};

    89

*/

    90

    91

/*

    92

 * The callback used for cache_reqs

    93

 */

    94

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

    95

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

    96

    97

    98

    99

   100

   101

   102

/*

   103

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

   104

 */

   105

struct cache *cache_open (struct cache_engine *engine);

   106

   107

/*

   108

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

   109

 * drive the request forward.

   110

 */

   111

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

   112

   113

/*

   114

 * Get the request's state.

   115

 */ 

   116

enum cache_req_state cache_req_state (struct cache_req *req);

   117

   118

/*

   119

 * Get the rquest's key

   120

 */

   121

const struct cache_key *cache_req_key (struct cache_req *req);

   122

   123

/*

   124

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

   125

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

   126

 *      offset      - how many bytes of data the cache entry contains. May be 0

   127

 *      available   - how many unread bytes are available. May be 0

   128

 */

   129

int cache_req_available (struct cache_req *req, size_t *size, size_t *offset, size_t *available);

   130

   131

/*

   132

 * Prepare this cache req for writing in the data. Hint, if nonzero, is used to pre-allocate resources for the entry.

   133

 */

   134

int cache_req_begin_write (struct cache_req *req, size_t hint);

   135

   136

/*

   137

 * Prepare this cache req for use with cache_req_pull.

   138

 */

   139

int cache_req_begin_read (struct cache_req *req);

   140

   141

/*

   142

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

   143

 * CACHE_REQ_WRITE mode.

   144

 *

   145

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

   146

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

   147

 *

   148

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

   149

 */

   150

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

   151

   152

/*

   153

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

   154

 * CACHE_REQ_READ and CACHE_REQ_WRITE mode.

   155

 *

   156

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

   157

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

   158

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

   159

 */

   160

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

   161

   162

/*

   163

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

   164

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

   165

 */

   166

void cache_req_abort (struct cache_req *req);

   167

   168

/*

   169

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

   170

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

   171

 */

   172

int cache_req_done (struct cache_req *req);

   173

   174

/*

   175

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

   176

 */

   177

void cache_req_release (struct cache_req *req);

   178

   179

#endif /* CACHE_H */