1

#ifndef MEMCACHE_H

     2

#define MEMCACHE_H

     3

     4

/*

     5

 * A libevent based memcached client that aims for high performance, concurrency and low latency.

     6

 */

     7

     8

#include "config.h"

     9

    10

/*

    11

 * Used to store the global information for a memcache context. A context contains both servers and active connections.

    14

 */

    15

struct memcache;

    16

    17

/*

    18

 * A transaction.

    21

 */

    22

struct memcache_req;

    23

    24

/*

    26

 */

    27

struct memcache_key {

    28

    /*

    29

     * Pointer to a char buffer containing the key itself.

    30

     *

    31

     * A key is a text tring which should uniquely identify a cache entry.

    32

     *

    33

     * The length limit for a key is usually 250 characters, but this is imposed by the server side (a longer key will

    34

     * presumeably cause a CLIENT_ERROR reply).

    35

     *

    36

     * The key should presumeably also not contain any spaces, carriage returns or newlines, as these are used to

    37

     * delimit tokens in the protocol itself.

    38

     *

    39

     * The buffer does not need to be zero-terminated.

    40

     */

    41

    char *buf;

    42

    43

    /*

    44

     * The length of the key buffer in bytes. This does not include a NUL byte.

    45

     */

    46

    size_t len;

    47

};

    48

    49

/*

    50

 * Object attributes

    51

 */

    52

struct memcache_obj {

    53

    /*

    54

     * An arbitrary 16-bit (32-bit for >1.2.1) that the server stores transparently.

    55

     */

    56

    unsigned int flags;

    57

    58

    /*

    59

     * Expiration time. If non-zero, either an offset in seconds from current time (up to 60*60*24*30 seconds, or 30d),

    60

     * or an absolute 32-bit unix timestamp.

    61

     */

    62

    time_t exptime;

    63

    64

    /*

    65

     * Number of bytes in the entry. This may be zero, in which case there will be no data.

    66

     */

    67

    size_t bytes;

    68

    69

    /*

    70

     * Used for the CMD_STORE_CAS command. An unique 64-bit value that changes if the entry is modified.

    71

     *

    72

     * Not needed for other commands, and may or may not be provided by CMD_FETCH_GET (will be set to zero).

    73

     */

    74

    unsigned long long cas;

    75

};

    76

    77

/*

    78

 * Object data

    79

 */

    80

struct memcache_buf {

    81

    /*

    82

     * The char buffer containing the data.

    83

     */

    84

    char *data;

    85

    86

    /*

    87

     * The total length of the char buffer, and thence the cache entry.

    88

     */

    89

    size_t len;

    90

    91

    /*

    92

     * The amount of data currently available in the buffer. This is used to provide streaming fetches.

    93

     *

    94

     * This field is *IMPORTANT*! Don't disregard it, or you *will* get incomplete data.

    95

     */

    96

    size_t offset;

    97

};

    98

    99

/*

   100

 * Available commands

   101

 */

   102

enum memcache_command {

   103

    MEMCACHE_CMD_INVALID,

   104

   105

    /*

   106

     * Retrieve the value of a key from the memcached server. 

   107

     *

   108

     * If the key exists, you will get a RPL_VALUE reply followed by a RPL_END reply. 

   109

     * If it does not exist, you will just get a RPL_END reply.

   110

     */

   111

    MEMCACHE_CMD_FETCH_GET,

   112

   113

    /*

   114

     * Store this data.

   115

     *

   116

     * Returns either RPL_STORED or RPL_NOT_STORED.

   117

     */

   118

    MEMCACHE_CMD_STORE_SET,

   119

   120

    /*

   121

     * Store this data, but only if the server doesn't already hold data for this key.

   122

     *

   123

     * Returns either RPL_STORED or RPL_NOT_STORED.

   124

     */

   125

    MEMCACHE_CMD_STORE_ADD,

   126

   127

    /*

   128

     * Store this data, but only if the server does already hold data for this key.

   129

     *

   130

     * Returns either RPL_STORED or RPL_NOT_STORED.

   131

     */

   132

    MEMCACHE_CMD_STORE_REPLACE,

   133

   134

    /*

   135

     * Add this data to an existing key after existing data.

   136

     *

   137

     * obj.flags and obj.exptime are ignored.

   138

     *

   139

     * Returns ???

   140

     */

   141

    MEMCACHE_CMD_STORE_APPEND,

   142

   143

    /*

   144

     * Add this data to an existing key before existing data.

   145

     *

   146

     * obj.flags and obj.exptime are ignored.

   147

     *

   148

     * Returns ???

   149

     */

