git.m6w6.name Git - m6w6/libmemcached/blob - libmemcached.html

   1
   2
   3 <!DOCTYPE html>
   4 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
   5 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
   6 <head>
   7   <meta charset="utf-8">
   8
   9   <meta name="viewport" content="width=device-width, initial-scale=1.0">
  10
  11   <title>C/C++ Client Library for memcached &mdash; libmemcached 1.0.99 documentation</title>
  12
  13
  14
  15
  16
  17
  18
  19
  20   <script type="text/javascript" src="_static/js/modernizr.min.js"></script>
  21
  22
  23       <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
  24         <script src="_static/jquery.js"></script>
  25         <script src="_static/underscore.js"></script>
  26         <script src="_static/doctools.js"></script>
  27         <script src="_static/language_data.js"></script>
  28
  29     <script type="text/javascript" src="_static/js/theme.js"></script>
  30
  31
  32
  33
  34   <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  35   <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  36     <link rel="index" title="Index" href="genindex.html" />
  37     <link rel="search" title="Search" href="search.html" />
  38     <link rel="copyright" title="Copyright" href="copyright.html" />
  39     <link rel="next" title="libmemcached API" href="libmemcached/index.html" />
  40     <link rel="prev" title="libmemcached Manual" href="index.html" />
  41 </head>
  42
  43 <body class="wy-body-for-nav">
  44
  45
  46   <div class="wy-grid-for-nav">
  47
  48     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
  49       <div class="wy-side-scroll">
  50         <div class="wy-side-nav-search" >
  51
  52
  53
  54             <a href="index.html" class="icon icon-home"> libmemcached
  55
  56
  57
  58           </a>
  59
  60
  61
  62
  63               <div class="version">
  64                 1.0
  65               </div>
  66
  67
  68
  69
  70 <div role="search">
  71   <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
  72     <input type="text" name="q" placeholder="Search docs" />
  73     <input type="hidden" name="check_keywords" value="yes" />
  74     <input type="hidden" name="area" value="default" />
  75   </form>
  76 </div>
  77
  78
  79         </div>
  80
  81         <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
  82
  83
  84
  85
  86
  87
  88               <p class="caption"><span class="caption-text">libmemcached</span></p>
  89 <ul class="current">
  90 <li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction</a></li>
  91 <li class="toctree-l1"><a class="reference internal" href="libmemcached/index.html">libmemcached API</a><ul>
  92 <li class="toctree-l2"><a class="reference internal" href="libmemcached/index_basics.html">Basics</a></li>
  93 <li class="toctree-l2"><a class="reference internal" href="libmemcached/index_data.html">Working with Data</a></li>
  94 <li class="toctree-l2"><a class="reference internal" href="libmemcached/index_errors.html">Messages and Errors</a></li>
  95 <li class="toctree-l2"><a class="reference internal" href="libmemcached/index_advanced.html">Advanced Topics</a></li>
  96 <li class="toctree-l2"><a class="reference internal" href="libmemcached/index_deprecated.html">Deprecated Functionality</a></li>
  97 </ul>
  98 </li>
  99 <li class="toctree-l1"><a class="reference internal" href="libmemcached/index_misc.html">Misc</a><ul>
 100 <li class="toctree-l2"><a class="reference internal" href="libmemcached/configuration.html">Configuration</a></li>
 101 <li class="toctree-l2"><a class="reference internal" href="libmemcached/constants.html">Constants</a></li>
 102 <li class="toctree-l2"><a class="reference internal" href="libmemcached/examples.html">Examples</a></li>
 103 <li class="toctree-l2"><a class="reference internal" href="libmemcached/versioning.html">Versioning</a></li>
 104 </ul>
 105 </li>
 106 </ul>
 107 <p class="caption"><span class="caption-text">libmemcachedutil</span></p>
 108 <ul>
 109 <li class="toctree-l1"><a class="reference internal" href="libmemcachedutil.html">Introduction</a></li>
 110 <li class="toctree-l1"><a class="reference internal" href="libmemcachedutil/index.html">libmemcachedutil API</a><ul>
 111 <li class="toctree-l2"><a class="reference internal" href="libmemcachedutil/memcached_pool.html">Working with memcached pools</a></li>
 112 </ul>
 113 </li>
 114 </ul>
 115 <p class="caption"><span class="caption-text">libhashkit</span></p>
 116 <ul>
 117 <li class="toctree-l1"><a class="reference internal" href="libhashkit.html">Introduction</a></li>
 118 <li class="toctree-l1"><a class="reference internal" href="libhashkit/index.html">libhashkit API</a><ul>
 119 <li class="toctree-l2"><a class="reference internal" href="libhashkit/hashkit_create.html">Creating a hashkit structure</a></li>
 120 <li class="toctree-l2"><a class="reference internal" href="libhashkit/hashkit_function.html">Set Hash Function</a></li>
 121 <li class="toctree-l2"><a class="reference internal" href="libhashkit/hashkit_functions.html">Available Hashes</a></li>
 122 <li class="toctree-l2"><a class="reference internal" href="libhashkit/hashkit_value.html">Generate hash value</a></li>
 123 </ul>
 124 </li>
 125 </ul>
 126 <p class="caption"><span class="caption-text">Client Applications</span></p>
 127 <ul>
 128 <li class="toctree-l1"><a class="reference internal" href="bin/index.html">Client Applications</a><ul>
 129 <li class="toctree-l2"><a class="reference internal" href="bin/memcapable.html">memcapable - Checking a Memcached server capabilities and compatibility</a></li>
 130 <li class="toctree-l2"><a class="reference internal" href="bin/memcat.html">memcat - “cat” data from a server</a></li>
 131 <li class="toctree-l2"><a class="reference internal" href="bin/memcp.html">memcp - Copy data to a server</a></li>
 132 <li class="toctree-l2"><a class="reference internal" href="bin/memdump.html">memdump - Dumping your server</a></li>
 133 <li class="toctree-l2"><a class="reference internal" href="bin/memerror.html">memerror - translate an error code to a string</a></li>
 134 <li class="toctree-l2"><a class="reference internal" href="bin/memflush.html">memflush - flush all data from a server</a></li>
 135 <li class="toctree-l2"><a class="reference internal" href="bin/memrm.html">memrm - Remove data from a server</a></li>
 136 <li class="toctree-l2"><a class="reference internal" href="bin/memslap.html">memslap - Load testing  and benchmarking a server</a></li>
 137 <li class="toctree-l2"><a class="reference internal" href="bin/memaslap.html">memaslap - Load testing  and benchmarking a server</a></li>
 138 <li class="toctree-l2"><a class="reference internal" href="bin/memstat.html">memstat - Gather statistics from a server</a></li>
 139 <li class="toctree-l2"><a class="reference internal" href="bin/memexist.html">memexist - Check for the existence of a key</a></li>
 140 <li class="toctree-l2"><a class="reference internal" href="bin/memparse.html">memparse - Parse an option string</a></li>
 141 <li class="toctree-l2"><a class="reference internal" href="bin/memping.html">memping - Test to see if a server is available.</a></li>
 142 <li class="toctree-l2"><a class="reference internal" href="bin/memtouch.html">memtouch - Touches a key.</a></li>
 143 </ul>
 144 </li>
 145 </ul>
 146
 147
 148
 149         </div>
 150       </div>
 151     </nav>
 152
 153     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
 154
 155
 156       <nav class="wy-nav-top" aria-label="top navigation">
 157
 158           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
 159           <a href="index.html">libmemcached</a>
 160
 161       </nav>
 162
 163
 164       <div class="wy-nav-content">
 165
 166         <div class="rst-content">
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184 <div role="navigation" aria-label="breadcrumbs navigation">
 185
 186   <ul class="wy-breadcrumbs">
 187
 188       <li><a href="index.html">Docs</a> &raquo;</li>
 189
 190       <li>C/C++ Client Library for memcached</li>
 191
 192
 193       <li class="wy-breadcrumbs-aside">
 194
 195
 196
 197       </li>
 198
 199   </ul>
 200
 201
 202   <hr/>
 203 </div>
 204           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
 205            <div itemprop="articleBody">
 206
 207   <div class="section" id="c-c-client-library-for-memcached">
 208 <h1>C/C++ Client Library for memcached<a class="headerlink" href="#c-c-client-library-for-memcached" title="Permalink to this headline">¶</a></h1>
 209 <div class="section" id="synopsis">
 210 <h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
 211 <dl class="simple">
 212 <dt>#include &lt;libmemcached/memcached.h&gt;</dt><dd><p>Compile and link with -lmemcached</p>
 213 </dd>
 214 </dl>
 215 <hr class="docutils" />
 216 <p><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">libmemcached</span></code> is an open source C/C++ client library and tools for the
 217 memcached server (<a class="reference external" href="http://memcached.org/">http://memcached.org/</a>). It has been designed to be light on
 218 memory usage, thread safe, and provide full access to server side methods.</p>
 219 <p><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">libmemcached</span></code> was designed to provide the greatest number of options to use
 220 Memcached. Some of the features provided:</p>
 221 <ol class="arabic simple">
 222 <li><p>Asynchronous and Synchronous Transport Support.</p></li>
 223 <li><p>Consistent Hashing and Distribution.</p></li>
 224 <li><p>Tunable Hashing algorithm to match keys.</p></li>
 225 <li><p>Access to large object support.</p></li>
 226 <li><p>Local replication.</p></li>
 227 <li><p>A complete reference guide and documentation to the API.</p></li>
 228 <li><p>Tools to Manage your Memcached networks.</p></li>
 229 </ol>
 230 </div>
 231 <div class="section" id="description">
 232 <h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
 233 <p>“Memcached is a high-performance, distributed memory object caching
 234 system, generic in nature, but intended for use in speeding up dynamic web
 235 applications by alleviating database load.”
 236 <a class="reference external" href="http://memcached.org/">http://memcached.org/</a></p>
 237 <p><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">libmemcached</span></code> is a small, thread-safe client library for the
 238 memcached protocol. The code has all been written to allow
 239 for both web and embedded usage. It handles the work behind routing
 240 individual keys to specific servers specified by the developer (and values are
 241 matched based on server order as supplied by the user). It implements
 242 a modular and consistent method of object distribution.</p>
 243 <p>There are multiple implemented routing and hashing methods. See the
 244 <a class="reference internal" href="libmemcached/memcached_behavior.html#_CPPv422memcached_behavior_setP12memcached_st20memcached_behavior_t8uint64_t" title="memcached_behavior_set"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_behavior_set()</span></code></a> manpage for more information.</p>
 245 <p>All operations are performed against a <a class="reference internal" href="libmemcached/memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> structure.
 246 These structures can either be dynamically allocated or statically
 247 allocated and then initialized by <a class="reference internal" href="libmemcached/memcached_create.html#_CPPv416memcached_createP12memcached_st" title="memcached_create"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_create()</span></code></a>. Functions have
 248 been written in order to encapsulate the <a class="reference internal" href="libmemcached/memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a>. It is not
 249 recommended that you operate directly against the structure.</p>
 250 <p>Nearly all functions return a <a class="reference internal" href="libmemcached/memcached_return_t.html#_CPPv418memcached_return_t" title="memcached_return_t"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_return_t</span></code></a> value.
 251 This value can be translated to a printable string with
 252 <a class="reference internal" href="libmemcached/memcached_strerror.html#_CPPv418memcached_strerrorP12memcached_st18memcached_return_t" title="memcached_strerror"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_strerror</span></code></a>.</p>
 253 <p>Objects are stored on servers by hashing keys. The hash value maps the key to a
 254 particular server. All clients understand how this hashing works, so it is
 255 possibly to reliably both push data to a server and retrieve data from a server.</p>
 256 <p>Group keys can be optionally used to group sets of objects with servers.</p>
 257 <p>Namespaces are supported, and can be used to partition caches so that multiple
 258 applications can use the same memcached servers.</p>
 259 <p>Some features of the library must be enabled through <a class="reference internal" href="libmemcached/memcached_behavior.html#_CPPv422memcached_behavior_setP12memcached_st20memcached_behavior_t8uint64_t" title="memcached_behavior_set"><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">memcached_behavior_set()</span></code></a>.</p>
 260 </div>
 261 <div class="section" id="constants">
 262 <h2>CONSTANTS<a class="headerlink" href="#constants" title="Permalink to this headline">¶</a></h2>
 263 <p>A number of constants have been provided for in the library.</p>
 264 <p>See <a class="reference internal" href="libmemcached/constants.html"><span class="doc">libmemcached Constants and Defaults</span></a>.</p>
 265 </div>
 266 <div class="section" id="threads-and-processes">
 267 <h2>THREADS AND PROCESSES<a class="headerlink" href="#threads-and-processes" title="Permalink to this headline">¶</a></h2>
 268 <p>No global variables are used in this library.</p>
 269 <p><a class="reference internal" href="libmemcached/memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> structures are thread-safe, but when using threads or
 270 forked processes it is important to keep one instance of <a class="reference internal" href="libmemcached/memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a>
 271 per process or thread. Without creating your own locking structures you can not
 272 share a single <a class="reference internal" href="libmemcached/memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a>. However, you can call
 273 <a class="reference internal" href="libmemcached/memcached_quit.html#_CPPv414memcached_quitP12memcached_st" title="memcached_quit"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">memcached_quit()</span></code></a> on a <a class="reference internal" href="libmemcached/memcached_create.html#_CPPv412memcached_st" title="memcached_st"><code class="xref cpp cpp-type docutils literal notranslate"><span class="pre">memcached_st</span></code></a> and then use the resulting
 274 cloned structure.</p>
 275 </div>
 276 <div class="section" id="systemtap">
 277 <h2>SYSTEMTAP<a class="headerlink" href="#systemtap" title="Permalink to this headline">¶</a></h2>
 278 <p><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">libmemcached</span></code> can be built to support Systemtap on Linux when enabled at
 279 compile time.</p>
 280 <p>Please see <em class="manpage"><a class="manpage reference external" href="http://man7.org/linux/man-pages/man1/stap.1.html">stap(1)</a></em> and <em class="manpage"><a class="manpage reference external" href="http://man7.org/linux/man-pages/man1/dtrace.1.html">dtrace(1)</a></em> for more information
 281 about Systemtap.</p>
 282 </div>
 283 <div class="section" id="client-programs">
 284 <h2>CLIENT PROGRAMS<a class="headerlink" href="#client-programs" title="Permalink to this headline">¶</a></h2>
 285 <p><code class="xref cpp cpp-any docutils literal notranslate"><span class="pre">libmemcached</span></code> comes with a few useful client programs:</p>
 286 <ul class="simple">
 287 <li><p><a class="reference internal" href="bin/memaslap.html"><span class="doc">memaslap - Load testing  and benchmarking a server</span></a></p></li>
 288 <li><p><a class="reference internal" href="bin/memcapable.html"><span class="doc">memcapable - Checking a Memcached server capabilities and compatibility</span></a></p></li>
 289 <li><p><a class="reference internal" href="bin/memcat.html"><span class="doc">memcat - “cat” data from a server</span></a></p></li>
 290 <li><p><a class="reference internal" href="bin/memcp.html"><span class="doc">memcp - Copy data to a server</span></a></p></li>
 291 <li><p><a class="reference internal" href="bin/memdump.html"><span class="doc">memdump - Dumping your server</span></a></p></li>
 292 <li><p><a class="reference internal" href="bin/memerror.html"><span class="doc">memerror - translate an error code to a string</span></a></p></li>
 293 <li><p><a class="reference internal" href="bin/memexist.html"><span class="doc">memexist - Check for the existence of a key</span></a></p></li>
 294 <li><p><a class="reference internal" href="bin/memflush.html"><span class="doc">memflush - flush all data from a server</span></a></p></li>
 295 <li><p><a class="reference internal" href="bin/memparse.html"><span class="doc">memparse - Parse an option string</span></a></p></li>
 296 <li><p><a class="reference internal" href="bin/memping.html"><span class="doc">memping - Test to see if a server is available.</span></a></p></li>
 297 <li><p><a class="reference internal" href="bin/memrm.html"><span class="doc">memrm - Remove data from a server</span></a></p></li>
 298 <li><p><a class="reference internal" href="bin/memslap.html"><span class="doc">memslap - Load testing  and benchmarking a server</span></a></p></li>
 299 <li><p><a class="reference internal" href="bin/memstat.html"><span class="doc">memstat - Gather statistics from a server</span></a></p></li>
 300 <li><p><a class="reference internal" href="bin/memtouch.html"><span class="doc">memtouch - Touches a key.</span></a></p></li>
 301 </ul>
 302 </div>
 303 <div class="section" id="utility-libraries">
 304 <h2>UTILITY LIBRARIES<a class="headerlink" href="#utility-libraries" title="Permalink to this headline">¶</a></h2>
 305 <ul class="simple">
 306 <li><p><a class="reference internal" href="libhashkit.html"><span class="doc">libhashkit - C/C++ hashing library</span></a></p></li>
 307 <li><p><a class="reference internal" href="libmemcachedutil.html"><span class="doc">libmemcachedutil - C/C++ utilities extending libmemcached</span></a></p></li>
 308 </ul>
 309 </div>
 310 <div class="section" id="see-also">
 311 <h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
 312 <ul class="simple">
 313 <li><p><em class="manpage"><a class="manpage reference external" href="http://man7.org/linux/man-pages/man1/memcached.1.html">memcached(1)</a></em></p></li>
 314 <li><p><a class="reference internal" href="libmemcached/configuration.html"><span class="doc">libmemcached Configuration</span></a></p></li>
 315 <li><p><a class="reference internal" href="libmemcached/examples.html"><span class="doc">libmemcached Examples</span></a></p></li>
 316 </ul>
 317 </div>
 318 </div>
 319
 320
 321            </div>
 322
 323           </div>
 324           <footer>
 325
 326     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 327
 328         <a href="libmemcached/index.html" class="btn btn-neutral float-right" title="libmemcached API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
 329
 330
 331         <a href="index.html" class="btn btn-neutral float-left" title="libmemcached Manual" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
 332
 333     </div>
 334
 335
 336   <hr/>
 337
 338   <div role="contentinfo">
 339     <p>
 340         &copy; <a href="copyright.html">Copyright</a>
 341
 342     </p>
 343   </div>
 344   Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
 345
 346 </footer>
 347
 348         </div>
 349       </div>
 350
 351     </section>
 352
 353   </div>
 354
 355
 356
 357   <script type="text/javascript">
 358       jQuery(function () {
 359           SphinxRtdTheme.Navigation.enable(true);
 360       });
 361   </script>
 362
 363
 364
 365
 366
 367
 368 </body>
 369 </html>