Skip to content

Commit 22ff33a

Browse files
GirgiasGirgias
committed
pthreads : fix XML by converting para to simpara tags via script
1 parent 5173b09 commit 22ff33a

37 files changed

+301
-318
lines changed

‎reference/pthreads/book.xml‎

Lines changed: 34 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,19 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 12424df3c8140290d9e5c4912cbdb260aae055f4 Maintainer: yuanyuqiang Status: ready -->
3+
<!-- EN-Revision: bf92d8bd839301de7c837d20ab1dac6c14f83bbf Maintainer: yuanyuqiang Status: ready -->
44
<!-- Reviewed: no -->
5-
6-
<book xml:id="book.pthreads" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="book.pthreads">
76
<?phpdoc extension-membership="pecl" ?>
87
<title>pthreads</title>
98
<titleabbrev>pthreads</titleabbrev>
109

1110
<preface xml:id="intro.pthreads">
1211
&reftitle.intro;
13-
<para>
12+
<simpara>
1413
pthreads 是一组允许用户在 PHP 中使用多线程技术的面向对象的 API。
1514
它提供了创建多线程应用所需的全套工具。
1615
通过使用 Thread， Worker 以及 Threaded 对象，PHP 应用可以创建、读取、写入以及执行多线程应用，并可以在多个线程之间进行同步控制。
17-
</para>
16+
</simpara>
1817
<warning>
1918
<simpara>
2019
此扩展已被声明为停止维护状态。
@@ -26,53 +25,53 @@
2625
</simpara>
2726
</tip>
2827
<warning>
29-
<para>
28+
<simpara>
3029
不可以在 web 服务器环境中使用 pthreads 扩展，
3130
PHP 多线程开发仅限于命令行模式的应用。
32-
</para>
31+
</simpara>
3332
</warning>
3433
<warning>
35-
<para>
34+
<simpara>
3635
只能在 PHP 7.2+ 版本中使用 pthreads (v3) 扩展，
3736
在 PHP 7.0 和 7.1 版本中，ZTS 模式是不安全的。
38-
</para>
37+
</simpara>
3938
</warning>
40-
<para>
39+
<simpara>
4140
Threaded 对象：
4241
<classname>Threaded</classname> 对象提供支持 pthreads 操作的基本功能，包括同步方法以及其他对程序员很有帮助的接口。
43-
</para>
44-
<para>
42+
</simpara>
43+
<simpara>
4544
Thread 对象：
4645
通过继承 pthreads 中提供的 <classname>Thread</classname> 对象并实现 <literal>run</literal> 方法，用户可以创建自己的 Thread 对象。
4746
只要线程上下文中持有某个 Thread 对象的引用，就可以读/写该对象的属性，也可以调用该对象的公有（public）或者受保护（protected）的方法。
4847
当在创建 Thread 对象的上下文中调用该对象的 <methodname>Thread::start</methodname> 方法时，pthreads 扩展会在另外的独立线程中执行该对象的 run 方法。
4948
仅有创建 Thread 对象的线程/进程方可开始（start）或者加入（join）这个 Thread 对象。
50-
</para>
51-
<para>
49+
</simpara>
50+
<simpara>
5251
Worker 对象：
5352
<classname>Worker</classname> 是有状态的线程对象，它在线程开始（通过调用 <methodname>Thread::start</methodname> 方法）之后就可用，
5453
除非代码中显式地关闭线程（通过调用 <methodname>Worker::shutdown</methodname> 方法），
5554
否则该对象在线程对象超出作用范围之后才会失效。
5655
持有 Worker 对象引用的线程上下文可以向 Worker 中入栈（通过调用 <methodname>Worker::stack</methodname> 方法）其他线程对象，Worker 对象将在独立线程中执行入栈对象的代码。
5756
Woker 对象的 <literal>run</literal> 方法会在它的栈中入栈对象之前执行，这样就可以进行一些必需的资源初始化工作。
58-
</para>
59-
<para>
57+
</simpara>
58+
<simpara>
6059
Pool 对象：
6160
<classname>Pool</classname> 对象是 Worker 线程对象池，可以用来在多个 Worker 对象之间分发 <classname>Threaded</classname> 对象，
6261
这是最易用且高效的多线程编程方式。
63-
</para>
62+
</simpara>
6463
<caution>
65-
<para>
64+
<simpara>
6665
<classname>Pool</classname> 是标准的 PHP 对象，它并没有继承 <classname>Threaded</classname> 类，所以不可以在多个线程上下文中共享同一个 Pool 对象。
67-
</para>
66+
</simpara>
6867
</caution>
69-
<para>
68+
<simpara>
7069
<classname>Volatile</classname> 类是在 pthreads v3 中新增加的，
7170
用来表示可变的 <classname>Threaded</classname> 类中的
7271
<classname>Threaded</classname> 属性（默认情况下是不可变的）。
7372
它也可以被用来在 <classname>Threaded</classname> 上下文中存储数组。
74-
</para>
75-
<para>
73+
</simpara>
74+
<simpara>
7675
线程间同步：
7776
由 pthreads 扩展创建的所有对象拥有内置的线程间同步机制，
7877
和 Java 语言很类似，
@@ -83,45 +82,45 @@
8382
等待另外一个线程上下文调用同一个对象的
8483
<methodname>Threaded::notify</methodname> 方法。
8584
为 PHP <classname>Threaded</classname> 对象提供了强有力的线程间同步控制机制。
86-
</para>
85+
</simpara>
8786
<caution>
88-
<para>
87+
<simpara>
8988
应用中会用在多线程场景中的对象都应该从 <classname>Threaded</classname> 类继承。
90-
</para>
89+
</simpara>
9190
</caution>
92-
<para>
91+
<simpara>
9392
数据存储：
9493
一般来说，任何可以序列化的数据类型都可以作为 Threaded 对象的属性，它可以从持有该对象引用的任何线程上下文读/写。
9594
并不是所有的数据都采用序列化方式存储，比如基本类型就是以其真实形态存储的。
9695
对于不是 Threaded 派生的对象，例如复杂类型、数组以及对象等，都是序列化存储的，可以从持有 Threaded 对象引用的任何线程上下文中读取和写入，
9796
区别就在于对于 Threaed 的派生对象，设置它的成员变量的过程是在独立线程上下文中执行的。
9897
对于 Threaded 派生对象，在同一时间，不同的线程上下文都可以从该对象中读取到同样的数据。
99-
</para>
100-
<para>
98+
</simpara>
99+
<simpara>
101100
静态成员：
102101
当创建新的线程上下文（Thread 或 Worker 对象）的时候，静态成员会被拷贝到新的上下文中。出于安全考虑，资源类型以及包含内部状态的对象类型的静态成员会被置空。
103102
实际上这个特性实现了类似线程本地存储的功能。举例说明，假设某个类拥有包含数据库连接信息以及数据库连接对象静态成员，
104103
那么当新的线程上下文启动的时候，仅有数据库连接信息会被复制到新上下文中，而数据库连接对象并不会被复制。
105104
所以，需要在新的上下文中根据复制过来的数据库连接基本信息来初始化数据库连接对象，新创建的数据库连接对象是独立的，
106105
不影响在原上下文中的数据库连接对象。
107-
</para>
106+
</simpara>
108107
<caution>
109-
<para>
108+
<simpara>
110109
当使用 print_r, var_dump 或者其他函数来进行对象调试的时候，是没有递归保护机制的。
111-
</para>
110+
</simpara>
112111
</caution>
113112
<note>
114-
<para>
113+
<simpara>
115114
资源类型：
116115
PHP 中很多使用到 Resource 资源类型的扩展或函数并未针对多线程场景进行特殊设计，也就是说，虽然 pthreads 扩展提供了
117116
在多个线程上下文中共享资源类型变量的能力，但是通常来说，你应该把它们视为非线程安全的。
118117
所以，如果要在多个线程上下文中共享资源类型的变量，你应该特别谨慎对待。
119-
</para>
118+
</simpara>
120119
</note>
121120
<caution>
122-
<para>
121+
<simpara>
123122
为了提供一个稳定的运行环境，pthreads 扩展在执行过程中会有一些必需的额外限制。
124-
</para>
123+
</simpara>
125124
</caution>
126125
</preface>
127126

