reference/memcached/memcached/getmulti.xml
1d8068ecb070fdc360d750e0c1f3f15796e61ec0
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<refentry xml:id="memcached.getmulti" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>Memcached::getMulti</refname>
...
...
@@ -9,35 +8,33 @@
9
8

10
9
<refsect1 role="description">
11
10
&reftitle.description;
12
-
<methodsynopsis>
13
-
<modifier>public</modifier> <type>mixed</type><methodname>Memcached::getMulti</methodname>
11
+
<methodsynopsis role="Memcached">
12
+
<modifier>public</modifier> <type class="union"><type>array</type><type>false</type></type><methodname>Memcached::getMulti</methodname>
14
13
<methodparam><type>array</type><parameter>keys</parameter></methodparam>
15
-
<methodparam choice="opt"><type>array</type><parameter role="reference">cas_tokens</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
14
+
<methodparam choice="opt"><type>int</type><parameter>get_flags</parameter><initializer>0</initializer></methodparam>
17
15
</methodsynopsis>
18
16
<para>
19
17
<function>Memcached::getMulti</function> is similar to
20
18
<methodname>Memcached::get</methodname>, but instead of a single key
21
19
item, it retrieves multiple items the keys of which are specified in the
22
-
<parameter>keys</parameter> array. If <parameter>cas_tokens</parameter>
23
-
variable is provided, it is filled with the CAS token values for the found
24
-
items.
20
+
<parameter>keys</parameter> array.
25
21
<note>
26
22
<para>
27
-
Unlike <methodname>Memcached::get</methodname> it is not possible to
28
-
specify a read-through cache callback for
29
-
<function>Memcached::getMulti</function>, because the memcache protocol
30
-
does not provide information on which keys were not found in the multi-key
31
-
request.
23
+
Before v3.0 a second argument <parameter role="reference">cas_tokens</parameter> was in use.
24
+
It was filled with the CAS token values for the found items.
25
+
The <parameter role="reference">cas_tokens</parameter> parameter was removed in v3.0 of the extension.
26
+
It was replaced with a new flag <constant>Memcached::GET_EXTENDED</constant>
27
+
that needs is to be used as the value for <parameter>get_flags</parameter>.
32
28
</para>
33
29
</note>
34
30
</para>
35
31
<para>
36
-
The <parameter>flags</parameter> parameter can be used to specify
37
-
additional options for <function>Memcached::getMulti</function>. Currently,
38
-
the only available option is
39
-
<constant>Memcached::GET_PRESERVE_ORDER</constant> that ensures that the
32
+
The <parameter>get_flags</parameter> parameter can be used to specify
33
+
additional options for <function>Memcached::getMulti</function>.
34
+
<constant>Memcached::GET_PRESERVE_ORDER</constant> ensures that the
40
35
keys are returned in the same order as they were requested in.
36
+
<constant>Memcached::GET_EXTENDED</constant> ensures that the
37
+
CAS tokens will be fetched too.
41
38
</para>
42
39
</refsect1>
43
40

...
...
@@ -54,15 +51,7 @@
54
51
</listitem>
55
52
</varlistentry>
56
53
<varlistentry>
57
-
<term><parameter>cas_tokens</parameter></term>
58
-
<listitem>
59
-
<para>
60
-
The variable to store the CAS tokens for the found items.
61
-
</para>
62
-
</listitem>
63
-
</varlistentry>
64
-
<varlistentry>
65
-
<term><parameter>flags</parameter></term>
54
+
<term><parameter>get_flags</parameter></term>
66
55
<listitem>
67
56
<para>
68
57
The flags for the get operation.
...
...
@@ -81,14 +70,75 @@
81
70
</para>
82
71
</refsect1>
83
72

73
+
<refsect1 role="changelog">
74
+
&reftitle.changelog;
75
+
<informaltable>
76
+
<tgroup cols="2">
77
+
<thead>
78
+
<row>
79
+
<entry>&Version;</entry>
80
+
<entry>&Description;</entry>
81
+
</row>
82
+
</thead>
83
+
<tbody>
84
+
<row>
85
+
<entry>PECL memcached 3.0.0</entry>
86
+
<entry>
87
+
The <parameter role="reference">cas_tokens</parameter> parameter was removed.
88
+
The <constant>Memcached::GET_EXTENDED</constant> was added and when passed as a flag it ensures the CAS tokens to be fetched.
89
+
</entry>
90
+
</row>
91
+
</tbody>
92
+
</tgroup>
93
+
</informaltable>
94
+
</refsect1>
95
+

