24

    /*

    25

     * Pointer to a char buffer containing the key itself.

    26

     *

    27

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

    28

     *

    29

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

    30

     * presumeably cause a CLIENT_ERROR reply).

    31

     *

    32

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

    33

     * delimit tokens in the protocol itself.

    34

     *

    35

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

    36

     */

    38

    39

    /*

    40

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

    41

     */

    49

    /*

    50

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

    51

     */

    53

    54

    /*

    55

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

    56

     * or an absolute 32-bit unix timestamp.

    57

     */

    59

    60

    /*

    61

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

    62

     */

    64

    65

    /*

    66

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

    67

     *

    68

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

    69

     */

    77

    /*

    78

     * The char buffer containing the data.

    79

     */

    81

    82

    /*

    83

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

    84

     */

    86

    87

    /*

    88

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

    89

     *

    90

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

    91

     */

   100

   101

    /*

   102

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

   103

     *

   104

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

   105

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

   106

     */

   107

    MEMCACHE_CMD_FETCH_GET,

   109

    /*

   110

     * Store this data.

   111

     *

   112

     * Returns either RPL_STORED or RPL_NOT_STORED.

   113

     */

   115

   116

    /*

   117

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

   118

     *

   119

     * Returns either RPL_STORED or RPL_NOT_STORED.

   120

     */

   122

   123

    /*

   124

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

   125

     *

   126

     * Returns either RPL_STORED or RPL_NOT_STORED.

   127

     */

   129

   130

    /*

   131

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

   132

     *

   133

     * obj.flags and obj.exptime are ignored.

   134

     *

   135

     * Returns ???

   136

     */

   138

   139

    /*

   140

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

   141

     *

   142

     * obj.flags and obj.exptime are ignored.

   143

     *

   144

     * Returns ???

   145

     */

   147

   148

    /*

   149

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

   150

     *

   151

     * obj.cas is required.

   152

     *

   153

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

   154

     * exist or has been deleted).

   155

     */

   161

/*

   162

 * Replies from the server

   163

 */

   166

   167

    /*

   168

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

   169

     */

   170

    MEMCACHE_RPL_ERROR,

   172

    /*

   173

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

   174

     */

   176

   177

    /*

   178

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

   179

     */

   182

    // CMD_FETCH_*

   183

   184

    /*

   185

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

   186

     */

   188

   189

    /*

   190

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

   191

     */

   194

    // CMD_STORE_*

   195

   196

    /*

   197

     * The object was succesfully stored in the cache.

   198

     */

   200

   201

    /*

   202

     * The object was not stored in the cache.

   203

     *

   204

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

   205

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

   206

     */

   208

   209

    /*

   210

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

   211

     * obj.cas does not match).

   212

     */

   214

   215

    /*

   216

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

   217

     */

   225

   226

    /*

   227

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

   228

     */

   229

    MEMCACHE_STATE_QUEUED,

   231

    /*

   232

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

   233

     */

   235

   236

    /*

   237

     * The reply has been received.

   238

     *

   239

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

   240

     */

   243

    /*

   244

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

   245

     *

   246

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

   247

     */

   248

    MEMCACHE_STATE_REPLY_DATA,

   249

   250

    /*

   251

     * The full reply has been received.

   252

     *

   253

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

   254

     */

   256

   257

    /*

   258

     * The full reply and reply data has been received.

   259

     *

   260

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

   261

     */

   263

   264

    /*

   265

     * An error has occurred.

   266

     *

   267

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

   268

     */

   289

 *

   290

 * The state machine will work as follows:

   291

 *

   292

 *  req_state                  multi   req_reply

   293

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

   294

 *  STATE_QUEUE                 ?

   295

 *  STATE_SEND

   296

 *  STATE_REPLY                         RPL_VALUE

   297

 *      STATE_REPLY_DATA        *       RPL_VALUE

   298

 *      STATE_DATA_DONE                 RPL_END

   299

 *

   300

 *      STATE_DONE                      RPL_END

   301

 *

   302

 *  STATE_ERROR                         RPL_{ERROR,CLIENT_ERROR,SERVER_ERROR}

   303

 *

   304

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

   309

 * Attempt to store an item into the cache.

   310

 *

   311

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

   312

 *

   313

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

   314

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

   315

 *

   316

 * The state machine will work as follows:

   317

 *

   318

 *  req_state               multi       req_reply

   319

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

   320

 *  STATE_QUEUE             ?

   321

 *  STATE_SEND

   322

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

   323

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

   324

 * 

   325

 *  STATE_ERROR                         RPL_{ERROR,CLIENT_ERROR,SERVER_ERROR}

   326

 *

   328

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

   331

 * Request state.

   332

 *

   333

 * Should always return a valid value.

   338

 * Request command.

   339

 *

   340

 * Should always return a valid value.

   342

enum memcache_command memcache_req_cmd (struct memcache_req *req);

   345

 * Request reply.

   346

 *

   347

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

   349

enum memcache_reply memcache_req_reply (struct memcache_req *req);

   350

   351

/*

   352

 * Request key.

   353

 *

   354

 * Will return a valid valuein all states

   355

 */

   356

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

   357

   358

/*

   359

 * Request data.

   360

 *

   361

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

   362

 */

   363

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

   364

   365

/*

   366

 * Request buf.

   367

 *

   368

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

   369

 *

   370

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

   371

 */

   372

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

   373

   374

/*

   375

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

   376

 */

   377

void memcache_req_free (struct memcache_req *req);