1

#ifndef CACHE_OP_H

     2

#define CACHE_OP_H

     3

     4

#include <sys/queue.h>

     5

     6

// this duplicates the cache_state enum, but is indeed interpreted differently:

     7

enum cache_op_state {

     8

    /*

     9

     * The op is still in the state of being constructed, and it not yet valid.

    10

     *

    11

     * This should not be encountered other than if the callback is called from within fn_op_start.

    12

     */

    13

    OP_STATE_INVALID,

    14

    15

    /*

    16

     * In the process of looking up the key. The op should enter this state as soon as it is constructed.

    17

     */

    18

    OP_STATE_LOOKUP,

    19

    20

    /*

    21

     * The key was not found in the cache. You should call cache_op_begin_write next.

    22

     */

    23

    OP_STATE_MISS,

    24

    25

    /*

    26

     * The key was found in the cache. You should call cache_op_begin_read next.

    27

     */

    28

    OP_STATE_HIT,

    29

    30

    /*

    31

     * cache_op_begin_read has been called, but the op is not yet read for cache_op_pull.

    32

     */

    33

    OP_STATE_OPEN_READ,

    34

    35

    /*

    36

     * cache_op_begin_write has been called, but the op is not yet read for cache_op_push.

    37

     */

    38

    OP_STATE_OPEN_WRITE,

    39

    40

    /*

    41

     * cache_op_begin_read has completed succesfully, and you may now call cache_op_pull.

    42

     */

    43

    OP_STATE_READ,

    44

    45

    /*

    46

     * cache_op_begin_write has completed succesfully, and you may now call cache_op_push/cache_op_done.

    47

     */

    48

    OP_STATE_WRITE,

    49

    50

    /*

    51

     * XXX: not used yet

    52

     */

    53

    OP_STATE_ERROR,

    54

};

    55

    56

struct cache_op {

    57

    // reference to what cache this belongs to

    58

    struct cache *cache;

    59

    60

    // used to store this in the cache->op_list

    61

    LIST_ENTRY(cache_op) node;

    62

    63

    // a pointer to the key we are using

    64

    // XXX: object lifetime is currently broken (cache_req.key_copy of the first req atm)

    65

    // XXX: the key should probably be copied into this.

    66

    struct cache_key *key;

    67

    68

    // the list of cache_req's that are using this op.

    69

    LIST_HEAD(cache_op_req_list_head, cache_req) req_list;

    70

    71

    // our current state.

    72

    enum cache_op_state state;

    73

};

    74

    75

/*

    76

 * Used by the engine's fn_op_start implementation to initialize the basic cache op state.

    77

 */

    78

int _cache_op_init(struct cache_op *op, struct cache *cache, struct cache_key *key);

    79

    80

/*

    81

 * Look for an existing cache_op with the given key in the given cache. Return NULL if not found, return pointer

    82

 * if found.

    83

 */

    84

struct cache_op *cache_op_find (struct cache *cache, struct cache_key *key);

    85

    86

/*

    87

 * Add the given cache_req to the list of reqs using this op

    88

 */

    89

int cache_op_register (struct cache_op *op, struct cache_req *req);

    90

    91

/*

    92

 * The given req is done and not using this op anymore. The op is closed if it was the only req left

    93

 *

    94

 * The op would normally be in the OP_STATE_READ state.

    95

 */

    96

int cache_op_deregister (struct cache_op *op, struct cache_req *req);

    97

    98

/*

    99

 * Get info about the data available in this cache entry.

   100

 *  size    - total size of the cache entry. 0 if unknown (not yet fully written).

   101

 *  offset  - how many bytes of the cache entry are currently stored. May be 0

   102

 *

   103

 *  size will be nonzero in the (OP_STATE_HIT | (OP_STATE_MISS -> OP_STATE_WRITE) -> ) OP_STATE_READ state.

   104

 *

   105

 *  This is valid in all states except OP_STATE_INVALID, OP_STATE_LOOKUP and OP_STATE_ERROR, but both values may very

   106

 *  well be zero in many of these states.

   107

 */

   108