84
96
<refsect1 role="examples">
85
97
&reftitle.examples;
86
98
<para>
87
99
<example>
88
-
<title><function>Memcached::getMulti</function> example</title>
100
+
<title><function>Memcached::getMulti</function> example for Memcached v3</title>
101
+
<programlisting role="php">
102
+
<![CDATA[
103
+
<?php
104
+
// Valid for v3 of the extension
105
+

106
+
$m = new Memcached();
107
+
$m->addServer('localhost', 11211);
108
+

109
+
$items = array(
110
+
'key1' => 'value1',
111
+
'key2' => 'value2',
112
+
'key3' => 'value3'
113
+
);
114
+
$m->setMulti($items);
115
+
$result = $m->getMulti(array('key1', 'key3', 'badkey'));
116
+
var_dump($result);
117
+
?>
118
+
]]>
119
+
</programlisting>
120
+
&example.outputs.similar;
121
+
<screen>
122
+
<![CDATA[
123
+
array(2) {
124
+
["key1"]=>
125
+
string(6) "value1"
126
+
["key3"]=>
127
+
string(6) "value3"
128
+
}
129
+
]]>
130
+
</screen>
131
+
</example>
132
+
</para>
133
+

134
+
<para>
135
+
<example>
136
+
<title><function>Memcached::getMulti</function> example for Memcached v1 and v2</title>
89
137
<programlisting role="php">
90
138
<![CDATA[
91
139
<?php
140
+
// Valid for v1 and v2 of the extension
141
+

92
142
$m = new Memcached();
93
143
$m->addServer('localhost', 11211);
94
144

...
...
@@ -122,12 +172,60 @@ array(2) {
122
172
</screen>
123
173
</example>
124
174
</para>
175
+

125
176
<para>
126
177
<example>
127
-
<title><constant>Memcached::GET_PRESERVE_ORDER</constant> example</title>
178
+
<title><constant>Memcached::GET_PRESERVE_ORDER</constant> example for Memcached v3</title>
128
179
<programlisting role="php">
129
180
<![CDATA[
130
181
<?php
182
+
// Valid for v3 of the extension
183
+

184
+
$m = new Memcached();
185
+
$m->addServer('localhost', 11211);
186
+

187
+
$data = array(
188
+
'foo' => 'foo-data',
189
+
'bar' => 'bar-data',
190
+
'baz' => 'baz-data',
191
+
'lol' => 'lol-data',
192
+
'kek' => 'kek-data',
193
+
);
194
+

195
+
$m->setMulti($data, 3600);
196
+

197
+
$keys = array_keys($data);
198
+
$keys[] = 'zoo';
199
+
$got = $m->getMulti($keys, Memcached::GET_PRESERVE_ORDER);
200
+

201
+
foreach ($got as $k => $v) {
202
+
echo "$k $v\n";
203
+
}
204
+
?>
205
+
]]>
206
+
</programlisting>
207
+
&example.outputs.similar;
208
+
<screen>
209
+
<![CDATA[
210
+
foo foo-data
211
+
bar bar-data
212
+
baz baz-data
213
+
lol lol-data
214
+
kek kek-data
215
+
zoo
216
+
]]>
217
+
</screen>
218
+
</example>
219
+
</para>
220
+

221
+
<para>
222
+
<example>
223
+
<title><constant>Memcached::GET_PRESERVE_ORDER</constant> example for Memcached v1 and v2</title>
224
+
<programlisting role="php">
225
+
<![CDATA[
226
+
<?php
227
+
// Valid for v1 and v2 of the extension
228
+

131
229
$m = new Memcached();
132
230
$m->addServer('localhost', 11211);
133
231

...
...
@@ -179,7 +277,6 @@ zoo
179
277
</refsect1>
180
278

181
279
</refentry>
182
-

183
280
<!-- Keep this comment at the end of the file
184
281
Local variables:
185
282
mode: sgml
186
283



Tools (Spanish Manual)