From 6dccfde5ef3bf87bf709129b9e2d8e85954e29f4 Mon Sep 17 00:00:00 2001
From: Kalle Sommer Nielsen <kalle@php.net>
Date: Sun, 16 Oct 2016 04:14:47 +0000
Subject: [PATCH] Update the proc_nice() documentation to reflect the Windows
 support in 7.2

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@340496 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/exec/functions/proc-nice.xml | 131 ++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 3 deletions(-)

diff --git a/reference/exec/functions/proc-nice.xml b/reference/exec/functions/proc-nice.xml
index 700e683a22..8c204c3277 100644
--- a/reference/exec/functions/proc-nice.xml
+++ b/reference/exec/functions/proc-nice.xml
@@ -33,8 +33,65 @@
      <term><parameter>increment</parameter></term>
      <listitem>
       <para>
-       The increment value of the priority change.
+       The new priority value, the value of this may differ on platforms.
       </para>
+      <para>
+       on Unix, a low value, such as <literal>-20</literal> means high priority 
+       wheras a positive value have a lower priority.
+      </para>
+      <para>
+       For Windows the <parameter>increment</parameter> parameter have the 
+       following meanings:
+      </para>
+      <informaltable>
+       <tgroup cols="3">
+        <thead>
+         <row>
+          <entry valign="top">Priority class</entry>
+          <entry valign="top">Possible values</entry>
+         </row>
+        </thead>
+        <tbody>
+         <row>
+          <entry valign="top"><constant>REALTIME_PRIORITY_CLASS</constant></entry>
+          <entry valign="top">
+           <parameter>increment</parameter> <literal>&gt; 23</literal>
+          </entry>
+         </row>
+         <row>
+          <entry valign="top"><constant>HIGH_PRIORITY_CLASS</constant></entry>
+          <entry valign="top">
+           <parameter>increment</parameter> <literal>&gt; 12</literal>
+          </entry>
+         </row>
+         <row>
+          <entry valign="top"><constant>ABOVE_NORMAL_PRIORITY_CLASS</constant></entry>
+          <entry valign="top">
+           <parameter>increment</parameter> <literal>&gt; 9</literal>
+          </entry>
+         </row>
+         <row>
+          <entry valign="top"><constant>NORMAL_PRIORITY_CLASS</constant></entry>
+          <entry valign="top">
+           <parameter>increment</parameter> <literal>&gt; 7</literal> &amp; 
+           <parameter>increment</parameter> <literal>&lt; 4</literal>
+          </entry>
+         </row>
+         <row>
+          <entry valign="top"><constant>IDLE_PRIORITY_CLASS</constant></entry>
+          <entry valign="top">
+           <parameter>increment</parameter> <literal>&gt; 5</literal>
+          </entry>
+         </row>
+         <row>
+          <entry valign="top"><constant>BELOW_NORMAL_PRIORITY_CLASS</constant></entry>
+          <entry valign="top">
+           <parameter>increment</parameter> <literal>&gt; 3</literal>
+          </entry>
+         </row>
+        </tbody>
+       </tgroup>
+      </informaltable>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -50,6 +107,64 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Using <function>proc_open</function> to set the process priority to high</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Windows
+proc_nice(12);
+
+// Unix
+proc_nice(-20)
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+Array
+(
+    [some_option] => aeiou
+    [PWD] => /tmp
+    [SHLVL] => 1
+    [_] => /usr/local/bin/php
+)
+command returned 0
+]]>
+    </screen>
+   </example>
+  </para>
+
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>7.2.0</entry>
+       <entry>
+        This function is now available on Windows.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
  <refsect1 role="notes">
   &reftitle.notes;
   <note>
@@ -57,8 +172,18 @@
    <para>
     <function>proc_nice</function> will only exist if your system has 'nice'
     capabilities. 'nice' conforms to: SVr4, SVID EXT, AT&amp;T, X/OPEN, BSD
-    4.3. This means that <function>proc_nice</function> is not available
-    on Windows.
+    4.3.
+   </para>
+  </note>
+  <note>
+   <title>Windows only</title>
+   <para>
+    The values of <parameter>increment</parameter> tries to mimic the output of 
+    the <literal>wmic</literal>.
+   </para>
+   <para>
+    On Windows this function will only change the <emphasis>current</emphasis> process 
+    priority, even if PHP was compiled using thread safety.
    </para>
   </note>
  </refsect1>