docs: sanitize

[awesomized/libmemcached] / docs / source / libmemcached / examples.rst

diff --git a/docs/source/libmemcached/examples.rst b/docs/source/libmemcached/examples.rst
new file mode 100644 (file)
index 0000000..69aaf24
--- /dev/null
+++ b/docs/source/libmemcached/examples.rst
@@ -0,0 +1,117 @@
+libmemcached Examples
+=====================
+
+Examples for libmemcached
+
+DESCRIPTION
+-----------
+
+For full examples, test cases are found in tests/\*.c in the main
+distribution. These are always up to date, and are used for each test run of
+the library.
+
+Connecting to servers
+---------------------
+
+.. code-block:: c
+
+  const char *config_string =
+    "--SERVER=host10.example.com "
+    "--SERVER=host11.example.com "
+    "--SERVER=host10.example.com";
+  memcached_st *memc= memcached(config_string, strlen(config_string);
+  {
+    // ...
+  }
+   memcached_free(memc);
+
+In the above code you create a :type:`memcached_st` object with three server 
+by making use of :func:`memcached_create`.
+
+Creating a pool of servers
+--------------------------
+
+.. code-block:: c
+
+  const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com";
+  
+  memcached_pool_st* pool= memcached_pool(config_string, strlen(config_string));
+
+  memcached_return_t rc;
+
+  memcached_st *memc= memcached_pool_pop(pool, false, &rc);
+
+  // .... do work
+
+  /*
+    Release the memc_ptr that was pulled from the pool
+  */
+  memcached_pool_push(pool, memc);
+
+  /*
+    Destroy the pool.
+  */
+  memcached_pool_destroy(pool);
+
+In the above code you create a :type:`memcached_pool_st` object with three
+server by making use of :func:`memcached_pool()`.
+
+When :func:`memcached_pool_destroy()` all memory will be released that is associated
+with the pool.
+
+Adding a value to the server
+----------------------------
+
+.. code-block:: c
+
+    char *key= "foo";
+    char *value= "value";
+    time_t expires = 0;
+    uint32_t flags = 0;
+
+    memcached_return_t rc = memcached_set(memc,
+                                         key, strlen(key),
+                                         value, value_length,
+                                         expires, flags);
+
+    if (rc != MEMCACHED_SUCCESS)
+    {
+        // handle failure
+    }
+
+It is best practice to always look at the return value of any operation.
+
+Fetching multiple values
+------------------------
+
+.. code-block:: c
+
+    memcached_return_t rc;
+    char *keys[]= {"fudge", "son", "food"};
+    size_t key_length[]= {5, 3, 4};
+    unsigned int x;
+    uint32_t flags;
+
+    char return_key[MEMCACHED_MAX_KEY];
+    size_t return_key_length;
+    char *return_value;
+    size_t return_value_length;
+
+    rc= memcached_mget(memc, keys, key_length, 3);
+
+    x= 0;
+    while ((return_value= memcached_fetch(memc, return_key, &return_key_length,
+                                     &return_value_length, &flags, &rc)))
+    {
+        free(return_value);
+        x++;
+    }
+
+Notice that you freed values returned from memcached_fetch(). The define
+`MEMCACHED_MAX_KEY` is provided for usage.
+
+SEE ALSO
+--------
+
+    :manpage:`memcached(1)`
+