Memcache::addServer
(PECL memcache >= 2.0.0)
Memcache::addServer — コネクションプールに memcached サーバーを追加する
説明
string
$host,int
$port = 11211,bool
$persistent = ?,int
$weight = ?,int
$timeout = ?,int
$retry_interval = ?,bool
$status = ?,callable
$failure_callback = ?,int
$timeoutms = ?): bool
Memcache::addServer() は、コネクションプールに サーバーを追加します。 memcache_add_server() 関数を使用することも可能です。
(Memcache::connect() および Memcache::pconnect() ではなく) このメソッドを使用すると、ネットワーク接続は それが実際に必要となるときまで確立されません。 つまり、大量のサーバーをプールに追加した場合に、 それらすべてが使用されることはないとしてもオーバーヘッドが発生しないということです。
他のサーバーが使用可能である場合、あらゆるメソッドのあらゆる段階について ユーザーが意識しないままにフェイルオーバー処理が行われます。 ソケットあるいは Memcaches サーバーレベルで発生したあらゆるエラー (ただし out-of-memory は除く) に対してフェイルオーバーが動作します。 既存のキーを追加しようとしたなどの通常のクライアントエラーの場合は、 フェイルオーバー処理は起動しません。
注意:
この関数は、Memcache バージョン 2.0.0 で追加されました。
パラメータ
host-
memcached が接続を待ち受けるホストを指定します。 このパラメータには別のトランスポート層を指定することもできます。たとえば
unix:///path/to/memcached.sockのようにすると Unix ドメインソケットを使用できます。この場合、portは0を指定しなければなりません。 port-
memcached が接続を待ち受けるポートを指定します。 Unix ドメインソケットを使用する場合は、このパラメータを
0とします。portを指定しなかったときのデフォルトは memcache.default_port となります。そのため、このメソッドをコールするときにはポートを明示しておくことをおすすめします。 persistent-
持続的な接続を使用するかどうかを指定します。 デフォルトは
trueです。 weight-
このサーバーに対して割り当てる容器の数を指定します。これは、 このサーバーが選択される可能性を左右します。選択される可能性は、 すべてのサーバーの weight の合計に対するこのパラメータの割合で 決まります。
timeout-
デーモンへの接続の際に使用する値 (秒単位) です。 デフォルト値を 1 秒でも変更する前には十分注意してください。 接続が遅くなってしまうと、 キャッシュ処理のメリットが なくなってしまいます。
retry_interval-
サーバーとの接続が失敗した際に再試行を行う頻度を設定します。 デフォルト値は 15 秒です。このパラメータを -1 にすると、 自動的な再試行を行いません。 dl() を使用してこの拡張モジュールが動的に 読み込まれている場合は、このパラメータおよび
persistentは何の効果も及ぼしません。失敗した接続構造体は、個々にタイムアウト値を持っており、 タイムアウト時間が経過するまでは、バックエンドから新たな要求が来ても その構造体はスキップされます。時間が経過すると、 その接続が無事再接続されるか、あるいはさらに
retry_interval秒の間、接続失敗と記録されます。 典型的な効果は、ウェブサーバーの各子プロセスがページを送り出す際にretry_interval秒ごとに接続を再試行することです。 status-
サーバーがオンライン状態であるかどうかを制御します。このパラメータを
falseにし、retry_intervalを -1 と設定すると、失敗したサーバーもコネクションプールに残します。 これにより、キー配布アルゴリズムに影響を与えないようにします。 このサーバーへのリクエストは、フェイルオーバーされるか失敗します。 どちらになるかはmemcache.allow_failoverの設定によって決まります。デフォルトはtrueで、 サーバーがオンライン状態であることを意味します。 failure_callback-
エラーが発生した際に実行されるコールバック関数を指定できるようにします。 コールバック関数は、フェイルオーバー処理の前に実行されます。 この関数は、ふたつの引数 (ホスト名、失敗したサーバーのポート) を受け取ります。
timeoutms-
例
例1 Memcache::addServer() の例
<?php
/* オブジェクト指向の API */
$memcache = new Memcache;
$memcache->addServer('memcache_host', 11211);
$memcache->addServer('memcache_host2', 11211);
/* 手続き型の API */
$memcache_obj = memcache_connect('memcache_host', 11211);
memcache_add_server($memcache_obj, 'memcache_host2', 11211);
?>注意
port を省略した場合は、PHP の ini 設定
memcache.default_port
の値をデフォルトとして使います。
もしこの値がアプリケーションのどこかで変更されていれば、予期せぬ結果を引き起こすかもしれません。
このメソッドをコールするときには、常にポートを明示しておくことをおすすめします。
参考
- Memcache::connect() - memcached サーバーへの接続をオープンする
- Memcache::pconnect() - memcached サーバーへの持続的な接続をオープンする
- Memcache::close() - memcached サーバーとの接続を閉じる
- Memcache::setServerParams() - サーバーのパラメータおよび状態を、実行時に変更する
- Memcache::getServerStatus() - サーバーの状態を返す
User Contributed Notes 6 notes
The Memcache client library is responsible for picking the right server to set/get data. That's why addServer is what you want to use rather than connect, when you have more than one Memcache server. A subsequent set/get will then connect on demand to the appropriate instance as needs be. Disconnection to whatever servers were connected to happening when you close or your script terminates.
Memcache instances added to your Memcache object via addServer should be added in the same order in your application to ensure that the same server is picked for use with the same key.
A client library may be implemented to run a CRC on the key and do a modulus over the number of instances in the list to select an instance from the list for the set/get. This ensures that data is spread nicely across the nodes.
That all works nicely behind the scenes for you in your PHP code, as long as you add your list of Memcache instances in a consistent manner with addServer.The $timeoutms argument can be used to specify the timeout in milliseconds, but isn't available in all versions. For example, it exists in php_memcache 2.2.6, but not in 3.0.4. In 2.2.6, if you specify it, then it overrides $timeout.
Caveat emptor: If $timeoutms is not specified, it defaults to the value of memcache.default_timeout_ms in php.ini, which defaults to 1000 if not set. This also overrides $timeout, which has the curious effect that $timeout is always ignored in php_memcache 2.2.6 (either in favor of $timeoutms, memcache.default_timeout_ms or the value 1000, in that order of priority).Note that this method will always return TRUE because a connection is not actually made at call time. See this bug report for more information: https://bugs.php.net/bug.php?id=58193Actually if you have two memcached servers from which one of them is on localhost, and the other is on a remote machine you can communicate with both even if you specify the loopback address for the local one.
<?php
$memcache_obj = memcache_connect("127.0.0.1", 11211);
memcache_add_server($memcache_obj, "memcache_remote_host");
$memcache_obj->set('var_key', time());
?>
This WILL communicate with both hosts but however there are two aspects that must be taken into account:
1. the communication will be done through different network interfaces with the two hosts. It will use the loopback interface for the "127.0.0.1" host (lo in my case on Linux) and the external interface for the "memcache_remote_host" (eth0 in my case). Only if you want to use the same network interface to communicate with both hosts you must use the external IPs of both machines (and all communication will go out through the eth0 interface).
2. the connection with the two hosts will be established differently because of how memcache_connect() and memcache_add_server() work. Therefore the memcache_connect() will initiate the connection to localhost through the loopback interface when it is called, while memcache_add_server() will just add the second server to the pool, but it will not send any package through the network until it's absolutely needed (for example when a memcache_set() command is issued).The weight of the server must be greater than 0.
If there is no memcached server to use, and you try to set/add variables, the apache will be crashed, with the error message "[notice] child pid 18725 exit signal Segmentation fault (11)" in error_log file.