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.

    12

 *

    13

 * Each context has one callback function defined, which is used for all requests.

    14

 */

    15

struct memcache;

    16

    17

/*

    18

 * A transaction.

    19

 *

    20

 * Each request has one callback argument defined, which is used for that request's callbacks.

    21

 */

    22

struct memcache_req;

    23

    24

/*

    25

 * Object keys

    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

     * If this is given as zero, then the length will be calculated from buf using strlen(). Empty keys are not

    47

     * allowed, so this will result in an error if buf is an empty string.

    48

     */

    49

    size_t len;

    50

};

    51

    52

/*

    53

 * Object attributes

    54

 */

    55

struct memcache_obj {

    56

    /*

    57

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

    58

     */

    59

    unsigned int flags;

    60

    61

    /*

    62

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

    63

     * or an absolute 32-bit unix timestamp.

    64

     */

    65

    time_t exptime;

    66

    67

    /*

    68

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

    69

     */

    70

    size_t bytes;

    71

    72

    /*

    73

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

    74

     *

    75

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

    76

     */

    77

    unsigned long long cas;

    78

};

    79

    80

/*

    81

 * Object data

    82

 */

    83

struct memcache_buf {

    84

    /*

    85

     * The char buffer containing the data.

    86

     */

    87

    char *data;

    88

    89

    /*

    90

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

    91

     */

    92

    size_t len;

    93

    94

    /*

    95

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

    96

     *

    97

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

    98

     */

    99

    size_t offset;

   100

};

   101

   102

/*

   103

 * Available commands

   104

 */

   105

enum memcache_command {

   106

    MEMCACHE_CMD_INVALID,

   107

   108

    /*

   109

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

   110

     *

   111

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

   112

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

   113

     */

   114

    MEMCACHE_CMD_FETCH_GET,

   115

   116

    /*

   117

     * Store this data.

   118

     *

   119

     * Returns either RPL_STORED or RPL_NOT_STORED.

   120

     */

   121

    MEMCACHE_CMD_STORE_SET,

   122

   123

    /*

   124

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

   125

     *

   126

     * Returns either RPL_STORED or RPL_NOT_STORED.

   127

     */

   128

    MEMCACHE_CMD_STORE_ADD,

   129

   130

    /*

   131

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

   132

     *

   133

     * Returns either RPL_STORED or RPL_NOT_STORED.

   134

     */

   135

    MEMCACHE_CMD_STORE_REPLACE,

   136

   137

    /*

   138

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

   139

     *

   140

     * obj.flags and obj.exptime are ignored.

   141

     *

   142

     * Returns ???

   143

     */

   144

    MEMCACHE_CMD_STORE_APPEND,

   145

   146

    /*

   147

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

   148

     *

   149

     * obj.flags and obj.exptime are ignored.

   150

     *

   151

     * Returns ???

   152

     */

   153

    MEMCACHE_CMD_STORE_PREPEND,

   154

   155

    /*

   156

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

   157

     *

   158

     * obj.cas is required.

   159

     *

   160

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

   161

     * exist or has been deleted).

   162

     */

   163

    MEMCACHE_CMD_STORE_CAS,

   164

   165

    MEMCACHE_CMD_MAX,

   166

};

   167

   168

/*

   169

 * Replies from the server

   170

 */

   171

enum memcache_reply {

   172

    MEMCACHE_RPL_INVALID,

   173

   174

    /*

   175

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

   176

     */

   177

    MEMCACHE_RPL_ERROR,

   178

   179

    /*

   180

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

   181

     */

   182

    MEMCACHE_RPL_CLIENT_ERROR,

   183

   184

    /*

   185

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

   186

     */

   187

    MEMCACHE_RPL_SERVER_ERROR,

   188

   189

    // CMD_FETCH_*

   190

   191

    /*

   192

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

   193

     */

   194

    MEMCACHE_RPL_VALUE,

   195

   196

    /*

   197

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

   198

     */

   199

    MEMCACHE_RPL_END,

   200

   201

    // CMD_STORE_*

   202

   203

    /*

   204

     * The object was succesfully stored in the cache.

   205

     */

   206

    MEMCACHE_RPL_STORED,

   207

   208

    /*

   209

     * The object was not stored in the cache.

   210

     *

   211

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

   212

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

   213

     */

   214

    MEMCACHE_RPL_NOT_STORED,

   215

   216

    /*

   217

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

   218

     * obj.cas does not match).

   219

     */

   220

    MEMCACHE_RPL_EXISTS,

   221

   222

    /*

   223

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

   224

     */

   225

    MEMCACHE_RPL_NOT_FOUND,

   226

   227

    MEMCACHE_RPL_MAX,

   228

};

   229

   230

/*

   231

 * Request states

   232

 */

   233

enum memcache_state {

   234

    MEMCACHE_STATE_INVALID,

