Client Flags...

Sean Chittenden sean at chittenden.org
Wed Dec 15 22:45:30 PST 2004


> It was originally 32 bits, but we figured that was excessive, and 
> trimmed
> it during one of our early struct item slimming sessions.

Is anyone actually using more than 256 different client flags?  I'd be 
*very* interested in such a use case.

> I see no reason to change it.

Here's the current FETCH Packet for the Binary Protocol.  I'm running 
into an alignment issue and think it'd be keen to move the Client Flag 
into the Options 3 byte given it's unused.  I'm also running out of 
options bits, so I'm not that dead set on it, but I think the feature 
creep is coming to a close and am not sure I'll spill into Options 3 
unless someone comes up with a class of options that I haven't 
accounted for already.  Maybe make the hold timer a u_int16_t value 
instead of a u_int32_t value?  *shrug*  It's only two bytes, so it's 
not that crucial, but I'm not a fan of having padding in there when it 
potentially could be avoided.  -sc


The FETCH Packet:

The FETCH Packet is the only way to fetch data from the server.

  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    Request    |   Options 1   |   Options 2   |   Options 3   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                          Key Length                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/         Client Flags          |         Zero'ed Bytes         /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/                          Hold Timer                           /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
/                              Key                              /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Request (required):
         All packets other than the HELLO packet contains a Request
         byte.  Each value for the request byte is unique for the
         protocol version.  The FETCH Packet has a request value of
         'f'.

Options 1 (required):
         These bits refer to the bits in the Options 1 Byte.

         Bit 0:  If this key exists and has a relative expiration, reset
                 the expiration to be be relative to the current time.
         Bit 1:  Request that the server delete the key after sending
                 the value to the client.
         Bit 2:  After the server has processed this request, close the
                 connection.
         Bit 3:  If the key exists, include the expiration of the key in
                 the response from the server.
         Bit 4:  If the key exists, include the number of fetch requests
                 left for this key.
         Bit 5:  Don't send the value (ie, return with a zero value
                 length DATA Packet).  Useful for obtaining
                 metrics/stats as use of this bit will almost always
                 not change the value of stats counters or last access
                 times.
         Bit 6:  This request includes a Hold Timer where the key is
                 frozen.
         Bit 7:  The key is a wildcard key.  Everything after the key is
                 assumed to be unanchored.  This is the SQL equivalent
                 of LIKE 'key%' or regular expression equivalent of
                 m/^${key}.*/

Options 2 (required):
         These bits refer to the bits in the Options 2 Byte.

         Bit 0:  When returning a DATA packet, return the number of
                 requests made for this key.
         Bit 1:  When returning a DATA packet, return the number of
                 seconds since the data for this packet was sent to
                 a client.
         Bit 2:  Return with a RESPONSE Packet, not a DATA Packet.
                 This effectively sets Bit 5 in Option Byte 1.  Delete
                 operations should use this bit and not Bit 5 in Option
                 Byte 1 of this packet.
         Bit 3:  Return data only if the Client Flags field matches the
                 client flags for the key.
         Bit 4-7:   Not designated

Options 3 (required):
         These bits refer to the bits in the Options 3 Byte.

         Bit 0-7:   Not designated

Key Length (required):
         Specify the length of the key.  The key length has a valid
         range of 1 - 4294967296.

Client Flags (optional):
         This field is required when Bit 3 of the Options Byte 2 is
         set.  Contains the client flags.

Zero'ed Bytes (optional):
         This field is required when Bit 3 of the Options Byte 2 is
         set.  Contains zero'ed bytes that are ignored by the server.

Hold Timer (optional):
         This field is required when Bit 6 of the Options Byte 1 is
         set.  If Bit 1 of Option Byte 1 is set, this acts as a hold
         timer for adding values with the same key.  If Bit 1 of Option
         Byte 1 is not set, FETCH requests for this key will return
         'n'ot found with the 'h' Minor Status value set.

Key (required):
         The key for the given request.  Keys are not padded by a null
         character.


The MULTI-FETCH Packet:

The MULTI-FETCH Packet is sent ahead of a FETCH Packet to denote that
the server should expect more than one FETCH Packet.  Omitting a
MULTI-FETCH Packet ahead of a series of FETCH Packets is allowed,
however it will degrade performance by increasing the number of
packets sent back and forth between the client and server.  Use of the
MULTI-FETCH Packet where appropriate is strongly advised.

  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|    Request    |    Number of FETCH Packets    |   Options 1   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Request (required):
         All packets other than the HELLO packet contains a Request
         byte.  Each value for the request byte is unique for the
         protocol version.  The MULTI-FETCH Packet has a request value
         of 'm'.

Number of FETCH Packets (required):
        Number of FETCH Packets that will follow a MULTI-FETCH Packet.
        A MULTI-FETCH Packet with this field set to one is acceptable,
        but not encouraged.

Options 1 (required):
         These bits refer to the bits in the Options 1 Byte.

         Bit 0-7:        Not Designated.

-- 
Sean Chittenden



More information about the memcached mailing list