Merge in additional documentation updates.

[m6w6/libmemcached] / docs / libmemcached_examples.rst

diff --git a/docs/libmemcached_examples.rst b/docs/libmemcached_examples.rst
index 82e2858852f825e9a326d06650b1d5e53941eba3..5c3acf6a9ac2725ac2a028dc0394d9664403b48e 100644 (file)
--- a/docs/libmemcached_examples.rst
+++ b/docs/libmemcached_examples.rst
@@ -1,29 +1,24 @@
-.. highlight:: perl
+========
+Examples
+========

 
 

+Examples for libmemcached

 
 

-****
-NAME
-****
-
-
-libmemcached_examples - Examples for libmemcached
-
-
-***********
+-----------

 DESCRIPTION
 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.
 
 
 
 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.
 

-Creating and Freeing structure
-==============================
+-----------------------------------------------
+Creating and Freeing the memcached_st structure
+-----------------------------------------------

 
 
 
 

-
-.. code-block:: perl
+.. code-block:: c

 
    memcached_st *memc;
    memcached_return_t rc;
 
    memcached_st *memc;
    memcached_return_t rc;


@@ -37,46 +32,69 @@ The above code would create a connection and then free the connection when
 finished.
 
 
 finished.
 
 

+---------------------

 Connecting to servers
 Connecting to servers

-=====================
+---------------------

 
 
 
 
 
 

-.. code-block:: perl
+.. code-block:: c

 
 

-   memcached_server_st *servers;
-   memcached_st *memc= memcached_create(NULL);
-   char servername[]= "0.example.com";
- 
-   servers= memcached_server_list_append(NULL, servername, 400, &rc);
- 
-   for (x= 0; x < 20; x++)
+   const char *config_string= "--SERVER=host10.example.com --SERVER=host11.example.com --SERVER=host10.example.com"
+   memcached_st *memc= memcached_create_with_options(config_string, strlen(config_string);

    {
    {

-     char buffer[SMALL_STRING_LEN];
- 
-     snprintf(buffer, SMALL_STRING_LEN, "%u.example.com", 400+x);
-     servers= memcached_server_list_append(servers, buffer, 401, &rc);
+    ...

    }
    }

-   rc= memcached_server_push(memc, servers);
-   memcached_server_free(servers);

    memcached_free(memc);
 
 
    memcached_free(memc);
 
 

-In the above code you create a \ ``memcached_st``\  object that you then feed in a
-single host into. In the for loop you build a \ ``memcached_server_st``\ 
-pointer that you then later feed via memcached_server_push() into the
-\ ``memcached_st``\  structure.
+In the above code you create a \ ``memcached_st``\  object with three server by making use of :manpage:`memcached_create_with_options(3)`.
+
+
+--------------------------
+Creating a pool of servers
+--------------------------
+
+
+
+.. code-block:: c

 
 

-You can reuse the \ ``memcached_server_st``\  object with multile \ ``memcached_st``\ 
-structures.
+  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 \ ``memcached_pool_st``\  object with three
+server by making use of :manpage:`memcached_pool(3)`.
+
+When memcached_pool_destroy() all memory will be released that is associated
+with the pool.
+
+
+----------------------------

 Adding a value to the server
 Adding a value to the server

-============================
+----------------------------

 
 
 
 
 
 

-.. code-block:: perl
+.. code-block:: c

 
    char *key= "foo";
    char *value;
 
    char *key= "foo";
    char *value;


@@ -103,12 +121,13 @@ Adding a value to the server
 It is best practice to always look at the return value of any operation.
 
 
 It is best practice to always look at the return value of any operation.
 
 

+------------------------

 Fetching multiple values
 Fetching multiple values

-========================
+------------------------

 
 
 
 
 
 

-.. code-block:: perl
+.. code-block:: c

 
    memcached_return_t rc;
    char *keys[]= {"fudge", "son", "food"};
 
    memcached_return_t rc;
    char *keys[]= {"fudge", "son", "food"};


@@ -137,27 +156,19 @@ Notice that you freed values returned from memcached_fetch(). The define
 
 
 
 
 
 

-****
+----

 HOME
 HOME

-****
+----

 
 
 To find out more information please check:
 `https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
 
 
 
 
 To find out more information please check:
 `https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
 
 

-******
-AUTHOR
-******
-
-
-Brian Aker, <brian@tangent.org>
-
-
-********
+--------

 SEE ALSO
 SEE ALSO

-********
+--------

 
 
 
 

-memcached(1)
+:manpage:`memcached(1)`