diff --git a/.classpath b/.classpath new file mode 100644 index 0000000..c9464c0 --- /dev/null +++ b/.classpath @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/.gitignore b/.gitignore index 8982d11..6e5a68e 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,11 @@ dist/ scratch/ .cachedir/ memcached-release* +/bin +/target +/java_memcached-release* +/release.properties +/pom.xml.releaseBackup +/ocalCheckout=true +/pom.xml.next +/pom.xml.tag diff --git a/.project b/.project new file mode 100644 index 0000000..a68f439 --- /dev/null +++ b/.project @@ -0,0 +1,23 @@ + + + Memcached-Java-Client + + + + + + org.eclipse.jdt.core.javabuilder + + + + + org.eclipse.m2e.core.maven2Builder + + + + + + org.eclipse.jdt.core.javanature + org.eclipse.m2e.core.maven2Nature + + diff --git a/.settings/org.eclipse.core.resources.prefs b/.settings/org.eclipse.core.resources.prefs new file mode 100644 index 0000000..843df19 --- /dev/null +++ b/.settings/org.eclipse.core.resources.prefs @@ -0,0 +1,5 @@ +#Fri Nov 25 11:05:34 CST 2011 +eclipse.preferences.version=1 +encoding//src/main/java=UTF-8 +encoding//src/test/java=UTF-8 +encoding/=UTF-8 diff --git a/.settings/org.eclipse.jdt.core.prefs b/.settings/org.eclipse.jdt.core.prefs new file mode 100644 index 0000000..14f521d --- /dev/null +++ b/.settings/org.eclipse.jdt.core.prefs @@ -0,0 +1,5 @@ +eclipse.preferences.version=1 +org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.6 +org.eclipse.jdt.core.compiler.compliance=1.6 +org.eclipse.jdt.core.compiler.problem.forbiddenReference=warning +org.eclipse.jdt.core.compiler.source=1.6 diff --git a/.settings/org.eclipse.m2e.core.prefs b/.settings/org.eclipse.m2e.core.prefs new file mode 100644 index 0000000..d054681 --- /dev/null +++ b/.settings/org.eclipse.m2e.core.prefs @@ -0,0 +1,5 @@ +#Fri Sep 30 12:12:40 CST 2011 +activeProfiles= +eclipse.preferences.version=1 +resolveWorkspaceProjects=true +version=1 diff --git a/README b/README new file mode 100644 index 0000000..c153389 --- /dev/null +++ b/README @@ -0,0 +1,64 @@ +#Author Xingen Wang (new.root@gmail.com) + Meng Li (jowett.lee@gmail.com) +Release 3.0.0: +Change the domain name in order to put the library into maven central. + +Release 2.6.6: +Resove issue #38. you can now get Boolean, Long with gets command in AsciiClient. + +Release 2.6.5: +since nio doesn't support soTimeout, solve this issue in com.schooner.MemCached.SockInputStream.readFromChannel(). + +Release 2.6.4: +add storeCounter with expiry support. + +Release 2.6.3: +Perhaps solve the hang issue. + +Release 2.6.1: +Add failback support. +We also re-implement the connection pool based on Apache commons pool in this release. +Fix issue 18. + +TODO: +We will add SASL support in next version. + +Release 2.6.0: +add slf4j logger support. +because compress is so slow, we remove this feature in this release. +we also remove error handler feature and classloader feature in this release. +fix issue 19. + +TODO: +We will add SASL support in next version. +Perhaps, we will get rid of the direct buffer, since it cause OutOfMemoryError. + + + +Release 2.5.x: +This is a performance branch for the whalin memcached java client, +which was first maintained by Greg Whalin and perhaps the most +popular memcached java client in past years. While in recent years, +some new memcached clients were found in the open source world, and +most of them has better performance compared to the old version. + +Considering the wide use of this old client, we intend to make it run +faster and try to make the new one 100% compatible with the old version. + +this 2.5.x version is supported by Schooner Information Technology, which +provides professional storage service over all all the world. + +Whalin client 2.5.x is proven to be 270% faster compared to the old version(2.0.1), +and we also did some comparison with other clients, please find the result +from following link: +https://github.com/gwhalin/Memcached-Java-Client/wiki/PERFORMANCE + +Usage: +Just use as the previous version(2.0.1), if you've already used it, just replace +the old version with the newer version(2.5.x). We believe it will give you surprise. + +Maintainers: +Greg Whalin +Xingen Wang +Meng Li + diff --git a/adv_config.xml b/adv_config.xml new file mode 100644 index 0000000..0c11c7b --- /dev/null +++ b/adv_config.xml @@ -0,0 +1,37 @@ + + + + + + + + + + diff --git a/build.properties b/build.properties new file mode 100644 index 0000000..e3c8607 --- /dev/null +++ b/build.properties @@ -0,0 +1,43 @@ +#------------------------------------------------------------------------------- +# Copyright (c) 2009 Schooner Information Technology, Inc. +# All rights reserved. +# +# http://www.schoonerinfotech.com/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# 3. The name of the author may not be used to endorse or promote products +# derived from this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +#------------------------------------------------------------------------------- +doc.dir=doc +src.dir=src/main/java +test.dir=src/test/java +build.dir=classes +test.build.dir=testclasses +build.instr.dir=classesinstr +project=java_memcached-release +ver=3.0.0 +junit.jar=lib/junit.jar +slf4japi.jar=lib/slf4j-api-1.6.1.jar +slf4jsimple.jar=lib/slf4j-simple-1.6.1.jar +emma.dir=lib +emma.enabled=true +report.dir=report +memcached.host=localhost:11211,localhost:11212 diff --git a/build.xml b/build.xml index 917b1d9..5166623 100644 --- a/build.xml +++ b/build.xml @@ -1,121 +1,209 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/CHANGELOG.txt b/doc/CHANGELOG.txt index b205def..0dcb053 100644 --- a/doc/CHANGELOG.txt +++ b/doc/CHANGELOG.txt @@ -1,3 +1,21 @@ +13 Nov 2009 (Xingen Wang, Meng Li, Qinliang Ling) + -- Refine source code and get compatible with Whalin memcached java client. + -- Reduce the initialization of MemcachedItem and performance increased 10%. + -- Add buffer size control and support big data more than 1MB. + -- Add maximum connection number control and fix the bugs in connection pool maintenance. + +24 Aug 2009 (Xingen Wang, Meng Li, Qinliang Ling) + -- performance increased 50% for udp protocol + +10 Jun 2009 (Xingen Wang, Meng Li, Qinliang Ling) + -- performance increased 270% + -- you can now specify transcoder to customize serialization and deserialization. + -- NIO in every place. + -- Direct Buffer used. + -- Simplify the logic of the source codes. + -- binary protocol supported in this release. + -- udp protocol supported in this release. + 28 Dec 2008 (gwhalin,pinkerton) -- released as 2.0 -- much reduced lock contention diff --git a/doc/COMPATIBLE.txt b/doc/COMPATIBLE.txt new file mode 100644 index 0000000..b3ddec7 --- /dev/null +++ b/doc/COMPATIBLE.txt @@ -0,0 +1,35 @@ +Known compatible issues with Whalin client 2.0.1: + +This version includes all the public APIs in Whalin, so that any legacy systems +can use this Java client without re-compiling source code. Due to our test, you can set +key/value pairs with whalin client 2.0.1 and get the key/value pairs with this new client +for all the native objects and default java object. But some of the APIs are fake, so +maybe there are still some compatible issues. + +Since Whalin only supports memcached text protocol, there is no compatible +issues when you are using binary or UDP client. + +Known issues: +============= +1. The following are fake APIs which are kept in this version to ensure the +legacy system can use our Java client: +MemCachedClient: + 1) setCompressEnable(boolean) + 2) setCompressThreshold(long) +Compress in LAN is not a good idea, it consumes a lot of CPU resources and achieve little benefit. +In our new client, compress is fake APIs, we don't compress anything in our client, but we will +decompress the data from the server side for those key/value pairs set with old whalin client. + +SockIOPool: + 3) getAliveCheck() + 4) getFailback() + 5) getFailover() + 6) getMaintSleep() + 7) getMaxBusy() + 8) getMaxIdle() + 9) setAliveCheck(boolean) + 10) setFailback(boolean) + 11) setFailover(boolean) + 12) setMaintSleep(long) + 13) setMaxBusyTime(long) + 14) setMaxIdle(long) \ No newline at end of file diff --git a/doc/CVS/Entries b/doc/CVS/Entries deleted file mode 100644 index d5d5a2f..0000000 --- a/doc/CVS/Entries +++ /dev/null @@ -1,6 +0,0 @@ -/LICENSE.txt/1.1/Mon Nov 29 18:11:59 2004// -/PORTABILITY.txt/1.2/Wed Aug 4 16:28:46 2004// -/README.txt/1.2/Wed Aug 4 16:28:46 2004// -/TODO.txt/1.5/Mon Jan 17 19:03:01 2005// -/CHANGELOG.txt/1.13/Sun Feb 6 17:22:59 2005// -D diff --git a/doc/CVS/Repository b/doc/CVS/Repository deleted file mode 100644 index 309e07c..0000000 --- a/doc/CVS/Repository +++ /dev/null @@ -1 +0,0 @@ -chapstick_java/src/com/danga/MemCached/doc diff --git a/doc/CVS/Root b/doc/CVS/Root deleted file mode 100644 index 08bddd8..0000000 --- a/doc/CVS/Root +++ /dev/null @@ -1 +0,0 @@ -:ext:cvs.dev.meetup.com:/usr/local/cvs diff --git a/doc/DEV_HOWTO.txt b/doc/DEV_HOWTO.txt new file mode 100644 index 0000000..6923c4b --- /dev/null +++ b/doc/DEV_HOWTO.txt @@ -0,0 +1,66 @@ + +Software requirement +======================= +1. JDK 1.5+ +2. Apache Ant 1.7.1+ +Uncompress the source package and enter the top of directory. + +How to build the source code +============================= +1. Run the following command, binary and test jar package will be generated for you. +ant jar +2. java_memcached-release_{version}.jar is the binary package. +3. java_memcached-release_test_{version}.jar is the test package. + +Unit test and code coverage +============================ +1. Open build.properties and set the entry "memcached.host" points to the +address of memcached server like this . +2. Run the ant task: +ant +3. When the ant task finishes successfully, a directory named report will +be created and all the unit test reports are in the directory. "index.html" +is the entrance of the unit test report and "coverage.html" is the entrance +of code coverage report. + +Simple performance test +======================== +1. MemCachedBenchTcp +java -Dmemcached.host= \ + -cp .:schooner-memcached-client-test-1.0.1.jar:schooner-memcached-client-bin-1.0.1.jar \ + com.schooner.MemCached.MemCachedBenchTcp + +2. MemCachedBenchUdp +java -Dmemcached.host= \ + -cp .:schooner-memcached-client-test-1.0.1.jar:schooner-memcached-client-bin-1.0.1.jar \ + com.schooner.MemCached.MemCachedBenchUdp + +Advanced checker +================= +The advanced checker provides some dynamic test features. It can be configured through XML file: + +You can find the default configuration file("adv_config.xml") in root directory of the source code. + +The advChecker will verify memcached client periodically and write error log into file "advChecker_errors.log" +if we can't retrieve the stored data. + + + + + + + + + + + +thread: the number of thread; +runtime: the run time of the checker; +sleep: the sleep time between two operations; +checkInterval: the time interval between two checks. +name: command name; +percent: The proportion of this command. + +run the advanced checker: +java -cp .:schooner-memcached-client-test-1.0.1.jar:schooner-memcached-client-bin-1.0.1.jar \ + com.schooner.MemCached.MemcachedClientAdvChecker \ No newline at end of file diff --git a/doc/HOWTO.txt b/doc/HOWTO.txt index e5961dd..15356fe 100644 --- a/doc/HOWTO.txt +++ b/doc/HOWTO.txt @@ -7,7 +7,7 @@ Basic Example: Lets say you have 3 servers. Server 1 and server 2 have 3GB of space and server 3 has 2GB of space for cache. Here is how I would set up my client. - +----------------------------------------------------------------------------- import com.danga.MemCached.*; public class MyClass { @@ -35,20 +35,6 @@ public class MyClass { pool.setServers( servers ); pool.setWeights( weights ); - // set some basic pool settings - // 5 initial, 5 min, and 250 max conns - // and set the max idle time for a conn - // to 6 hours - pool.setInitConn( 5 ); - pool.setMinConn( 5 ); - pool.setMaxConn( 250 ); - pool.setMaxIdle( 1000 * 60 * 60 * 6 ); - - // set the sleep for the maint thread - // it will wake up every x seconds and - // maintain the pool size - pool.setMaintSleep( 30 ); - // set some TCP settings // disable nagle // set the read timeout to 3 secs @@ -59,61 +45,27 @@ public class MyClass { // initialize the connection pool pool.initialize(); - - - // lets set some compression on for the client - // compress anything larger than 64k - mcc.setCompressEnable( true ); - mcc.setCompressThreshold( 64 * 1024 ); } // from here on down, you can call any of the client calls public static void examples() { mcc.set( "foo", "This is a test String" ); - String bar = mcc.get( "foo" ); + String bar = mcc.get( "foo" ).toString(); } } - +------------------------------------------------------------------------------- Multi-client Example: ===================== If you need to support multiple clients (i.e. Java, PHP, Perl, etc.) you need to make a few changes when you are setting things up: - +----------------------------------------------------------------- // use a compatible hashing algorithm pool.setHashingAlg( SockIOPool.NEW_COMPAT_HASH ); - - // store primitives as strings - // the java client serializes primitives - // - // note: this will not help you when it comes to - // storing non primitives - mcc.setPrimitiveAsString( true ); - - // don't url encode keys - // by default the java client url encodes keys - // to sanitize them so they will always work on the server - // however, other clients do not do this - mcc.setSanitizeKeys( false ); - - -Failover/Failback Notes: -======================== - -By default the java client will failover to a new server when a server -dies. It will also failback to the original if it detects that the -server comes back (it checks the server in a falling off pattern). - -If you want to disable this (useful if you have flapping servers), -there are two settings to handle this. - - pool.setFailover( false ); - pool.setFailback( false ); - +------------------------------------------------------------------- Serialization: ============== - For java "native types", which include: Boolean @@ -130,20 +82,114 @@ Date Integer The client will by default *NOT* use java serialization, and instead -will serialize using the primitive values to save space. You can -override this by using the mcc.setPrimitiveAsString( true ), which -will use the toString representation of the object. +will serialize using the primitive values to save space. + +For other java objects, you have 2 options to serialize the java objects. +one is make sure the class implements Serializable in order to be able +to be stored with default object transcoder provided by this client; +The other alternative is to write your own transcoder to do the serialization +and deserialization by yourself, the following is simple example: +------------------------------------------------------------------------- +package com.schooner.MemCached; +import java.io.ByteArrayInputStream; +import java.io.IOException; +import java.io.InputStream; +import java.io.ObjectInputStream; +import java.io.ObjectOutputStream; +import java.io.OutputStream; +/** + * {@link ObjectTransCoder} is the default TransCoder used to handle the + * serialization and deserialization in memcached operations. + * + * @author Xingen Wang + * @see AbstractTransCoder + * @see TransCoder + */ +public class ObjectTransCoder extends AbstractTransCoder { + + /* + * (non-Javadoc) + * + * @see com.schooner.MemCached.TransCoder#decode(InputStream) + */ + public Object decode(final InputStream input) throws IOException { + Object obj = null; + ObjectInputStream ois = new ObjectInputStream(input); + try { + obj = ois.readObject(); + } catch (ClassNotFoundException e) { + throw new IOException(e.getMessage()); + } + ois.close(); + return obj; + } -For other java objects, you need to make sure the class implements -Serializable in order to be able to be stored in the cache. + /* + * (non-Javadoc) + * + * @see + * com.schooner.MemCached.AbstractTransCoder#encode(java.io.OutputStream, + * java.lang.Object) + */ + public void encode(final OutputStream output, final Object object) throws IOException { + ObjectOutputStream oos = new ObjectOutputStream(output); + oos.writeObject(object); + oos.close(); + } -I would also reccomend that if possible, classes should instead -implement Externalizable as opposed to Serializable. This allows the + public Object decode(byte[] input){ + Object obj = null; + try { + ObjectInputStream ois = new ObjectInputStream( + new ByteArrayInputStream(input)); + obj = ois.readObject(); + ois.close(); + } catch (IOException e) { + // TODO Auto-generated catch block + e.printStackTrace(); + } catch (ClassNotFoundException e) { + // TODO Auto-generated catch block + e.printStackTrace(); + } + return obj; + } +} +----------------------------------------------------------------------------------------- +After that, you should set transcoder to your client: +----------------------------------------------------------------------------- +MemCachedClient mc = new MemCachedClient(); +mc.setTransCoder(new YourTransCoder()); +----------------------------------------------------------------------------- + +I would also recommend that if possible, classes should instead +implement Externalizable as opposed to Serializable or write the +transcoder by your self. This allows the author of the class to define how objects of that class should serialize. In practice at Meetup.com, we saw a 60% reduction in the size of our serialized objects by doing this. This means less data to eat up cache space and less data to transfer over the network. +binary protocol: +================ +In Schooner's implementation, binary protocol for memcached has been implemented, and +due to our test performance increased about 5% overall, but you have to use +memcached 1.4+ in the server side to support this features. +The following code snipets shows how to use this feature: +----------------------------------------------------------------------------- +mc = new MemCachedClient(true, true); +----------------------------------------------------------------------------- + +UDP protocol: +============= +In schooner's implementation, UDP protocol for memcached is also supported. While due +to our test, the performance is not that good as tcp protocol, we are still working on +performance tuning. +In our latest implementation, UDP protocol works in asynchronized mode. +We recommend user memcached 1.4.4+ when UDP protocol is used. +----------------------------------------------------------------------------- +mc = new MemCachedClient(false, false); +----------------------------------------------------------------------------- + Other: ====== -See the java docs. +See the java docs. \ No newline at end of file diff --git a/doc/LICENSE.txt b/doc/LICENSE.txt index 3da12a9..ee757ea 100644 --- a/doc/LICENSE.txt +++ b/doc/LICENSE.txt @@ -1,3 +1,5 @@ +LGPLv3 + * Copyright (c) 2007, Greg Whain * All rights reserved. * @@ -22,3 +24,33 @@ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +******************************************************************************** + +/******************************************************************************* + * Copyright (c) 2009 Schooner Information Technology, Inc. + * All rights reserved. + * + * http://www.schoonerinfotech.com/ + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. The name of the author may not be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ \ No newline at end of file diff --git a/doc/PORTABILITY.txt b/doc/PORTABILITY.txt index 6f67dca..1a3fbb9 100644 --- a/doc/PORTABILITY.txt +++ b/doc/PORTABILITY.txt @@ -1,6 +1,7 @@ This file lists the portability status of this client. Please send me any -additional information (greg@meetup.com). +additional information. The newest release has only been tested on: Sun's JRE 5 and up on Linux/x86/amd64 +Sun's JRE 5 and up on Windows/x86/32 diff --git a/doc/README.txt b/doc/README.txt index 6c0222f..09b244a 100644 --- a/doc/README.txt +++ b/doc/README.txt @@ -1,7 +1,25 @@ WARNING! -This version is not compatible with versions prior to version 0.9.2 -Please see javadocs for examples on how to use. +This version is compatible with legacy whalin version, so you can use it without +re-compile your source code in most cases. Refer to COMPATIBLE.txt for detailed information. -This release required Java 5 in order to work. If you would like to downport to 1.4 +This release required Java 5 in order to work. If you would like to degrade to 1.4 please feel free. + + +Known issues: +============= +1. you are always get null when value size is big for windows platform for the UDP protocol. +2. Out of memory when connections number is big. Try to specify more memory with -Xmx. + +Reports: +============ +Find the following reports in the directory. +1. Unit test report + report/index.html +2. Code coverage report + report/coverage.html +3. benchmark test report + doc/benchmark.html +4. javadoc + javadoc/index.html \ No newline at end of file diff --git a/doc/TODO.txt b/doc/TODO.txt index 59c6b30..0358378 100644 --- a/doc/TODO.txt +++ b/doc/TODO.txt @@ -1,8 +1,3 @@ To Do: - -- NIO support for write operations -- removeMulti support -- binary protocol support -- support for new add methods (cas,append,prepend) -- clean up Logging code (auto-detect log4j/logging/etc) -- clean up and add more unit/performance tests +- Increase performance for UDP protocol by decreasing the latency time. +- Give performance test report for UDP protocol. diff --git a/doc/benchmark.html b/doc/benchmark.html new file mode 100644 index 0000000..974fbe4 --- /dev/null +++ b/doc/benchmark.html @@ -0,0 +1,155 @@ + + + + + + +Performance Comparison between Java Memcached Client + + + +

