1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.13 $ -->
<refentry xml:id="function.memcache-addserver" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>Memcache::addServer</refname>
<refpurpose>Add a memcached server to connection pool</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>Memcache::addServer</methodname>
<methodparam><type>string</type><parameter>host</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>port</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>persistent</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>weight</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>timeout</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>retry_interval</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>status</parameter></methodparam>
<methodparam choice="opt"><type>callback</type><parameter>failure_callback</parameter></methodparam>
</methodsynopsis>
<para>
<function>Memcache::addServer</function> adds a server to the connection
pool. The connection, which was opened using <function>Memcache::addServer</function>
will be automatically closed at the end of script execution, you can also close it
manually with <function>Memcache::close</function>.
You can also use the <function>memcache_add_server</function> function.
</para>
<para>
When using this method (as opposed to <function>Memcache::connect</function> and
<function>Memcache::pconnect</function>) the network connection is not established
until actually needed. Thus there is no overhead in adding a large number of servers
to the pool, even though they might not all be used.
</para>
<para>
Failover may occur at any stage in any of the methods, as long as other
servers are available the request the user won't notice. Any kind of
socket or Memcached server level errors (except out-of-memory) may trigger
the failover. Normal client errors such as adding an existing key will not
trigger a failover.
</para>
<note>
<para>
This function has been added to Memcache version 2.0.0.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>host</parameter></term>
<listitem>
<para>
Point to the host where memcached is listening for connections. This parameter
may also specify other transports like <literal>unix:///path/to/memcached.sock</literal>
to use UNIX domain sockets, in this case <parameter>port</parameter> must also
be set to <literal>0</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>port</parameter></term>
<listitem>
<para>
Point to the port where memcached is listening for connections.
This parameter is optional and its default value is 11211. Set this
parameter to <literal>0</literal> when using UNIX domain sockets.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>persistent</parameter></term>
<listitem>
<para>
Controls the use of a persistent connection. Default to &true;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>weight</parameter></term>
<listitem>
<para>
Number of buckets to create for this server which in turn control its
probability of it being selected. The probability is relative to the
total weight of all servers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>timeout</parameter></term>
<listitem>
<para>
Value in seconds which will be used for connecting to the daemon. Think
twice before changing the default value of 1 second - you can lose all
the advantages of caching if your connection is too slow.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>retry_interval</parameter></term>
<listitem>
<para>
Controls how often a failed server will be retried, the default value
is 15 seconds. Setting this parameter to -1 disables automatic retry.
Neither this nor the <parameter>persistent</parameter> parameter has any
effect when the extension is loaded dynamically via <function>dl</function>.
</para>
<para>
Each failed connection struct has its own timeout and before it has expired
the struct will be skipped when selecting backends to serve a request. Once
expired the connection will be successfully reconnected or marked as failed
for another <parameter>retry_interval</parameter> seconds. The typical
effect is that each web server child will retry the connection about every
<parameter>retry_interval</parameter> seconds when serving a page.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>status</parameter></term>
<listitem>
<para>
Controls if the server should be flagged as online. Setting this parameter
to &false; and <parameter>retry_interval</parameter> to -1 allows a failed
server to be kept in the pool so as not to affect the key distribution
algoritm. Requests for this server will then failover or fail immediatly
depending on the <parameter>memcache.allow_failover</parameter> setting.
Default to &true;, meaning the server should be considered online.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>failure_callback</parameter></term>
<listitem>
<para>
Allows the user to specify a callback function to run upon encountering an
error. The callback is run before failover is attemped. The function takes
two parameters, the hostname and port of the failed server.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
&return.success;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>Memcache::addServer</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
/* OO API */
$memcache = new Memcache;
$memcache->addServer('memcache_host', 11211);
$memcache->addServer('memcache_host2', 11211);
/* procedural API */
$memcache_obj = memcache_connect('memcache_host', 11211);
memcache_add_server($memcache_obj, 'memcache_host2', 11211);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Memcache::connect</function></member>
<member><function>Memcache::pconnect</function></member>
<member><function>Memcache::close</function></member>
<member><function>Memcache::setServerParams</function></member>
<member><function>Memcache::getServerStatus</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
