Memcache::addServer
コネクションプールに memcached サーバーを追加する
説明
bool Memcache::addServer(
string $host,
int $port = 11211,
bool $persistent = ?,
int $weight = ?,
int $timeout = ?,
int $retry_interval = ?,
bool $status = ?,
callable $failure_callback = ?,
int $timeoutms = ?
)
(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
-
戻り値
成功した場合に true を、失敗した場合に false を返します。
例
例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
- Memcache::pconnect
- Memcache::close
- Memcache::setServerParams
- Memcache::getServerStatus