@@ -134,7 +133,6 @@
134133
&reference.pthreads.pool;
135134
&reference.pthreads.volatile;
136135
</book>
137-
138136
<!-- Keep this comment at the end of the file
139137
Local variables:
140138
mode: sgml

‎reference/pthreads/configure.xml‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,25 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 637c29c81a694e3e9f1d6293bd7af230050e5499 Maintainer: yuanyuqiang Status: ready -->
3+
<!-- EN-Revision: bf92d8bd839301de7c837d20ab1dac6c14f83bbf Maintainer: yuanyuqiang Status: ready -->
44
<!-- Reviewed: no -->
5-
6-
<section xml:id="pthreads.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="pthreads.installation">
76
&reftitle.install;
87

9-
<para>
8+
<simpara>
109
使用 <option role="configure">--enable-maintainer-zts</option> 选项编译 PHP。
11-
</para>
10+
</simpara>
1211

13-
<para>
12+
<simpara>
1413
Windows 用户需要在 &php.ini; 中配置 <filename>php_pthreads.dll</filename> 扩展。
15-
</para>
16-
14+
</simpara>
15+
1716
<note>
18-
<para>
17+
<simpara>
1918
Windows 用户同时需要将 <filename>pthreadVC2.dll</filename> （包含在 pthreads 发行包中）加入到 <envar>PATH</envar> 环境变量中。
20-
</para>
19+
</simpara>
2120
</note>
2221