   150

    MEMCACHE_CMD_STORE_PREPEND,

   151

   152

    /*

   153

     * Check and Set - store this data but only if no one else had updated it since I last fetched it.

   154

     *

   155

     * obj.cas is required.

   156

     *

   157

     * Returns RPL_STORED, RPL_NOT_STORED, RPL_EXISTS (data has been modified), or RPL_NOT_FOUND (the item does not

   158

     * exist or has been deleted).

   159

     */

   160

    MEMCACHE_CMD_STORE_CAS,

   161

   162

    MEMCACHE_CMD_MAX,

   163

};

   164

   165

/*

   166

 * Replies from the server

   167

 */

   168

enum memcache_reply {

   169

    MEMCACHE_RPL_INVALID,

   170

   171

    /*

   172

     * The library sent an unknown command. This probably means the server is not compatible with said command.

   173

     */

   174

    MEMCACHE_RPL_ERROR,

   175

   176

    /*

   177

     * There was an error in the request that the library sent. The error message is printed out via ERROR.

   178

     */

   179

    MEMCACHE_RPL_CLIENT_ERROR,

   180

   181

    /*

   182

     * There was an error with the server when processing the request. The error message is printed out via ERROR.

   183

     */

   184

    MEMCACHE_RPL_SERVER_ERROR,

   185

   186

    // CMD_FETCH_*

   187

   188

    /*

   189

     * The given key was found in the cache. The obj attributes are now known, and the buf data is on the way.

   190

     */

   191

    MEMCACHE_RPL_VALUE,

   192

   193

    /*

   194

     * No more RPL_VALUE replies will be sent. This may be the only reply sent if the key was not found.

   195

     */

   196

    MEMCACHE_RPL_END,

   197

   198

    // CMD_STORE_*

   199

   200

    /*

   201

     * The object was succesfully stored in the cache.

   202

     */

   203

    MEMCACHE_RPL_STORED,

   204

   205

    /*

   206

     * The object was not stored in the cache.

   207

     *

   208

     * This could be for a number of reasons, perhaps the object is too large, the cache is full, the key is in the

   209

     * delete queue, or some condition imposed by the STORE_* command was not met.

   210

     */

   211

    MEMCACHE_RPL_NOT_STORED,

   212

   213

    /*

   214

     * The item you were trying to store with a STORE_CAS request has been modified since you last fetched it (i.e.

   215

     * obj.cas does not match).

   216

     */

   217

    MEMCACHE_RPL_EXISTS,

   218

   219

    /*

   220

     * The item you were trying to store with a STORE_CAS request did not exist (or has been deleted).

   221

     */

   222

    MEMCACHE_RPL_NOT_FOUND,

   223

   224

    MEMCACHE_RPL_MAX,

   225

};

   226

   230

enum memcache_req_state {

   231

    MEMCACHE_STATE_INVALID,

   232

   233

    /*

   234

     * The request is queued, and has not been sent yet

   235

     */

   236

    MEMCACHE_STATE_QUEUED,

   237

   238

    /*

   239

     * The request is being sent, and the reply has not yet been received

   240

     */

   241

    MEMCACHE_STATE_SEND,

   242

   243

    /*

   244

     * The reply has been received.

   245

     *

   246

     * req_reply and req_obj will return a non-NULL value, but there is no reply data yet.

   247

     */

   248

    MEMCACHE_STATE_REPLY,

   249

   250

    /*

   251

     * The reply and part of the reply data has been received.

   252

     *

   253

     * req_reply, req_obj and req_buf will all return non-NULL values, but buf.offset will be smaller than buf.len.

   254

     */

   255

    MEMCACHE_STATE_REPLY_DATA,

   256

   257

    /*

   258

     * The full reply has been received.

   259

     *

   260

     * req_reply, req_obj will return a non-NULL value, but there is no reply data.

   261

     */

   262

    MEMCACHE_STATE_DONE,

   263

   264

    /*

   265

     * The full reply and reply data has been received.

   266

     *

   267

     * req_reply, req_obj and req_buf will all return non-NULL values, and buf.offset will be equal to buf.len.

   268

     */

   269

    MEMCACHE_STATE_DATA_DONE,

   270

   271

    /*

   272

     * An error has occurred.

   273

     *

   274

     * req_reply, req_obj and req_buf may or may not work.

   275

     */

   276

    MEMCACHE_STATE_ERROR,

   277

};

   278

   279