Performance Comparison between Java Memcached Client

+ + +

There are several memcached clients +written in java programming language, including spymemcached, + Java-MemCached , Xmemcached and memcached-client-forjava(A +optimiezed Java-MemCached) etc.
The performance numbers of the 4 open +source memcached clients and schooner memcached client are presented +here to help you make choice.

+ + + +

Test Scenario

+ +

Single memcached server runs on a linux +machine.

+ +

A java client connect to memcached +servers,then start numbers of threads to repeat themself to store and +retrive data from memcachd concurrently,write 50% and read 50%,with no +miss rate.

+ +

Test Environment

+ +
    +
  • Software +
      +
    • 1 Memcached Servers +
        +
      • Version is 1.4.3, default install configuration.
      • +
      • Start with option "-p 12000 -m 2048"
      • +
      +
    • +
    • Java Client +
        +
      • JVM Version: Sun JDK 1.6.0_10 x86_64
      • +
      • Both memcached text protocol and binary protocol is + covered(if supported). +
      • Schoonermemcached 1.0.2, max connection number eq thread number. (binary/udp + protocol supported)
      • +
      • xmemcached 1.2.0 stable, connection pool size eq thread number. (binary protocol supported)
      • +
      • Spymemcached 2.5rc1,default configuration. (binary protocol + supported)
      • +
      • Whalin java client 2.0.1, max connection number eq thread number.
      • +
      • Asfmemcached 2.5.2, max connection number eq thread number.
      • +
      • JVM args: -server -Xmx1024m
      • +
      • Xmemcached and Spymemcached are asynchronized implementations.So they have to set + operation timeout,both are set to 3 seconds.
      • +
      +
    • +
    +
  • +
  • Hardware +
      +
    • Server +
        +
      • CPU: 8 x Intel(R) Xeon(R) CPU X5450 @ 3.00GHz
      • +
      • O/S: 2.6.28.9 x86_64 GNU/Linux (CentOS release 5.2)
      • +
      • RAM: 50 GiB
      • +
      • NIC: 10G QLogic network
      • +
      +
    • +
    • Client (Hostname: Serpent) +
        +
      • CPU: 8 x Intel(R) Xeon(R) CPU X5450 @ 3.00GHz
      • +
      • O/S: 2.6.26.5 x86_64 GNU/Linux (CentOS release 5.2)
      • +
      • RAM: 16 GiB
      • +
      • NIC: 10G QLogic network
      • +
      +
    • +
    +
  • +
