svn: /phpdoc/ja/trunk/reference/opcache/ book.xml preload.xml

mumumu                                   Fri, 31 Jul 2020 00:17:01 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=350251

Log:
[working] Document configuring opcache preloading

Patch provided by Larry Garfield.

Changed paths:
    U   phpdoc/ja/trunk/reference/opcache/book.xml
    A   phpdoc/ja/trunk/reference/opcache/preload.xml

Modified: phpdoc/ja/trunk/reference/opcache/book.xml
===================================================================
--- phpdoc/ja/trunk/reference/opcache/book.xml	2020-07-31 00:11:21 UTC (rev 350250)
+++ phpdoc/ja/trunk/reference/opcache/book.xml	2020-07-31 00:17:01 UTC (rev 350251)
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 330685 Maintainer: mumumu Status: ready -->
+<!-- EN-Revision: 350245 Maintainer: mumumu Status: ready -->
+<!-- Credits: mumumu -->

 <book xml:id="book.opcache" xmlns="http://docbook.org/ns/docbook">
  <?phpdoc extension-membership="core" ?>
@@ -18,6 +19,7 @@
  </preface>

  &reference.opcache.setup;
+ &reference.opcache.preload;
  &reference.opcache.reference;

 </book>

Added: phpdoc/ja/trunk/reference/opcache/preload.xml
===================================================================
--- phpdoc/ja/trunk/reference/opcache/preload.xml	                        (rev 0)
+++ phpdoc/ja/trunk/reference/opcache/preload.xml	2020-07-31 00:17:01 UTC (rev 350251)
@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 350245 Maintainer: mumumu Status: working -->
+
+<chapter xml:id="opcache.preloading" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>コードの事前ロード</title>
+
+ <para>
+  PHP 7.4.0 以降、エンジンの起動時に opcache にあらかじめ読み込ませるスクリプトを指定できるようになりました。
+  指定されたファイルに存在する (関数やクラスなどの) あらゆるシンボルは、
+  明示的にインクルードすることなく全てのリクエストからグローバルに利用できるようになります。
+  これにより、(コードが常に利用できるようになるため) メモリ使用量と、
+  パフォーマンスおよび便利さのトレードオフが発生します。
+  あらかじめ読み込まれたスクリプトをクリアするには PHP プロセスの再起動が必要です。
+  つまり、この機能は本番環境でのみ役に立つものです。開発環境では役に立ちません。
+ </para>
+
+ <para>
+  パフォーマンスとメモリ使用量の最適なトレードオフは、アプリケーションによって異なることに注意して下さい。
+  "全てをあらかじめ読み込む" ことはもっとも簡単な戦略かもしれませんが、
+  必ずしも最適な戦略とは限りません。
+  さらに、コードの事前ロードは、リクエストが終了しても継続して生き残るプロセスの場合にだけ役に立ちます。
+  つまり、opcache が有効になった CLI スクリプトは動作はしますが、
+  一般的にコードの事前ロードは役に立ちません。
+  但し、<link linkend="ffi.examples-complete">FFI</link> 経由でコードの事前ロードを使う場合は例外です。
+ </para>
+
+ <note>
+  <para>
+   コードの事前ロードは、Windows ではサポートされていません。
+  </para>
+ </note>
+
+ <para>
+  コードの事前ロードを設定するには、2つのステップが必要です。
+  まず、opcache を有効にしなければなりません。
+  その上で、<link linkend="ini.opcache.preload">opcache.preload</link> の値を &php.ini; に設定します。
+ </para>
+
+ <informalexample>
+  <programlisting role="ini">
+<![CDATA[
+opcache.preload=preload.php
+]]>
+  </programlisting>
+ </informalexample>
+
+ <para>
+  <filename>preload.php</filename> is an arbitrary file that will run once at server startup
+  (PHP-FPM, mod_php, etc.) and load code into persistent memory.  If PHP will be run as
+  root (not recommended), the <link linkend="ini.opcache.preload-user">opcache.preload_user</link>
+  value can specify an alternate system user to run the preloading.  Running preloading as
+  root is not allowed.
+ </para>
+
+ <para>
+  In the <filename>preload.php</filename> script, any file referenced by <function>include</function>,
+  <function>include_once</function>, <function>require</function>, <function>require_once</function>, or
+  <function>opcache_compile_file</function> will be parsed into persistent memory.  In the following example,
+  all <filename>.php</filename> files in the <filename>src</filename> directory will be preloaded, unless they
+  are a <literal>Test</literal> file.
+ </para>
+
+ <informalexample>
+  <programlisting role="php">
+<![CDATA[
+<?php
+$directory = new RecursiveDirectoryIterator(__DIR__ . '/src');
+$fullTree = new RecursiveIteratorIterator($directory);
+$phpFiles = new RegexIterator($fullTree, '/.+((?<!Test)+\.php$)/i', RecursiveRegexIterator::GET_MATCH);
+
+foreach ($phpFiles as $key => $file) {
+    require_once($file[0]);
+}
+?>
+]]>
+  </programlisting>
+ </informalexample>
+
+ <para>
+  Both <function>include</function> and <function>opcache_compile_file</function> will work, but have different
+  implications for how code gets handled.
+
+  <itemizedlist>
+   <listitem><simpara><function>include</function> will execute code in the file,
+    while <function>opcache_compile_file</function> will not.  That means only the former supports
+    conditional declaration (functions declared inside an if-block).</simpara></listitem>
+   <listitem><simpara>Because <function>include</function> will execute code, nested <function>include</function>d
+    files will also be parsed and their declarations preloaded.</simpara></listitem>
+   <listitem><simpara><function>opcache_compile_file</function> can load files in any order.  That is, if
+    <filename>a.php</filename> defines  class <literal>A</literal> and <filename>b.php</filename> defines class
+    <literal>B</literal> that extends <literal>A</literal>, then <function>opcache_compile_file</function> can
+    load those two files in any order.  When using <function>include</function>, however, <filename>a.php</filename>
+    <emphasis>must</emphasis> be included first.</simpara></listitem>
+   <listitem><simpara>In either case, if a later script includes a file that has already been preloaded then
+    its contents will still execute, but any symbols it defines will not be re-defined.  Using
+    <function>include_once</function> will not prevent the file from being included a second time.</simpara></listitem>
+  </itemizedlist>
+
+  Which approach is better therefore depends on the desired behavior.  With code that would otherwise use an
+  autoloader, <function>opcache_compile_file</function> allows for greater flexibility.  With code that would
+  otherwise be loaded manually, <function>include</function> will be more robust.
+ </para>
+
+</chapter>
+
+<!-- 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
+-->


Property changes on: phpdoc/ja/trunk/reference/opcache/preload.xml
___________________________________________________________________
Added: svn:keywords
## -0,0 +1 ##
+Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL
\ No newline at end of property