Memcache::addServer

(PECL memcache >= 2.0.0)

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

説明

Memcache::addServer(
    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

戻り値

成功した場合に 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() - サーバーの状態を返す

Found A Problem?

Learn How To Improve This Page • Submit a Pull Request • Report a Bug

＋add a note

User Contributed Notes 6 notes

down

rstaveley at seseit dot com ¶

13 years ago

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.

down

enno dot rehling at gmail dot com ¶

13 years ago

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).

down

joewynn dot nz+phpnet at gmail dot com ¶

11 years ago

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=58193

down

eu at serbannistor dot ro ¶

13 years ago

Actually 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).

down

iwind dot liu at gmail dot com ¶

14 years ago

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.

down

-5

Jean-Baptiste Quenot ¶

16 years ago

The default value for the "weight" argument is 1

＋add a note