+ +

Test Result

+ +

Client and Servers on Different Machines

+

+

Part1 Compare by threads number

+ +
+
+
+
+ +
+
+
+
+ +
+
+
+
+ +
+< + +
+
+
+ +
+
+
+
+ +
+
+
+
+
+

+

Part2 Compare by value size

+ +
+
+
+
+ +
+
+
+
+ +
+
+
+
+ +
+
+
+
+ + \ No newline at end of file diff --git a/doc/binary_protocol.txt b/doc/binary_protocol.txt new file mode 100644 index 0000000..da53814 --- /dev/null +++ b/doc/binary_protocol.txt @@ -0,0 +1,1677 @@ +MemcacheBinaryProtocol +Network Working Group Stone, Ed. +Internet-Draft Six Apart, Ltd. +Intended status: Informational Norbye, Ed. +Expires: March 1, 2009 Sun Microsystems, INC + August 28, 2008 + + + Memcache Binary Protocol + draft-stone-memcache-binary-01 + +Status of this Memo + + This document is an Internet-Draft and is NOT offered in accordance + with Section 10 of RFC 2026, and the author does not provide the IETF + with any rights other than to publish as an Internet-Draft. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on March 1, 2009. + +Abstract + + This memo explains the memcache binary protocol for informational + purposes. + + Memcache is a high performance key-value cache. It is intentionally + a dumb cache, optimized for speed only. Applications using memcache + do not rely on it for data -- a persistent database with guaranteed + reliability is strongly recommended -- but applications can run much + faster when cached data is available in memcache. + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 1] + +Internet-Draft Memcache Binary Protocol August 2008 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Conventions Used In This Document . . . . . . . . . . . . 3 + 2. Packet Structure . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. Defined Values . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.1. Magic Byte . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Response Status . . . . . . . . . . . . . . . . . . . . . 5 + 3.3. Command Opcodes . . . . . . . . . . . . . . . . . . . . . 6 + 3.4. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 6 + 4.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 6 + 4.2. Get, Get Quietly, Get Key, Get Key Quietly . . . . . . . . 7 + 4.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 8 + 4.3. Set, Add, Replace . . . . . . . . . . . . . . . . . . . . 12 + 4.3.1. Example . . . . . . . . . . . . . . . . . . . . . . . 12 + 4.4. Delete . . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 4.4.1. Example . . . . . . . . . . . . . . . . . . . . . . . 15 + 4.5. Increment, Decrement . . . . . . . . . . . . . . . . . . . 16 + 4.5.1. Example . . . . . . . . . . . . . . . . . . . . . . . 17 + 4.6. quit . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 4.6.1. Example . . . . . . . . . . . . . . . . . . . . . . . 20 + 4.7. Flush . . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 4.7.1. Example . . . . . . . . . . . . . . . . . . . . . . . 21 + 4.8. noop . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 4.8.1. Example . . . . . . . . . . . . . . . . . . . . . . . 23 + 4.9. version . . . . . . . . . . . . . . . . . . . . . . . . . 23 + 4.9.1. Example . . . . . . . . . . . . . . . . . . . . . . . 24 + 4.10. Append, Prepend . . . . . . . . . . . . . . . . . . . . . 25 + 4.10.1. Example . . . . . . . . . . . . . . . . . . . . . . . 26 + 4.11. Stat . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 4.11.1. Example . . . . . . . . . . . . . . . . . . . . . . . 27 + 5. Security Considerations . . . . . . . . . . . . . . . . . . . 29 + 6. Normative References . . . . . . . . . . . . . . . . . . . . . 30 + Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 30 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 2] + +Internet-Draft Memcache Binary Protocol August 2008 + + +1. Introduction + + Memcache is a high performance key-value cache. It is intentionally + a dumb cache, optimized for speed only. Applications using memcache + do not rely on it for data -- a persistent database with guaranteed + reliability is strongly recommended -- but applications can run much + faster when cached data is available in memcache. + + Memcache was originally written to make LiveJournal [LJ] go faster. + It now powers all of the fastest web sites that you love. + +1.1. Conventions Used In This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + + +2. Packet Structure + + General format of a packet: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0/ HEADER / + / / + / / + / / + +---------------+---------------+---------------+---------------+ + 24/ COMMAND-SPECIFIC EXTRAS (as needed) / + +/ (note length in th extras length header field) / + +---------------+---------------+---------------+---------------+ + m/ Key (as needed) / + +/ (note length in key length header field) / + +---------------+---------------+---------------+---------------+ + n/ Value (as needed) / + +/ (note length is total body length header field, minus / + +/ sum of the extras and key length body fields) / + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 3] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Request header: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| Magic | Opcode | Key length | + +---------------+---------------+---------------+---------------+ + 4| Extras length | Data type | Reserved | + +---------------+---------------+---------------+---------------+ + 8| Total body length | + +---------------+---------------+---------------+---------------+ + 12| Opaque | + +---------------+---------------+---------------+---------------+ + 16| CAS | + | | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Response header: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| Magic | Opcode | Key Length | + +---------------+---------------+---------------+---------------+ + 4| Extras length | Data type | Status | + +---------------+---------------+---------------+---------------+ + 8| Total body length | + +---------------+---------------+---------------+---------------+ + 12| Opaque | + +---------------+---------------+---------------+---------------+ + 16| CAS | + | | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Header fields: + Magic Magic number. + Opcode Command code. + Key length Length in bytes of the text key that follows the + command extras. + Status Status of the response (non-zero on error). + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 4] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Extras length Length in bytes of the command extras. + Data type Reserved for future use (Sean is using this + soon). + Reserved Really reserved for future use (up for grabs). + Total body length Length in bytes of extra + key + value. + Opaque Will be copied back to you in the response. + CAS Data version check + + +3. Defined Values + +3.1. Magic Byte + + 0x80 Request packet for this protocol version + 0x81 Response packet for this protocol version + + Magic byte / version. For each version of the protocol, we'll use a + different request/response value pair. This is useful for protocol + analyzers to know what a packet is in isolation from which direction + it is moving. Note that it is common to run a memcached instance on + a host that also runs an application server. Such a host will both + send and receive memcache packets. + + The version should hopefully correspond only to different meanings of + the command byte. In an ideal world, we will not change the header + format. As reserved bytes are given defined meaning, the protocol + version / magic byte values should be incremented. + + Traffic analysis tools are encouraged to identify memcache packets + and provide detailed interpretation if the magic bytes are recognized + and otherwise to provide a generic breakdown of the packet. Note + that the key and value positions can always be identified even if the + magic byte or command opcode are not recognized. + +3.2. Response Status + + Possible values of this two-byte field: + 0x0000 No error + 0x0001 Key not found + 0x0002 Key exists + 0x0003 Value too big + 0x0004 Invalid arguments + 0x0005 Item not stored + 0x0081 Unknown command + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 5] + +Internet-Draft Memcache Binary Protocol August 2008 + + + 0x0082 Out of memory + +3.3. Command Opcodes + + Possible values of the one-byte field: + 0x00 Get + 0x01 Set + 0x02 Add + 0x03 Replace + 0x04 Delete + 0x05 Increment + 0x06 Decrement + 0x07 Quit + 0x08 Flush + 0x09 GetQ + 0x0A No-op + 0x0B Version + 0x0C GetK + 0x0D GetKQ + 0x0E Append + 0x0F Prepend + 0x10 Stat + +3.4. Data Types + + Possible values of the one-byte field: + 0x00 Raw bytes + + +4. Commands + +4.1. Introduction + + All communication is initiated by a request from the client, and the + server will respond to each request with zero or multiple packets + from each request. If the server respond with a message with a non- + nil status code, the body of the packet contains a textual error + message. If the status code is nil, the command opcode will define + the layout of the body of the message. + +4.1.1. Example + + The following figure illustrates the packet layout for a packet with + an error message. + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 6] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Packet layout: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x09 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x4e ('N') | 0x6f ('o') | 0x74 ('t') | 0x20 (' ') | + +---------------+---------------+---------------+---------------+ + 28| 0x66 ('f') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | + +---------------+---------------+---------------+---------------+ + 32| 0x64 ('d') | + +---------------+ + Total 33 bytes (24 byte header, and 9 bytes value) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x00 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0001 + Total body (8-11) : 0x00000009 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value (24-32): The textual string "Not found" + +4.2. Get, Get Quietly, Get Key, Get Key Quietly + + Request: + + MUST NOT have extras. + + + + + +Stone & Norbye Expires March 1, 2009 [Page 7] + +Internet-Draft Memcache Binary Protocol August 2008 + + + MUST have key. + MUST NOT have value. + + o 4 byte flags + + Response (if found): + + MUST have extras. + MAY have key. + MAY have value. + + o 4 byte flags + + Extra data for the get commands: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| Flags | + +---------------+---------------+---------------+---------------+ + + Total 4 bytes + + The get command gets a single key. The getq command is both mum on + cache miss and quiet, holding its response until a non-quiet command + is issued. Getk and getkq differs from get and getq by adding the + key into the response packet. + + You're not guaranteed a response to a getq/getkq cache hit until you + send a non-getq/getkq command later, which uncorks the server which + bundles up IOs to send to the client in one go. + + Clients should implement multi-get (still important for reducing + network roundtrips!) as n pipelined requests, the first n-1 being + getq/getkq, the last being a regular get/getk. that way you're + guaranteed to get a response, and you know when the server's done. + you can also do the naive thing and send n pipelined get/getks, but + then you could potentially get back a lot of "NOT_FOUND" error code + packets. alternatively, you can send 'n' getq/getkqs, followed by a + 'noop' command. + +4.2.1. Example + + To request the data associated with the key "Hello" the following + fields must be specified in the packet. + + + + + +Stone & Norbye Expires March 1, 2009 [Page 8] + +Internet-Draft Memcache Binary Protocol August 2008 + + + get request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | + +---------------+ + + Total 29 bytes (24 byte header, and 5 bytes key) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x00 + Key length (2,3) : 0x0005 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000005 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key (24-29): The textual string: "Hello" + Value : None + + If the item exist on the server the following packet is returned, + otherwise a packet with status code != 0 will be returned (see + Introduction (Section 4.1)) + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 9] + +Internet-Draft Memcache Binary Protocol August 2008 + + + get/getq response: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x09 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 32| 0x64 ('d') | + +---------------+ + + Total 33 bytes (24 byte header, 4 byte extras and 5 byte value) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x00 + Key length (2,3) : 0x0000 + Extra length (4) : 0x04 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000009 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000001 + Extras : + Flags (24-27): 0xdeadbeef + Key : None + Value (28-32): The textual string "World" + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 10] + +Internet-Draft Memcache Binary Protocol August 2008 + + + getk/getkq response: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x0E | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 32| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | + +---------------+---------------+---------------+---------------+ + 36| 0x6c ('l') | 0x64 ('d') | + +---------------+---------------+ + + Total 38 bytes (24 byte header, 4 byte extras, 5 byte key + and 5 byte value) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x00 + Key length (2,3) : 0x0005 + Extra length (4) : 0x04 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x0000000E + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000001 + Extras : + Flags (24-27): 0xdeadbeef + Key (28-32): The textual string: "Hello" + Value (33-37): The textual string "World" + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 11] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.3. Set, Add, Replace + + MUST have extras. + MUST have key. + MUST have value. + + o 4 byte flags + o 4 byte expiration time + + Extra data for set/add/replace: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| Flags | + +---------------+---------------+---------------+---------------+ + 4| Expiration | + +---------------+---------------+---------------+---------------+ + Total 8 bytes + + If the Data Version Check (CAS) is nonzero, the requested operation + MUST only succeed if the item exists and has a CAS value identical to + the provided value. + + Add MUST fail if the item already exist. + + Replace MUST fail if the item doesn't exist. + + Set should store the data unconditionally if the item exists or not.. + +4.3.1. Example + + The following figure shows an add-command for + Key: "Hello" + Value: "World" + Flags: 0xdeadbeef + Expiry: in two hours + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 12] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Add request: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x02 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x08 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x12 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0xde | 0xad | 0xbe | 0xef | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x0e | 0x10 | + +---------------+---------------+---------------+---------------+ + 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | + +---------------+---------------+---------------+---------------+ + 40| 0x6c ('l') | 0x64 ('d') | + +---------------+---------------+ + + Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and + 5 byte value) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x02 + Key length (2,3) : 0x0005 + Extra length (4) : 0x08 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000012 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : + Flags (24-27): 0xdeadbeef + Expiry (28-31): 0x00000e10 + Key (32-36): The textual string "Hello" + Value (37-41): The textual string "World" + + + +Stone & Norbye Expires March 1, 2009 [Page 13] + +Internet-Draft Memcache Binary Protocol August 2008 + + + The response-packet contains no extra data, and the result of + operation is signaled through the status code. If the command + succeed, the CAS value for the item is returned in the CAS-field of + the packet. + + Successful add response: + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x02 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x02 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000001 + Extras : None + Key : None + Value : None + +4.4. Delete + + MUST NOT have extras + MUST have key. + MUST NOT have value. + + Delete the item with the specific key. + + + +Stone & Norbye Expires March 1, 2009 [Page 14] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.4.1. Example + + The following figure shows a delete message for the item "Hello" + + Delete request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x04 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | + +---------------+ + + Total 29 bytes (24 byte header, 5 byte value) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x04 + Key length (2,3) : 0x0005 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000005 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : The textual string "Hello" + Value : None + + The response-packet contains no extra data, and the result of + operation is signaled through the status code. + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 15] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.5. Increment, Decrement + + MUST have extras. + MUST have key. + MUST NOT have value. + + o 8 byte value to add / subtract + o 8 byte initial value (unsigned) + o 4 byte expiration time + + Extra data for incr/decr: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| Amount to add | + | | + +---------------+---------------+---------------+---------------+ + 8| Initial value | + | | + +---------------+---------------+---------------+---------------+ + 16| Expiration | + +---------------+---------------+---------------+---------------+ + Total 20 bytes + + These commands will either add or remove the specified amount to the + requested counter. + + If the counter does not exist, one of two things may happen: + + 1. If the expiration value is all one-bits (0xffffffff), the + operation will fail with NOT_FOUND. + 2. For all other expiration values, the operation will succeed by + seeding the value for this key with the provided initial value to + expire with the provided expiration time. The flags will be set + to zero. + + incr/decr response body: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 64-bit unsigned response. | + | | + +---------------+---------------+---------------+---------------+ + Total 8 bytes + + + +Stone & Norbye Expires March 1, 2009 [Page 16] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.5.1. Example + + The following figure shows an incr-command for + Key: "counter" + Delta: 0x01 + Initial: 0x00 + Expiry: in two hours + + Increment request: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 17] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x05 | 0x00 | 0x07 | + +---------------+---------------+---------------+---------------+ + 4| 0x14 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x1b | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x00 | 0x01 | + +---------------+---------------+---------------+---------------+ + 32| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 36| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 40| 0x00 | 0x00 | 0x0e | 0x10 | + +---------------+---------------+---------------+---------------+ + 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | + +---------------+---------------+---------------+---------------+ + 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') | + +---------------+---------------+---------------+ + Total 51 bytes (24 byte header, 20 byte extras, 7 byte key) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x05 + Key length (2,3) : 0x0007 + Extra length (4) : 0x14 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x0000001b + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : + delta (24-31): 0x0000000000000001 + initial (32-39): 0x0000000000000000 + exipration (40-43): 0x00000e10 + Key : Textual string "counter" + Value : None + + + +Stone & Norbye Expires March 1, 2009 [Page 18] + +Internet-Draft Memcache Binary Protocol August 2008 + + + If the key doesn't exist, the server will respond with the initial + value. If not the incremented value will be returned. Let's assume + that the key didn't exist, so the initial value is returned. + + Increment response: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x05 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x08 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 28| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 32 bytes (24 byte header, 8 byte value) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x05 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000008 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000005 + Extras : None + Key : None + Value : 0x0000000000000000 + +4.6. quit + + MUST NOT have extras. + MUST NOT have key. + + + + + +Stone & Norbye Expires March 1, 2009 [Page 19] + +Internet-Draft Memcache Binary Protocol August 2008 + + + MUST NOT have value. + + Close the connection to the server. + +4.6.1. Example + + Quit request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x07 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x07 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value : None + + The response-packet contains no extra data, and the result of + operation is signaled through the status code. The server will then + close the connection. + +4.7. Flush + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 20] + +Internet-Draft Memcache Binary Protocol August 2008 + + + MAY have extras + MUST NOT have key. + MUST NOT have value. + + o 4 byte expiration time + + Extra data for flush: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| Expiration | + +---------------+---------------+---------------+---------------+ + Total 4 bytes + + Flush the items in the cache now or sometime in the future specified + by the expiration field. See the documentation of the textual + protocol for the full description on how to specify the expiration + time. + +4.7.1. Example + + To flush the cache (delete all items) in two hours, the set the + following values in the request + + + + + + + + + + + + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 21] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Flush request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x08 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x04 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x04 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x00 | 0x00 | 0x0e | 0x10 | + +---------------+---------------+---------------+---------------+ + Total 28 bytes (24 byte header, 4 byte body) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x08 + Key length (2,3) : 0x0000 + Extra length (4) : 0x04 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000004 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : + Expiry (24-27): 0x000e10 + Key : None + Value : None + + The response-packet contains no extra data, and the result of + operation is signaled through the status code. + +4.8. noop + + MUST NOT have extras. + MUST NOT have key. + MUST NOT have value. + + Used as a keep alive. Flushes outstanding getq/getkq's. + + + + +Stone & Norbye Expires March 1, 2009 [Page 22] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.8.1. Example + + Noop request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0a | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x0a + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value : None + + The response-packet contains no extra data, and the result of + operation is signaled through the status code. + +4.9. version + + MUST NOT have extras. + MUST NOT have key. + MUST NOT have value. + + Request the server version. + + The server respond with a packet containing the version string in the + + + +Stone & Norbye Expires March 1, 2009 [Page 23] + +Internet-Draft Memcache Binary Protocol August 2008 + + + body with the following format: "x.y.z" + +4.9.1. Example + + Version request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0b | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x0b + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 24] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Version response: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x0b | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x31 ('1') | 0x2e ('.') | 0x33 ('3') | 0x2e ('.') | + +---------------+---------------+---------------+---------------+ + 28| 0x31 ('1') | + +---------------+ + Total 29 bytes (24 byte header, 5 byte body) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x0b + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000005 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value : Textual string "1.3.1" + +4.10. Append, Prepend + + MUST NOT have extras. + MUST have key. + MUST have value. + + These commands will either append or prepend the specified value to + the requested key. + + + + + +Stone & Norbye Expires March 1, 2009 [Page 25] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.10.1. Example + + The following example appends '!' to the 'Hello' key. + + Append request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x0e | 0x00 | 0x05 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x06 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | + +---------------+---------------+---------------+---------------+ + 28| 0x6f ('o') | 0x21 ('!') | + +---------------+---------------+ + Total 30 bytes (24 byte header, 5 byte key, 1 byte value) + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x0e + Key length (2,3) : 0x0005 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000006 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key (24-28): The textual string "Hello" + Value (29) : "!" + + The response-packet contains no extra data, and the result of + operation is signaled through the status code. + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 26] + +Internet-Draft Memcache Binary Protocol August 2008 + + +4.11. Stat + + MUST NOT have extras. + MAY have key. + MUST NOT have value. + + Request server statistics. Without a key specified the server will + respond with a "default" set of statistics information. Each piece + of statistical information is returned in it's own packet (key + contains the name of the statistical item and the body contains the + value in ASCII format). The sequence of return packet is terminated + with a packet with no key and no value. + +4.11.1. Example + + The following example requests all statistics from the server + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 27] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Stat request: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x80 | 0x10 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + Total 24 bytes + + Field (offset) (value) + Magic (0) : 0x80 + Opcode (1) : 0x10 + Key length (2,3) : 0x0000 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Reserved (6,7) : 0x0000 + Total body (8-11) : 0x00000000 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Extras : None + Key : None + Value : None + + The server will send send each value in a separate packet with an + "empty" packet (no key / no value) to terminate the sequence. Each + of the response packets look like the following example: + + + + + + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 28] + +Internet-Draft Memcache Binary Protocol August 2008 + + + Stat response: + + Byte/ 0 | 1 | 2 | 3 | + / | | | | + |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| + +---------------+---------------+---------------+---------------+ + 0| 0x81 | 0x10 | 0x00 | 0x03 | + +---------------+---------------+---------------+---------------+ + 4| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 8| 0x00 | 0x00 | 0x00 | 0x07 | + +---------------+---------------+---------------+---------------+ + 12| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 16| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 20| 0x00 | 0x00 | 0x00 | 0x00 | + +---------------+---------------+---------------+---------------+ + 24| 0x70 ('p') | 0x69 ('i') | 0x64 ('d') | 0x33 ('3') | + +---------------+---------------+---------------+---------------+ + 28| 0x30 ('0') | 0x37 ('7') | 0x38 ('8') | + +---------------+---------------+---------------+ + Total 31 bytes (24 byte header, 3 byte key, 4 byte body) + + Field (offset) (value) + Magic (0) : 0x81 + Opcode (1) : 0x10 + Key length (2,3) : 0x0003 + Extra length (4) : 0x00 + Data type (5) : 0x00 + Status (6,7) : 0x0000 + Total body (8-11) : 0x00000007 + Opaque (12-15): 0x00000000 + CAS (16-23): 0x0000000000000000 + Exstras : None + Key : The textual string "pid" + Value : The textual string "3078" + + +5. Security Considerations + + Memcache has no authentication or security layers whatsoever. It is + RECOMMENDED that memcache be deployed strictly on closed, protected, + back-end networks within a single data center, within a single + cluster of servers, or even on a single host, providing shared + caching for multiple applications. Memcache MUST NOT be made + available on a public network. + + + + +Stone & Norbye Expires March 1, 2009 [Page 29] + +Internet-Draft Memcache Binary Protocol August 2008 + + +6. Normative References + + [KEYWORDS] + Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [LJ] Danga Interactive, "LJ NEEDS MOAR SPEED", 10 1999. + + +Appendix A. Acknowledgments + + Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin + Sallings, for their work on the memcached server. + + Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan + Martin, Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, + Jamie McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, + Robin H. Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean- + Francois Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris + Goffinet, Tomash Brechko, and others for their work reporting bugs + and maintaining memcached client libraries and bindings in many + languages. + + +Authors' Addresses + + Aaron Stone (editor) + Six Apart, Ltd. + 548 4th Street + San Francisco, CA 94107 + USA + + Email: aaron@serendipity.palo-alto.ca.us + + + Trond Norbye (editor) + Sun Microsystems, INC + Haakon VII g. 7B + Trondheim NO-7485 Trondheim + Norway + + Email: trond.norbye@sun.com + + + + + + + + + +Stone & Norbye Expires March 1, 2009 [Page 30] \ No newline at end of file diff --git a/doc/images/DataSize_throughput_128_mix_string.jpg b/doc/images/DataSize_throughput_128_mix_string.jpg new file mode 100644 index 0000000..b1a7715 Binary files /dev/null and b/doc/images/DataSize_throughput_128_mix_string.jpg differ diff --git a/doc/images/DataSize_throughput_1_mix_string.jpg b/doc/images/DataSize_throughput_1_mix_string.jpg new file mode 100644 index 0000000..cd9d248 Binary files /dev/null and b/doc/images/DataSize_throughput_1_mix_string.jpg differ diff --git a/doc/images/DataSize_throughput_64_mix_string.jpg b/doc/images/DataSize_throughput_64_mix_string.jpg new file mode 100644 index 0000000..3e6c70f Binary files /dev/null and b/doc/images/DataSize_throughput_64_mix_string.jpg differ diff --git a/doc/images/DataSize_throughput_8_mix_string.jpg b/doc/images/DataSize_throughput_8_mix_string.jpg new file mode 100644 index 0000000..15eafc6 Binary files /dev/null and b/doc/images/DataSize_throughput_8_mix_string.jpg differ diff --git a/doc/images/ThreadNum_throughput_102400_mix_string.jpg b/doc/images/ThreadNum_throughput_102400_mix_string.jpg new file mode 100644 index 0000000..945337e Binary files /dev/null and b/doc/images/ThreadNum_throughput_102400_mix_string.jpg differ diff --git a/doc/images/ThreadNum_throughput_10240_mix_string.jpg b/doc/images/ThreadNum_throughput_10240_mix_string.jpg new file mode 100644 index 0000000..cd279fc Binary files /dev/null and b/doc/images/ThreadNum_throughput_10240_mix_string.jpg differ diff --git a/doc/images/ThreadNum_throughput_1024_mix_string.jpg b/doc/images/ThreadNum_throughput_1024_mix_string.jpg new file mode 100644 index 0000000..8885e69 Binary files /dev/null and b/doc/images/ThreadNum_throughput_1024_mix_string.jpg differ diff --git a/doc/images/ThreadNum_throughput_128_mix_string.jpg b/doc/images/ThreadNum_throughput_128_mix_string.jpg new file mode 100644 index 0000000..fb0edb8 Binary files /dev/null and b/doc/images/ThreadNum_throughput_128_mix_string.jpg differ diff --git a/doc/images/ThreadNum_throughput_512_mix_string.jpg b/doc/images/ThreadNum_throughput_512_mix_string.jpg new file mode 100644 index 0000000..52a7f5c Binary files /dev/null and b/doc/images/ThreadNum_throughput_512_mix_string.jpg differ diff --git a/doc/images/ThreadNum_throughput_64_mix_string.jpg b/doc/images/ThreadNum_throughput_64_mix_string.jpg new file mode 100644 index 0000000..9773abb Binary files /dev/null and b/doc/images/ThreadNum_throughput_64_mix_string.jpg differ diff --git a/doc/protocol.txt b/doc/protocol.txt new file mode 100644 index 0000000..c7920df --- /dev/null +++ b/doc/protocol.txt @@ -0,0 +1,599 @@ +Protocol +-------- + +Clients of memcached communicate with server through TCP connections. +(A UDP interface is also available; details are below under "UDP +protocol.") A given running memcached server listens on some +(configurable) port; clients connect to that port, send commands to +the server, read responses, and eventually close the connection. + +There is no need to send any command to end the session. A client may +just close the connection at any moment it no longer needs it. Note, +however, that clients are encouraged to cache their connections rather +than reopen them every time they need to store or retrieve data. This +is because memcached is especially designed to work very efficiently +with a very large number (many hundreds, more than a thousand if +necessary) of open connections. Caching connections will eliminate the +overhead associated with establishing a TCP connection (the overhead +of preparing for a new connection on the server side is insignificant +compared to this). + +There are two kinds of data sent in the memcache protocol: text lines +and unstructured data. Text lines are used for commands from clients +and responses from servers. Unstructured data is sent when a client +wants to store or retrieve data. The server will transmit back +unstructured data in exactly the same way it received it, as a byte +stream. The server doesn't care about byte order issues in +unstructured data and isn't aware of them. There are no limitations on +characters that may appear in unstructured data; however, the reader +of such data (either a client or a server) will always know, from a +preceding text line, the exact length of the data block being +transmitted. + +Text lines are always terminated by \r\n. Unstructured data is _also_ +terminated by \r\n, even though \r, \n or any other 8-bit characters +may also appear inside the data. Therefore, when a client retrieves +data from a server, it must use the length of the data block (which it +will be provided with) to determine where the data block ends, and not +the fact that \r\n follows the end of the data block, even though it +does. + +Keys +---- + +Data stored by memcached is identified with the help of a key. A key +is a text string which should uniquely identify the data for clients +that are interested in storing and retrieving it. Currently the +length limit of a key is set at 250 characters (of course, normally +clients wouldn't need to use such long keys); the key must not include +control characters or whitespace. + +Commands +-------- + +There are three types of commands. + +Storage commands (there are six: "set", "add", "replace", "append" +"prepend" and "cas") ask the server to store some data identified by a key. The +client sends a command line, and then a data block; after that the +client expects one line of response, which will indicate success or +faulure. + +Retrieval commands (there are two: "get" and "gets") ask the server to +retrieve data corresponding to a set of keys (one or more keys in one +request). The client sends a command line, which includes all the +requested keys; after that for each item the server finds it sends to +the client one response line with information about the item, and one +data block with the item's data; this continues until the server +finished with the "END" response line. + +All other commands don't involve unstructured data. In all of them, +the client sends one command line, and expects (depending on the +command) either one line of response, or several lines of response +ending with "END" on the last line. + +A command line always starts with the name of the command, followed by +parameters (if any) delimited by whitespace. Command names are +lower-case and are case-sensitive. + +Expiration times +---------------- + +Some commands involve a client sending some kind of expiration time +(relative to an item or to an operation requested by the client) to +the server. In all such cases, the actual value sent may either be +Unix time (number of seconds since January 1, 1970, as a 32-bit +value), or a number of seconds starting from current time. In the +latter case, this number of seconds may not exceed 60*60*24*30 (number +of seconds in 30 days); if the number sent by a client is larger than +that, the server will consider it to be real Unix time value rather +than an offset from current time. + + +Error strings +------------- + +Each command sent by a client may be answered with an error string +from the server. These error strings come in three types: + +- "ERROR\r\n" + + means the client sent a nonexistent command name. + +- "CLIENT_ERROR \r\n" + + means some sort of client error in the input line, i.e. the input + doesn't conform to the protocol in some way. is a + human-readable error string. + +- "SERVER_ERROR \r\n" + + means some sort of server error prevents the server from carrying + out the command. is a human-readable error string. In cases + of severe server errors, which make it impossible to continue + serving the client (this shouldn't normally happen), the server will + close the connection after sending the error line. This is the only + case in which the server closes a connection to a client. + + +In the descriptions of individual commands below, these error lines +are not again specifically mentioned, but clients must allow for their +possibility. + + +Storage commands +---------------- + +First, the client sends a command line which looks like this: + + [noreply]\r\n +cas [noreply]\r\n + +- is "set", "add", "replace", "append" or "prepend" + + "set" means "store this data". + + "add" means "store this data, but only if the server *doesn't* already + hold data for this key". + + "replace" means "store this data, but only if the server *does* + already hold data for this key". + + "append" means "add this data to an existing key after existing data". + + "prepend" means "add this data to an existing key before existing data". + + The append and prepend commands do not accept flags or exptime. + They update existing data portions, and ignore new flag and exptime + settings. + + "cas" is a check and set operation which means "store this data but + only if no one else has updated since I last fetched it." + +- is the key under which the client asks to store the data + +- is an arbitrary 16-bit unsigned integer (written out in + decimal) that the server stores along with the data and sends back + when the item is retrieved. Clients may use this as a bit field to + store data-specific information; this field is opaque to the server. + Note that in memcached 1.2.1 and higher, flags may be 32-bits, instead + of 16, but you might want to restrict yourself to 16 bits for + compatibility with older versions. + +- is expiration time. If it's 0, the item never expires + (although it may be deleted from the cache to make place for other + items). If it's non-zero (either Unix time or offset in seconds from + current time), it is guaranteed that clients will not be able to + retrieve this item after the expiration time arrives (measured by + server time). + +- is the number of bytes in the data block to follow, *not* + including the delimiting \r\n. may be zero (in which case + it's followed by an empty data block). + +- is a unique 64-bit value of an existing entry. + Clients should use the value returned from the "gets" command + when issuing "cas" updates. + +- "noreply" optional parameter instructs the server to not send the + reply. NOTE: if the request line is malformed, the server can't + parse "noreply" option reliably. In this case it may send the error + to the client, and not reading it on the client side will break + things. Client should construct only valid requests. + +After this line, the client sends the data block: + +\r\n + +- is a chunk of arbitrary 8-bit data of length + from the previous line. + +After sending the command line and the data blockm the client awaits +the reply, which may be: + +- "STORED\r\n", to indicate success. + +- "NOT_STORED\r\n" to indicate the data was not stored, but not +because of an error. This normally means that either that the +condition for an "add" or a "replace" command wasn't met, or that the +item is in a delete queue (see the "delete" command below). + +- "EXISTS\r\n" to indicate that the item you are trying to store with +a "cas" command has been modified since you last fetched it. + +- "NOT_FOUND\r\n" to indicate that the item you are trying to store +with a "cas" command did not exist or has been deleted. + + +Retrieval command: +------------------ + +The retrieval commands "get" and "gets" operates like this: + +get *\r\n +gets *\r\n + +- * means one or more key strings separated by whitespace. + +After this command, the client expects zero or more items, each of +which is received as a text line followed by a data block. After all +the items have been transmitted, the server sends the string + +"END\r\n" + +to indicate the end of response. + +Each item sent by the server looks like this: + +VALUE []\r\n +\r\n + +- is the key for the item being sent + +- is the flags value set by the storage command + +- is the length of the data block to follow, *not* including + its delimiting \r\n + +- is a unique 64-bit integer that uniquely identifies + this specific item. + +- is the data for this item. + +If some of the keys appearing in a retrieval request are not sent back +by the server in the item list this means that the server does not +hold items with such keys (because they were never stored, or stored +but deleted to make space for more items, or expired, or explicitly +deleted by a client). + + +Deletion +-------- + +The command "delete" allows for explicit deletion of items: + +delete [