コネクションプールに memcached サーバーを追加する

# Memcache::addServer

# memcache_add_server

(PECL memcache >= 2.0.0)

Memcache::addServer -- memcache_add_server — コネクションプールに memcached サーバーを追加する

### 説明

function Memcache::addServer(
string `$host`,
int `$port` = 11211,
bool `$persistent` = ?,
int `$weight` = ?,
int `$timeout` = ?,
int `$retry_interval` = ?,
bool `$status` = ?,
callable `$failure_callback` = ?,
int `$timeoutms` = ?
): bool
function memcache_add_server(
Memcache `$memcache`,
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::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() - memcached サーバーへの接続をオープンする
- Memcache::pconnect() - memcached サーバーへの持続的な接続をオープンする
- Memcache::close() - memcached サーバーとの接続を閉じる
- Memcache::setServerParams() - サーバーのパラメータおよび状態を、実行時に変更する
- Memcache::getServerStatus() - サーバーの状態を返す

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open