2322
</section>
24-
25-
2623
<!-- Keep this comment at the end of the file
2724
Local variables:
2825
mode: sgml

‎reference/pthreads/pool.xml‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: c44e9cb68b9b65771f9c45db2c07a06c63d71359 Maintainer: yuanyuqiang Status: ready -->
3+
<!-- EN-Revision: bf92d8bd839301de7c837d20ab1dac6c14f83bbf Maintainer: yuanyuqiang Status: ready -->
44
<!-- CREDITS: mowangjuanzi -->
5-
<reference xml:id="class.pool" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
5+
<reference xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="class.pool" role="class">
66

77
<title>Pool 类</title>
88
<titleabbrev>Pool</titleabbrev>
@@ -12,12 +12,12 @@
1212
<!-- {{{ Pool intro -->
1313
<section xml:id="pool.intro">
1414
&reftitle.intro;
15-
<para>
15+
<simpara>
1616
Pool 对象是多个 Worker 对象的容器，同时也是它们的控制器。
17-
</para>
18-
<para>
17+
</simpara>
18+
<simpara>
1919
线程池是对 Worker 功能的高层抽象，包括按照 pthreads 需要的方式来管理应用的功能。
20-
</para>
20+
</simpara>
2121
</section>
2222
<!-- }}} -->
2323

@@ -76,31 +76,31 @@
7676
<varlistentry xml:id="pool.props.size">
7777
<term><varname>size</varname></term>
7878
<listitem>
79-
<para>Pool 对象可容纳的 Worker 对象的最大数量</para>
79+
<simpara>Pool 对象可容纳的 Worker 对象的最大数量</simpara>
8080
</listitem>
8181
</varlistentry>
8282
<varlistentry xml:id="pool.props.class">
8383
<term><varname>class</varname></term>
8484
<listitem>
85-
<para>Worker 的类</para>
85+
<simpara>Worker 的类</simpara>
8686
</listitem>
8787
</varlistentry>
8888
<varlistentry xml:id="pool.props.workers">
8989
<term><varname>workers</varname></term>
9090
<listitem>
91-
<para>指向 Worker 对象的引用</para>
91+
<simpara>指向 Worker 对象的引用</simpara>
9292
</listitem>
9393
</varlistentry>
9494
<varlistentry xml:id="pool.props.ctor">
9595
<term><varname>ctor</varname></term>
9696
<listitem>
97-
<para>构造新的 Worker 对象时所需的参数</para>
97+
<simpara>构造新的 Worker 对象时所需的参数</simpara>
9898
</listitem>
9999
</varlistentry>
100100
<varlistentry xml:id="pool.props.last">
101101
<term><varname>last</varname></term>
102102
<listitem>
103-
<para>最后使用的 Worker 对象在池中的位置偏移量</para>
103+
<simpara>最后使用的 Worker 对象在池中的位置偏移量</simpara>
104104
</listitem>
105105
</varlistentry>
106106
</variablelist>
@@ -113,7 +113,6 @@
113113
&reference.pthreads.entities.pool;
114114

