Merge pull request #140 from hussainnaqvee/patch-1
[awesomized/libmemcached] / 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