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