int cache_op_available (struct cache_op *op, size_t *size, size_t *offset);

   109

   110

/*

   111

 * Prepare op for reading the data from it.

   112

 *

   113

 * The op must be in the OP_SATE_HIT state, and will move ino the OP_STATE_OPEN_READ state, possibly also

   114

 * directly into the OP_STATE_READ state.

   115

 */

   116

int cache_op_begin_read (struct cache_op *op);

   117

   118

/*

   119

 * Prepare op for writing data to it. If size_hint is nonzero, it is used to optimize resource preallocation.

   120

 *

   121

 * The op must be in the OP_STATE_MISS state, and will move into the OP_STATE_OPEN_WRITE state, possibly also

   122

 * directly into the OP_STATE_WRITE state.

   123

 */

   124

int cache_op_begin_write (struct cache_op *op, size_t size_hint);

   125

   126

/*

   127

 * Write some data into the cache by reading from the given fd. Size, if nonzero, tells how many bytes of data to read,

   128

 * otherwise, as much data as possible will be read. Size will be updated to the number of bytes actually pushed on

   129

 * return. This may be zero bytes (XXX: OP_STATE_PAUSE_WRITE).

   130

 *

   131

 * The op must be in the OP_STATE_WRITE state. All registered reqs will be notified, even if zero bytes were pushed.

   132

 */

   133

int cache_op_push (struct cache_op *op, int fd, size_t *size);

   134

   135

/*

   136

 * Read some data from the cache into the given fd.

   137

 *

   138

 * The data pulled from the cache entry should be *size bytes, starting at *offset. If the value of *size is zero,

   139

 * then as much data as is available will be pulled, otherwise, pull the given number of bytes. If the cache entry

   140

 * contains less bytes than requested, this is an error. Offset should be updated to point to what will be the next

   141

 * unread data, and size should be updated to how many bytes were read (if it was given as zero).

   142

 *

   143

 * The op mustbe in the OP_STATE_READ or OP_STATE_WRITE state.

   144

 */

   145

int cache_op_pull (struct cache_op *op, int fd, size_t *offset, size_t *size);

   146

   147

/*

   148

 * Indicate that the freshly written cache entry is now complete. This should be called after the last cache_op_push

   149

 * call, and no more cache_op_push calls may ensue.

   150

 *

   151

 * The op must be in the OP_STATE_WRITE state, and will move into the OP_STATE_READ state (i.e. the op may still be

   152

 * read from).

   153

 */

   154

int cache_op_done (struct cache_op *op);

   155

   156

/*

   157

 * Used by the engines to notify of state transitions

   158

 */

   159

   160

/*

   161

 * cache_op_start completed, and the cache op is ready for begin_read/begin_write, based on `found`.

   162

 *

   163

 * OP_STATE_LOOKUP -> (OP_STATE_HIT | OP_STATE_MISS)

   164

 */

   165

int _cache_op_lookup_done (struct cache_op *op, int found);

   166

   167

/*

   168

 * cache_op_begin_read completed, ad the cache op is ready for cache_op_pull

   169

 *

   170

 * OP_STATE_OPEN_READ -> OP_STATE_READ

   171

 */

   172

int _cache_op_read_ready (struct cache_op *op);

   173

   174

/*

   175

 * cache_op_begin_write completed, and the cache op is ready for cache_op_push.

   176

 *

   177

 * OP_STATE_OPEN_WRITE -> OP_STATE_WRITE

   178

 */

   179

int _cache_op_write_ready (struct cache_op *op);

   180

   181

/*

   182

 * There is new data available for reading.

   183

 *

   184

 * OP_STATE_READ | OP_STATE_WRITE 

   185

 */

   186

int _cache_op_data_available (struct cache_op *op);

   187

   188

/*

   189

 * cache_op_done completed, and the cache op now contains all the data that it ever will.

   190

 *

   191

 * OP_STATE_WRITE -> OP_STATE_READ

   192

 */

   193

int _cache_op_write_done (struct cache_op *op);

   194

   195

#endif /* CACHE_OP_H */