/*

   284

 */

   285

typedef int (*memcache_cb) (struct memcache_req *, void*);

   286

   287

/*

   288

 * Allocate a new memcache context for use with other methods.

   291

 */

   292

struct memcache *memcache_alloc (memcache_cb cb_fn);

   293

   294

/*

   295

 * Add a server to the pool of available servers.

   298

 */

   299

int memcache_add_server (struct memcache *mc, struct config_endpoint *endpoint, int max_connections);

   300

   301

/*

   302

 * Attempt to fetch a key from the cache.

   303

 *

   306

 * The state machine will work as follows:

   307

 *

   308

 *  req_state                  multi   req_reply

   309

 *  ---------------------------------------------

   310

 *  STATE_QUEUE                 ?

   311

 *  STATE_SEND

   312

 *  STATE_REPLY                         RPL_VALUE

   313

 *      STATE_REPLY_DATA        *       RPL_VALUE

   314

 *      STATE_DATA_DONE                 RPL_END

   315

 *

   316

 *      STATE_DONE                      RPL_END

   317

 *

   318

 *  STATE_ERROR                         RPL_{ERROR,CLIENT_ERROR,SERVER_ERROR}

   319

 *

   320

 * The item attributes/data can be accessed via req_obj/req_buf as described in `enum memcache_state`.

   321

 */

   322

struct memcache_req *memcache_fetch (struct memcache *mc, const struct memcache_key *key, void *cb_arg);

   323

   324

/*

   325

 * Attempt to store an item into the cache.

   326

 *

   327

 * The cmd argument can be used to specify what CMD_STORE_* command to use.

   328

 *

   329

 * The given memcache_key is copied, including the char array pointed to by buf.

   330

 * Both obj and buf are also copied, but buf.data will not be copied - the pointer must remain valid until the request is done.

   333

 *

   334

 * The state machine will work as follows:

   335

 *

   336

 *  req_state               multi       req_reply

   337

 *  ---------------------------------------------

   338

 *  STATE_QUEUE             ?

   339

 *  STATE_SEND

   340

 *  STATE_REPLY                         RPL_{STORED,NOT_STORED,EXISTS,NOT_FOUND}

   341

 *  STATE_DONE                          RPL_{STORED,NOT_STORED,EXISTS,NOT_FOUND}

   342

 * 

   343

 *  STATE_ERROR                         RPL_{ERROR,CLIENT_ERROR,SERVER_ERROR}

   344

 *

   345

 */

   346

struct memcache_req *memcache_store (struct memcache *mc, enum memcache_command cmd, const struct memcache_key *key, const struct memcache_obj *obj, const struct memcache_buf *buf, void *cb_arg);

   347

   348

/*

   349

 * Request state.

   350

 *

   351

 * Should always return a valid value.

   352

 */ 

   353

enum memcache_req_state memcache_req_state (struct memcache_req *req);

   354

   355

/*

   356

 * Request command.

   357

 *

   358

 * Should always return a valid value.

   359

 */

   360

enum memcache_command memcache_req_cmd (struct memcache_req *req);

   361

   362

/*

   363

 * Request reply.

   364

 *

   365

 * Will return a valid value in the STATE_REPLY, STATE_REPLY_DATA, STATE_DONE and STATE_DATA_DONE states.

   366

 */

   367

enum memcache_reply memcache_req_reply (struct memcache_req *req);

   368

   369

/*

   370

 * Request key.

   371

 *

   372

 * Will return a valid valuein all states

   373

 */

   374

const struct memcache_key *keymemcache_req_key (struct memcache_req *req);

   375

   376

/*

   377

 * Request data.

   378

 *

   379

 * Will return a valid value in the STATE_REPLY, STATE_REPLY_DATA, STATE_DONE and STATE_DATA_DONE states.

   380

 */

   381

const struct memcache_obj *memcache_req_obj (struct memcache_req *req);

   382

   383

/*

   384

 * Request buf.

   385

 *

   386

 * Will return a valid value in the STATE_REPLY_DATA and STATE_DATA_DONE states.

   387

 *

   388

 * Note that buf.offset may be less than buf.len in the STATE_REPLY_DATA state.

   389

 */

   390

const struct memcache_buf *memcache_req_buf (struct memcache_req *req);

   391

   392

/*

   402

 * Free a req that is in the STATE_DONE, STATE_DATA_DONE or STATE_ERROR state.

   403

 */

   404

void memcache_req_free (struct memcache_req *req);

   405

   406

#endif /* MEMCACHE_H */