   235

   236

    /*

   237

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

   238

     */

   239

    MEMCACHE_STATE_QUEUED,

   240

   241

    /*

   242

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

   243

     */

   244

    MEMCACHE_STATE_SEND,

   245

   246

    /*

   247

     * The reply has been received.

   248

     *

   249

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

   250

     */

   251

    MEMCACHE_STATE_REPLY,

   252

   253

    /*

   254

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

   255

     *

   256

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

   257

     */

   258

    MEMCACHE_STATE_REPLY_DATA,

   259

   260

    /*

   261

     * The full reply has been received.

   262

     *

   263

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

   264

     */

   265

    MEMCACHE_STATE_DONE,

   266

   267

    /*

   268

     * The full reply and reply data has been received.

   269

     *

   270

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

   271

     */

   272

    MEMCACHE_STATE_DONE_DATA,

   273

   274

    /*

   275

     * An error has occurred.

   276

     *

   277

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

   278

     */

   279

    MEMCACHE_STATE_ERROR,

   280

};

   281

   282

/*

   283

 * Callback used.

   284

 *

   285

 * This is called whenever the request's state changes, including when new data is received in the STATE_REPLY_DATA

   286

 * state.

   287

 */

   288

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

   289

   290

/*

   291

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

   292

 *

   293

 * The given callback function is used for all requests in this context.

   294

 */

   296

   297

/*

   298

 * Add a server to the pool of available servers.

   299

 *

   300

 * At most <max_connections> connections will be kept open to this server, and additional requests will be queued.

   301

 */

   302

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

   303

   304

/*

   305

 * Attempt to fetch a key from the cache.

   306

 *

   307

 * The given callback argument will be used when invoking the context's callback for this request.

   308

 *

   309

 * The state machine will work as follows:

   310

 *

   311

 *  req_state                  multi   req_reply

   312

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

   313

 *  STATE_QUEUE                 ?

   314

 *  STATE_SEND

   315

 *      STATE_REPLY                     RPL_VALUE

   316

 *      STATE_REPLY_DATA        *       RPL_VALUE

   317

 *      STATE_REPLY_DATA                RPL_END

   318

 *      STATE_DONE_DATA                 RPL_END

   319

 *

   320

 *      STATE_REPLY                     RPL_END

   321

 *      STATE_DONE                      RPL_END

   322

 *

   323

 *  STATE_ERROR                         RPL_{ERROR,CLIENT_ERROR,SERVER_ERROR}

   324

 *

   325

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

   326

 */

   327

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

   328

   329

/*

   330

 * Attempt to store an item into the cache.

   331

 *

   332

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

   333

 *

   334

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

   335

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

   336

 * 

   337

 * The given callback argument will be used when invoking the context's callback for this request.

   338

 *

   339

 * The state machine will work as follows:

   340

 *

   341

 *  req_state               multi       req_reply

   342

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

   343

 *  STATE_QUEUE             ?

   344

 *  STATE_SEND

   345

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

   346

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

   347

 * 

   348

 *  STATE_ERROR                         RPL_{ERROR,CLIENT_ERROR,SERVER_ERROR}

   349

 *

   350

 */

   351

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);

   352

   353

/*

   354

 * Request state.

   355

 *

   356

 * Should always return a valid value.

   357

 */ 

   358

enum memcache_state memcache_req_state (struct memcache_req *req);

   359

   360

/*

   361

 * Request command.

   362

 *

   363

 * Should always return a valid value.

   364

 */

   365

enum memcache_command memcache_req_cmd (struct memcache_req *req);

   366

   367

/*

   368

 * Request reply.

   369

 *

   370

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

   371

 */

   372

enum memcache_reply memcache_req_reply (struct memcache_req *req);

   373

   374

/*

   375

 * Request key.

   376

 *

   377

 * Will return a valid valuein all states

   378

 */

   379

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

   380

   381

/*

   382

 * Request data.

   383

 *

   384

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

   385

 */

   386

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

   387

   388

/*

   389

 * Request buf.

   390

 *

   391

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

   392

 *

   393

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

   394

 */

   395

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

   396

   397

/*

   398

 * Abort a running request, regardless of what state it is in.

   399

 *

   400

 * You do not need to call req_free after this.

   401

 *

   402

 * XXX: unimplemented

   403

 */

   404

void memcache_req_abort (struct memcache_req *req);

   405

   406

/*

   407

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

   408

 */

   409

void memcache_req_free (struct memcache_req *req);

   410

   411

/*

   412

 * Translate commands/replies/states into strings.

   413

 */

   414

const char *memcache_command_str (enum memcache_command cmd);

   415

const char *memcache_reply_str (enum memcache_reply reply);

   416

const char *memcache_state_str (enum memcache_state state);

   417

   418

#endif /* MEMCACHE_H */