git.m6w6.name Git - awesomized/libmemcached/blob - docs/source/libmemcached/examples.rst

   1 libmemcached Examples
   2 =====================
   3
   4 Examples for libmemcached
   5
   6 DESCRIPTION
   7 -----------
   8
   9 For full examples, test cases are found in tests/\*.c in the main distribution.
  10 These are always up to date, and are used for each test run of the library.
  11
  12 Connecting to servers
  13 ---------------------
  14
  15 .. code-block:: c
  16
  17   const char *config_string =
  18     "--SERVER=host10.example.com "
  19     "--SERVER=host11.example.com "
  20     "--SERVER=host10.example.com";
  21   memcached_st *memc= memcached(config_string, strlen(config_string);
  22   {
  23     // ...
  24   }
  25    memcached_free(memc);
  26
  27 In the above code you create a `memcached_st` object with three server by making
  28 use of `memcached_create`.
  29
  30 Creating a pool of servers
  31 --------------------------
  32
  33 .. code-block:: c
  34
  35   const char *config_string =
  36     "--SERVER=host10.example.com "
  37     "--SERVER=host11.example.com "
  38     "--SERVER=host10.example.com";
  39
  40   memcached_pool_st* pool= memcached_pool(config_string, strlen(config_string));
  41
  42   memcached_return_t rc;
  43
  44   memcached_st *memc= memcached_pool_pop(pool, false, &rc);
  45
  46   // .... do work
  47
  48   /*
  49     Release the memc_ptr that was pulled from the pool
  50   */
  51   memcached_pool_push(pool, memc);
  52
  53   /*
  54     Destroy the pool.
  55   */
  56   memcached_pool_destroy(pool);
  57
  58 In the above code you create a `memcached_pool_st` object with three server by
  59 making use of `memcached_pool()`.
  60
  61 When `memcached_pool_destroy()` all memory will be released that is associated
  62 with the pool.
  63
  64 Adding a value to the server
  65 ----------------------------
  66
  67 .. code-block:: c
  68
  69     char *key= "foo";
  70     char *value= "value";
  71     time_t expires = 0;
  72     uint32_t flags = 0;
  73
  74     memcached_return_t rc = memcached_set(memc,
  75                                          key, strlen(key),
  76                                          value, value_length,
  77                                          expires, flags);
  78
  79     if (rc != MEMCACHED_SUCCESS)
  80     {
  81         // handle failure
  82     }
  83
  84 It is best practice to always look at the return value of any operation.
  85
  86 Fetching multiple values
  87 ------------------------
  88
  89 .. code-block:: c
  90
  91     memcached_return_t rc;
  92     char *keys[]= {"fudge", "son", "food"};
  93     size_t key_length[]= {5, 3, 4};
  94     unsigned int x;
  95     uint32_t flags;
  96
  97     char return_key[MEMCACHED_MAX_KEY];
  98     size_t return_key_length;
  99     char *return_value;
 100     size_t return_value_length;
 101
 102     rc= memcached_mget(memc, keys, key_length, 3);
 103
 104     x= 0;
 105     while ((return_value= memcached_fetch(memc, return_key, &return_key_length,
 106                                      &return_value_length, &flags, &rc)))
 107     {
 108         free(return_value);
 109         x++;
 110     }
 111
 112 Notice that you freed values returned from memcached_fetch(). The define
 113 `MEMCACHED_MAX_KEY` is provided for usage.
 114
 115 SEE ALSO
 116 --------
 117
 118     :manpage:`memcached(1)`
 119