115115
</reference>
116-
117116
<!-- Keep this comment at the end of the file
118117
Local variables:
119118
mode: sgml

‎reference/pthreads/pool/collect.xml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 1f3517218031b663f773061056a873cf2a03f32d Maintainer: yuanyuqiang Status: ready -->
3+
<!-- EN-Revision: bf92d8bd839301de7c837d20ab1dac6c14f83bbf Maintainer: yuanyuqiang Status: ready -->
44
<!-- CREDITS: Luffy -->
55
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="pool.collect">
66
<refnamediv>
@@ -14,9 +14,9 @@
1414
<modifier>public</modifier> <type>int</type><methodname>Pool::collect</methodname>
1515
<methodparam choice="opt"><type>Callable</type><parameter>collector</parameter></methodparam>
1616
</methodsynopsis>
17-
<para>
17+
<simpara>
1818
对于视为垃圾的引用，使用给定的垃圾收集器进行收集
19-
</para>
19+
</simpara>
2020
</refsect1>
2121

2222
<refsect1 role="parameters">
@@ -25,20 +25,20 @@
2525
<varlistentry>
2626
<term><parameter>collector</parameter></term>
2727
<listitem>
28-
<para>
28+
<simpara>
2929
垃圾收集器，它返回一个布尔值表示这个任务是否可以被进行垃圾收集。
3030
仅在极少的情况下需要一个自定义的垃圾收集器。
31-
</para>
31+
</simpara>
3232
</listitem>
3333
</varlistentry>
3434
</variablelist>
3535
</refsect1>
3636

3737
<refsect1 role="returnvalues">
3838
&reftitle.returnvalues;
39-
<para>
39+
<simpara>
4040
池中剩余的待收集的任务数量。
41-
</para>
41+
</simpara>
4242
</refsect1>
4343

4444
<refsect1 role="changelog">

‎reference/pthreads/pool/construct.xml‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 1f3517218031b663f773061056a873cf2a03f32d Maintainer: yuanyuqiang Status: ready -->
3+
<!-- EN-Revision: bf92d8bd839301de7c837d20ab1dac6c14f83bbf Maintainer: yuanyuqiang Status: ready -->
44
<!-- CREDITS: mowangjuanzi -->
55
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="pool.construct">
66
<refnamediv>
@@ -16,11 +16,11 @@
1616
<methodparam choice="opt"><type>string</type><parameter>class</parameter></methodparam>
1717
<methodparam choice="opt"><type>array</type><parameter>ctor</parameter></methodparam>
1818
</constructorsynopsis>
19-
<para>
19+
<simpara>
2020
创建新的 Worker 对象池，但是所对应的线程是延迟创建的的，也就是说，
2121
直到需要执行任务的时候
2222
才会创建对应的线程。
23-
</para>
23+
</simpara>
2424
</refsect1>
2525

2626
<refsect1 role="parameters">
@@ -29,26 +29,26 @@
2929
<varlistentry>
3030
<term><parameter>size</parameter></term>
3131
<listitem>
32-
<para>
32+
<simpara>
3333
此 Pool 对象可创建的 Worker 对象的最大数量
34-
</para>
34+
</simpara>
3535
</listitem>
3636
</varlistentry>
3737
<varlistentry>
3838
<term><parameter>class</parameter></term>
3939
<listitem>
40-
<para>
40+
<simpara>
4141
新创建的 Worker 对象的类。
4242
如果不指定类，那么会使用默认的 <classname>Worker</classname> 类。
43-
</para>
43+
</simpara>
4444
</listitem>
4545
</varlistentry>
4646
<varlistentry>
4747
<term><parameter>ctor</parameter></term>
4848
<listitem>
49-
<para>
49+
<simpara>
5050
创建 Worker 对象时所用到的参数，以数组方式传入
51-
</para>
51+
</simpara>
5252
</listitem>
5353
</varlistentry>
5454
</variablelist>

0 commit comments

Comments
 (0)