addserver.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f4098e2bac4bcc136b95b85badcf4476fa683477 Maintainer: takagi Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="memcache.addserver">
 <refnamediv>
  <refname>Memcache::addServer</refname>
  <refname>memcache_add_server</refname>
  <refpurpose>コネクションプールに memcached サーバーを追加する</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><initializer>11211</initializer></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>callable</type><parameter>failure_callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>timeoutms</parameter></methodparam>
  </methodsynopsis>
    <methodsynopsis>
   <type>bool</type><methodname>memcache_add_server</methodname>
   <methodparam><type>Memcache</type><parameter>memcache</parameter></methodparam>
   <methodparam><type>string</type><parameter>host</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>11211</initializer></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>callable</type><parameter>failure_callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>timeoutms</parameter></methodparam>
  </methodsynopsis>

  <simpara>
   <function>Memcache::addServer</function> は、コネクションプールに
   サーバーを追加します。
  </simpara>

  <simpara>
   (<function>Memcache::connect</function> および
   <function>Memcache::pconnect</function> ではなく)
   このメソッドを使用すると、ネットワーク接続は
   それが実際に必要となるときまで確立されません。
   つまり、大量のサーバーをプールに追加した場合に、
   それらすべてが使用されることはないとしてもオーバーヘッドが発生しないということです。
  </simpara>

  <simpara>
   他のサーバーが使用可能である場合、あらゆるメソッドのあらゆる段階について
   ユーザーが意識しないままにフェイルオーバー処理が行われます。
   ソケットあるいは Memcaches サーバーレベルで発生したあらゆるエラー
   (ただし out-of-memory は除く) に対してフェイルオーバーが動作します。
   既存のキーを追加しようとしたなどの通常のクライアントエラーの場合は、
   フェイルオーバー処理は起動しません。
  </simpara>

  <note>
   <simpara>
    この関数は、Memcache バージョン 2.0.0 で追加されました。
   </simpara>
  </note>

 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>host</parameter></term>
    <listitem>
     <simpara>
      memcached が接続を待ち受けるホストを指定します。
      このパラメータには別のトランスポート層を指定することもできます。たとえば
      <literal>unix:///path/to/memcached.sock</literal>
      のようにすると Unix ドメインソケットを使用できます。この場合、
      <parameter>port</parameter> は <literal>0</literal>
      を指定しなければなりません。
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>port</parameter></term>
    <listitem>
     <simpara>
      memcached が接続を待ち受けるポートを指定します。
      Unix ドメインソケットを使用する場合は、このパラメータを <literal>0</literal>
      とします。
     </simpara>
     <simpara>
      <parameter>port</parameter> を指定しなかったときのデフォルトは
      <link linkend="ini.memcache.default-port">memcache.default_port</link>
      となります。そのため、このメソッドをコールするときにはポートを明示しておくことをおすすめします。
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>persistent</parameter></term>
    <listitem>
     <simpara>
      持続的な接続を使用するかどうかを指定します。
      デフォルトは &true; です。
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>weight</parameter></term>
    <listitem>
     <simpara>
      このサーバーに対して割り当てる容器の数を指定します。これは、
      このサーバーが選択される可能性を左右します。選択される可能性は、
      すべてのサーバーの weight の合計に対するこのパラメータの割合で
      決まります。
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>timeout</parameter></term>
    <listitem>
     <simpara>
      デーモンへの接続の際に使用する値 (秒単位) です。
      デフォルト値を 1 秒でも変更する前には十分注意してください。
      接続が遅くなってしまうと、 キャッシュ処理のメリットが
      なくなってしまいます。
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>retry_interval</parameter></term>
    <listitem>
     <simpara>
      サーバーとの接続が失敗した際に再試行を行う頻度を設定します。
      デフォルト値は 15 秒です。このパラメータを -1 にすると、
      自動的な再試行を行いません。
      <function>dl</function> を使用してこの拡張モジュールが動的に
      読み込まれている場合は、このパラメータおよび
      <parameter>persistent</parameter> は何の効果も及ぼしません。
     </simpara>
     <simpara>
      失敗した接続構造体は、個々にタイムアウト値を持っており、
      タイムアウト時間が経過するまでは、バックエンドから新たな要求が来ても
      その構造体はスキップされます。時間が経過すると、
      その接続が無事再接続されるか、あるいはさらに
      <parameter>retry_interval</parameter> 秒の間、接続失敗と記録されます。
      典型的な効果は、ウェブサーバーの各子プロセスがページを送り出す際に
      <parameter>retry_interval</parameter> 秒ごとに接続を再試行することです。
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>status</parameter></term>
    <listitem>
     <simpara>
      サーバーがオンライン状態であるかどうかを制御します。このパラメータを
      &false; にし、<parameter>retry_interval</parameter> を -1
      と設定すると、失敗したサーバーもコネクションプールに残します。
      これにより、キー配布アルゴリズムに影響を与えないようにします。
      このサーバーへのリクエストは、フェイルオーバーされるか失敗します。
      どちらになるかは <parameter>memcache.allow_failover</parameter>
      の設定によって決まります。デフォルトは &true; で、
      サーバーがオンライン状態であることを意味します。
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>failure_callback</parameter></term>
    <listitem>
     <simpara>
      エラーが発生した際に実行されるコールバック関数を指定できるようにします。
      コールバック関数は、フェイルオーバー処理の前に実行されます。
      この関数は、ふたつの引数 (ホスト名、失敗したサーバーのポート)
      を受け取ります。
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>timeoutms</parameter></term>
    <listitem>
     <simpara>

     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   &return.success;
  </simpara>
 </refsect1>

<refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>Memcache::addServer</function> の例</title>
   <programlisting role="php">
<![CDATA[
<?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);

?>
]]>
   </programlisting>
  </example>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <simpara>
    <parameter>port</parameter> を省略した場合は、PHP の ini 設定
    <link linkend="ini.memcache.default-port">memcache.default_port</link>
    の値をデフォルトとして使います。
    もしこの値がアプリケーションのどこかで変更されていれば、予期せぬ結果を引き起こすかもしれません。
    このメソッドをコールするときには、常にポートを明示しておくことをおすすめします。
   </simpara>
  </warning>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <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>
 </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:"~/.phpdoc/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
-->