[DOC-CVS] [doc-en] master: pcntl: Fix duplicate documentation for pcntl_getqos_class and pcntl_setqos_class (#5609)
[email protected] (KentarouTakeda via GitHub) Sun, 14 Jun 2026 08:23:07 +0000
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: KentarouTakeda (KentarouTakeda)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-06-14T10:23:05+02:00
Commit: https://github.com/php/doc-en/commit/28192e830f2c204570cc140c24341d07807df8bc
Raw diff: https://github.com/php/doc-en/commit/28192e830f2c204570cc140c24341d07807df8bc.diff
pcntl: Fix duplicate documentation for pcntl_getqos_class and pcntl_setqos_class (#5609)
* Fix duplicate documentation for pcntl_getqos_class and pcntl_setqos_class
These functions were each documented in two files sharing the same xml:id.
The build normalizes _ to - in file-entity names, so the hyphen-named files
(#5350) collided with the underscore-named ones (#5506) and were silently
dropped. Merge both versions into the hyphen-named files and remove the
underscore-named ones.
* Address review: use exceptionname for Error and simpara for parameters
Mark the thrown Error with <exceptionname>, use <simpara> for the
qos_class description, and drop the <para> wrapper around its <variablelist>.
Changed paths:
D reference/pcntl/functions/pcntl_getqos_class.xml
D reference/pcntl/functions/pcntl_setqos_class.xml
M reference/pcntl/functions/pcntl-getqos-class.xml
M reference/pcntl/functions/pcntl-setqos-class.xml
Diff:
diff --git a/reference/pcntl/functions/pcntl-getqos-class.xml b/reference/pcntl/functions/pcntl-getqos-class.xml
index 430a54f5d030..8ac56ebc737c 100644
--- a/reference/pcntl/functions/pcntl-getqos-class.xml
+++ b/reference/pcntl/functions/pcntl-getqos-class.xml
@@ -2,7 +2,7 @@
<refentry xml:id="function.pcntl-getqos-class" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>pcntl_getqos_class</refname>
- <refpurpose>Get the current Quality of Service class of the process</refpurpose>
+ <refpurpose>Get the QoS class of the current thread</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -12,10 +12,12 @@
<void/>
</methodsynopsis>
<simpara>
- Returns the current Quality of Service (<acronym>QoS</acronym>) class of the calling process.
- This function is only available on macOS, which uses <acronym>QoS</acronym> classes to
- manage energy efficiency and performance.
+ Retrieves the Quality of Service (<acronym>QoS</acronym>) class of the
+ current thread.
</simpara>
+ <note>
+ <simpara>This function is only available on Apple platforms.</simpara>
+ </note>
</refsect1>
<refsect1 role="parameters">
@@ -26,8 +28,16 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
- Returns a <classname>Pcntl\QosClass</classname> enum value representing
- the current <acronym>QoS</acronym> class.
+ Returns the current <acronym>QoS</acronym> class as a
+ <enumname>Pcntl\QosClass</enumname>.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws an <exceptionname>Error</exceptionname> if the underlying call to
+ <literal>pthread_get_qos_class_np()</literal> fails.
</simpara>
</refsect1>
@@ -35,6 +45,7 @@
&reftitle.seealso;
<simplelist>
<member><function>pcntl_setqos_class</function></member>
+ <member><enumname>Pcntl\QosClass</enumname></member>
</simplelist>
</refsect1>
diff --git a/reference/pcntl/functions/pcntl-setqos-class.xml b/reference/pcntl/functions/pcntl-setqos-class.xml
index 698d0d231f19..f314f15199a9 100644
--- a/reference/pcntl/functions/pcntl-setqos-class.xml
+++ b/reference/pcntl/functions/pcntl-setqos-class.xml
@@ -2,19 +2,18 @@
<refentry xml:id="function.pcntl-setqos-class" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>pcntl_setqos_class</refname>
- <refpurpose>Set the Quality of Service class of the process</refpurpose>
+ <refpurpose>Set the QoS class of the current thread</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>pcntl_setqos_class</methodname>
- <methodparam choice="opt"><type>Pcntl\QosClass</type><parameter>qos_class</parameter><initializer>Pcntl\QosClass::Default</initializer></methodparam>
+ <methodparam choice="opt"><type>Pcntl\QosClass</type><parameter>qos_class</parameter><initializer><constant>Pcntl\QosClass::Default</constant></initializer></methodparam>
</methodsynopsis>
<simpara>
- Sets the Quality of Service (<acronym>QoS</acronym>) class of the calling process.
- This function is only available on macOS, which uses <acronym>QoS</acronym> classes to
- manage energy efficiency and performance.
+ Sets the Quality of Service (<acronym>QoS</acronym>) class of the current
+ thread.
</simpara>
</refsect1>
@@ -25,19 +24,69 @@
<term><parameter>qos_class</parameter></term>
<listitem>
<simpara>
- The <acronym>QoS</acronym> class to set. Must be one of the
- <classname>Pcntl\QosClass</classname> enum values:
+ The Quality of Service class to assign to the current thread. The
+ operating system uses this as a hint to schedule CPU time, I/O priority,
+ and energy usage, with higher classes preempting lower ones. See
+ <enumname>Pcntl\QosClass</enumname> for the available cases.
</simpara>
- <simplelist>
- <member><literal>Pcntl\QosClass::UserInteractive</literal></member>
- <member><literal>Pcntl\QosClass::UserInitiated</literal></member>
- <member><literal>Pcntl\QosClass::Default</literal></member>
- <member><literal>Pcntl\QosClass::Utility</literal></member>
- <member><literal>Pcntl\QosClass::Background</literal></member>
- </simplelist>
+ <variablelist>
+ <varlistentry>
+ <term><constant>Pcntl\QosClass::UserInteractive</constant></term>
+ <listitem>
+ <simpara>
+ Highest priority. Intended for work that directly drives a user
+ interface and must complete virtually instantly to avoid perceived
+ delay, such as event handling or drawing.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>Pcntl\QosClass::UserInitiated</constant></term>
+ <listitem>
+ <simpara>
+ High priority, just below <constant>UserInteractive</constant>.
+ Intended for work the user has explicitly initiated and is actively
+ waiting on, expected to complete within a few seconds.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>Pcntl\QosClass::Default</constant></term>
+ <listitem>
+ <simpara>
+ Standard priority, used when no more specific class applies. Runs
+ after higher-priority work but ahead of <constant>Utility</constant>
+ and <constant>Background</constant>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>Pcntl\QosClass::Utility</constant></term>
+ <listitem>
+ <simpara>
+ Lower priority, intended for long-running work the user is aware of
+ but not actively waiting on, such as downloads, imports, or bulk
+ computation. Scheduled in an energy-efficient manner.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>Pcntl\QosClass::Background</constant></term>
+ <listitem>
+ <simpara>
+ Lowest priority, intended for work the user is not aware of, such as
+ prefetching, indexing, or maintenance. Heavily optimized for energy
+ efficiency and may be deferred when the system is under load.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
+ <note>
+ <simpara>This function is only available on Apple platforms.</simpara>
+ </note>
</refsect1>
<refsect1 role="returnvalues">
@@ -47,10 +96,19 @@
</simpara>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws an <exceptionname>Error</exceptionname> if the underlying call to
+ <literal>pthread_set_qos_class_self_np()</literal> fails.
+ </simpara>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>pcntl_getqos_class</function></member>
+ <member><enumname>Pcntl\QosClass</enumname></member>
</simplelist>
</refsect1>
diff --git a/reference/pcntl/functions/pcntl_getqos_class.xml b/reference/pcntl/functions/pcntl_getqos_class.xml
deleted file mode 100644
index 83d16d1424b6..000000000000
--- a/reference/pcntl/functions/pcntl_getqos_class.xml
+++ /dev/null
@@ -1,71 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<refentry xml:id="function.pcntl-getqos-class" xmlns="http://docbook.org/ns/docbook">
- <refnamediv>
- <refname>pcntl_getqos_class</refname>
- <refpurpose>Get the QoS class of the current thread</refpurpose>
- </refnamediv>
-
- <refsect1 role="description">
- &reftitle.description;
- <methodsynopsis>
- <type>Pcntl\QosClass</type><methodname>pcntl_getqos_class</methodname>
- <void/>
- </methodsynopsis>
- <simpara>
- Retrieve the QoS class.
- </simpara>
- <note>
- <simpara>This function is only available on Apple platforms.</simpara>
- </note>
- </refsect1>
-
- <refsect1 role="parameters">
- &reftitle.parameters;
- &no.function.parameters;
- </refsect1>
-
- <refsect1 role="returnvalues">
- &reftitle.returnvalues;
- <simpara>
- Returns the <enumname>Pcntl\QosClass</enumname>.
- </simpara>
- </refsect1>
-
- <refsect1 role="errors">
- &reftitle.errors;
- <simpara>
- Throws an <classname>Error</classname> if the underlying call to
- <literal>pthread_get_qos_class_np()</literal> fails.
- </simpara>
- </refsect1>
-
- <refsect1 role="seealso">
- &reftitle.seealso;
- <simplelist>
- <member><function>pcntl_setqos_class</function></member>
- <member><enumname>Pcntl\QosClass</enumname></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
--->
diff --git a/reference/pcntl/functions/pcntl_setqos_class.xml b/reference/pcntl/functions/pcntl_setqos_class.xml
deleted file mode 100644
index 113272c0305a..000000000000
--- a/reference/pcntl/functions/pcntl_setqos_class.xml
+++ /dev/null
@@ -1,137 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<refentry xml:id="function.pcntl-setqos-class" xmlns="http://docbook.org/ns/docbook">
- <refnamediv>
- <refname>pcntl_setqos_class</refname>
- <refpurpose>Set the QoS class of the current thread</refpurpose>
- </refnamediv>
-
- <refsect1 role="description">
- &reftitle.description;
- <methodsynopsis>
- <type>void</type><methodname>pcntl_setqos_class</methodname>
- <methodparam choice="opt"><type>Pcntl\QosClass</type><parameter>qos_class</parameter><initializer><constant>Pcntl\QosClass::Default</constant></initializer></methodparam>
- </methodsynopsis>
- <simpara>
- Set the QoS class.
- </simpara>
- </refsect1>
-
- <refsect1 role="parameters">
- &reftitle.parameters;
- <variablelist>
- <varlistentry>
- <term><parameter>qos_class</parameter></term>
- <listitem>
- <para>
- The Quality of Service class to assign to the current thread. The
- operating system uses this as a hint to schedule CPU time, I/O priority,
- and energy usage, with higher classes preempting lower ones. See
- <enumname>Pcntl\QosClass</enumname> for the available cases.
- </para>
- <para>
- <variablelist>
- <varlistentry>
- <term><constant>Pcntl\QosClass::UserInteractive</constant></term>
- <listitem>
- <simpara>
- Highest priority. Intended for work that directly drives a user
- interface and must complete virtually instantly to avoid perceived
- delay, such as event handling or drawing.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><constant>Pcntl\QosClass::UserInitiated</constant></term>
- <listitem>
- <simpara>
- High priority, just below <constant>UserInteractive</constant>.
- Intended for work the user has explicitly initiated and is actively
- waiting on, expected to complete within a few seconds.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><constant>Pcntl\QosClass::Default</constant></term>
- <listitem>
- <simpara>
- Standard priority, used when no more specific class applies. Runs
- after higher-priority work but ahead of <constant>Utility</constant>
- and <constant>Background</constant>.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><constant>Pcntl\QosClass::Utility</constant></term>
- <listitem>
- <simpara>
- Lower priority, intended for long-running work the user is aware of
- but not actively waiting on, such as downloads, imports, or bulk
- computation. Scheduled in an energy-efficient manner.
- </simpara>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><constant>Pcntl\QosClass::Background</constant></term>
- <listitem>
- <simpara>
- Lowest priority, intended for work the user is not aware of, such as
- prefetching, indexing, or maintenance. Heavily optimized for energy
- efficiency and may be deferred when the system is under load.
- </simpara>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <note>
- <simpara>This function is only available on Apple platforms.</simpara>
- </note>
- </refsect1>
-
- <refsect1 role="returnvalues">
- &reftitle.returnvalues;
- <simpara>
- &return.void;
- </simpara>
- </refsect1>
-
- <refsect1 role="errors">
- &reftitle.errors;
- <simpara>
- Throws an <classname>Error</classname> if the underlying call to
- <literal>pthread_set_qos_class_self_np()</literal> fails.
- </simpara>
- </refsect1>
-
- <refsect1 role="seealso">
- &reftitle.seealso;
- <simplelist>
- <member><function>pcntl_getqos_class</function></member>
- <member><enumname>Pcntl\QosClass</enumname></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
--->