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