[boost-doc-zh] r370 committed - 翻译 ref, signals, signals2 库的xml/qbk文件
- From: boost-doc-zh@xxxxxxxxxxxxxx
- To: boost-doc-zh-notify@xxxxxxxxxxxxx
- Date: Sat, 23 Jan 2010 14:27:39 +0000
Revision: 370
Author: alai04
Date: Sat Jan 23 06:27:10 2010
Log: 翻译 ref, signals, signals2 库的xml/qbk文件
http://code.google.com/p/boost-doc-zh/source/detail?r=370
Modified:
/trunk/libs/bind/doc/ref.xml
/trunk/libs/signals/doc/design.xml
/trunk/libs/signals/doc/faq.xml
/trunk/libs/signals/doc/introduction.xml
/trunk/libs/signals/doc/rationale.xml
/trunk/libs/signals/doc/tests.xml
/trunk/libs/signals/doc/tutorial.xml
/trunk/libs/signals2/doc/examples.xml
/trunk/libs/signals2/doc/faq.xml
/trunk/libs/signals2/doc/introduction.xml
/trunk/libs/signals2/doc/porting.xml
/trunk/libs/signals2/doc/rationale.xml
/trunk/libs/signals2/doc/tests.xml
/trunk/libs/signals2/doc/thread_safety.xml
/trunk/libs/signals2/doc/tutorial.xml
=======================================
--- /trunk/libs/bind/doc/ref.xml Fri Sep 4 04:09:20 2009
+++ /trunk/libs/bind/doc/ref.xml Sat Jan 23 06:27:10 2010
@@ -51,7 +51,7 @@
<title>Boost.Ref</title>
<section id="ref.intro">
- <title>Introduction</title>
+ <title>Introduction 简介</title>
<using-namespace name="boost"/>
@@ -69,43 +69,66 @@
two traits classes
<code><classname>boost::is_reference_wrapper<T></classname></code>
and
-
<code><classname>boost::unwrap_reference<T></classname></code>.</para>
+
<code><classname>boost::unwrap_reference<T></classname></code>.<sbr/>
+ Ref 库是一个小型库，对于把引用传递给函数模板（算法）非常有用，这些函数模
板（算法）通常都接收它们的参数的拷贝。
+ 它定义了类模板
<code><classname>boost::reference_wrapper<T></classname></code>，
+ 两个返回 <code>boost::reference_wrapper<T></code> 实例的函数
<code><functionname>boost::ref</functionname></code>
+ 和 <code><functionname>boost::cref</functionname></code>，一个
<code><functionname>boost::unwrap_ref</functionname></code>
+ 用以解开一个 <code>boost::reference_wrapper<T></code> 的外包装或返
回一个至任意其它类型的对象的引用，
+ 以及两个 traits classes（特征类
）<code><classname>boost::is_reference_wrapper<T></classname></code>
+ 和 <code><classname>boost::unwrap_reference<T></classname></code>。
</para>
<para>The purpose of
<code>boost::reference_wrapper<T></code> is to
contain a reference to an object of type T. It is primarily used to
"feed" references to function templates (algorithms) that take their
- parameter by value.</para>
+ parameter by value.<sbr/>
+ <code>boost::reference_wrapper<T></code> 的目的是容纳一个引向类型
为 T 的对象的引用。
+ 它主要用于把引用“喂”给那些以传值方式持有它们的参数的函数模板（算法）。
</para>
<para>To support this usage,
<code>boost::reference_wrapper<T></code> provides an implicit
conversion to <code>T&</code>. This usually allows the function
- templates to work on references unmodified.</para>
+ templates to work on references unmodified.<sbr/>
+ 为了支持这个用法，<code>boost::reference_wrapper<T></code> 提供一个
到 <code>T&</code> 的隐式转换。
+ 这通常允许函数模板可以不加改变地工作在引用上。</para>
<para><code>boost::reference_wrapper<T></code> is
both CopyConstructible and Assignable (ordinary references are not
- Assignable).</para>
+ Assignable).<sbr/>
+ <code>boost::reference_wrapper<T></code> 是可拷贝构造的，也是可赋值
的
+ （普通引用不是可赋值的）。</para>
<para>The expression <code>boost::ref(x)</code>
returns a
<code>boost::reference_wrapper<X>(x)</code> where X
is the type of x. Similarly,
<code>boost::cref(x)</code> returns a
- <code>boost::reference_wrapper<X const>(x)</code>.</para>
+ <code>boost::reference_wrapper<X const>(x)</code>.<sbr/>
+ 表达式 <code>boost::ref(x)</code> 返回一个
<code>boost::reference_wrapper<X>(x)</code>，X 是 x 的类型。
+ 类似地，<code>boost::cref(x)</code> 返回一个
<code>boost::reference_wrapper<X const>(x)</code>。</para>
<para>The expression <code>boost::unwrap_ref(x)</code>
returns a
<code>boost::unwrap_reference<X>::type&</code> where X
- is the type of x.</para>
+ is the type of x.<sbr/>
+ 表达式 <code>boost::unwrap_ref(x)</code> 返回一个
<code>boost::unwrap_reference<X>::type&</code>，
+ 其中 X 为 x 的类型。</para>
<para>The expression
<code>boost::is_reference_wrapper<T>::value</code>
is true if T is a <code>reference_wrapper</code>, and
- false otherwise.</para>
+ false otherwise.<sbr/>
+ 如果 T 是一个 <code>reference_wrapper</code>，则表达式
+ <code>boost::is_reference_wrapper<T>::value</code> 的值为 true，
+ 否则为 false。</para>
<para>The type-expression
<code>boost::unwrap_reference<T>::type</code> is T::type if T
- is a <code>reference_wrapper</code>, T otherwise.</para>
+ is a <code>reference_wrapper</code>, T otherwise.<sbr/>
+ 如果 T 是一个 <code>reference_wrapper</code>，则类型表达式
+ <code>boost::unwrap_reference<T>::type</code> 的值为 T::type，
+ 否则为 T。</para>
</section>
<library-reference>
@@ -117,7 +140,8 @@
</template>
<purpose>
Contains a reference to an object of type
- <computeroutput>T</computeroutput>.
+ <computeroutput>T</computeroutput>. <sbr/>
+ 容纳一个引向类型为 <computeroutput>T</computeroutput> 的对象的引
用。
</purpose>
<description>
@@ -127,7 +151,10 @@
an implicit conversion to
<computeroutput>T&</computeroutput>, which usually allows
the function templates to work on references
- unmodified.</para>
+ unmodified.<sbr/>
+
<computeroutput><classname>reference_wrapper</classname></computeroutput> 主
要用于把引用
+ “喂”给那些以传值方式持有它们的参数的函数模板（算法）。它提供一个到
<computeroutput>T&</computeroutput> 的隐式转换，
+ 这通常允许函数模板可以不加改变地工作在引用上。</para>
</description>
<typedef name="type"><type>T</type></typedef>
@@ -140,28 +167,37 @@
<effects><simpara>Constructs a
<computeroutput><classname>reference_wrapper</classname></computeroutput>
object that stores a reference to
- <computeroutput>t</computeroutput>.</simpara></effects>
-
- <throws><simpara>Does not throw.</simpara></throws>
+ <computeroutput>t</computeroutput>.<sbr/>
+ 构造一个存储引向 <computeroutput>t</computeroutput> 的引用的
+
<computeroutput><classname>reference_wrapper</classname></computeroutput> 对
象。</simpara></effects>
+
+ <throws><simpara>Does not throw.<sbr/>
+ 不会抛出异常。</simpara></throws>
</constructor>
<method-group name="access">
<method name="conversion-operator" cv="const">
<type>T&</type>
- <returns><simpara>The stored reference.</simpara></returns>
- <throws><simpara>Does not throw.</simpara></throws>
+ <returns><simpara>The stored reference.<sbr/>
+ 所存储的引用。</simpara></returns>
+ <throws><simpara>Does not throw.<sbr/>
+ 不会抛出异常。</simpara></throws>
</method>
<method name="get" cv="const">
<type>T&</type>
- <returns><simpara>The stored reference.</simpara></returns>
- <throws><simpara>Does not throw.</simpara></throws>
+ <returns><simpara>The stored reference.<sbr/>
+ 所存储的引用。</simpara></returns>
+ <throws><simpara>Does not throw.<sbr/>
+ 不会抛出异常。</simpara></throws>
</method>
<method name="get_pointer" cv="const">
<type>T*</type>
- <returns><simpara>A pointer to the object referenced by the
stored reference.</simpara></returns>
- <throws><simpara>Does not throw.</simpara></throws>
+ <returns><simpara>A pointer to the object referenced by the
stored reference.<sbr/>
+ 一个指向所存储的引用引向的对象的指针。</simpara></returns>
+ <throws><simpara>Does not throw.<sbr/>
+ 不会抛出异常。</simpara></throws>
</method>
</method-group>
@@ -174,7 +210,8 @@
<returns><simpara><computeroutput><classname>reference_wrapper</classname><T>(t)</computeroutput></simpara></returns>
- <throws><simpara>Does not throw.</simpara></throws>
+ <throws><simpara>Does not throw.<sbr/>
+ 不会抛出异常。</simpara></throws>
</function>
<function name="cref">
@@ -185,7 +222,8 @@
<returns><simpara><computeroutput><classname>reference_wrapper</classname><T
const>(t)</computeroutput></simpara></returns>
- <throws><simpara>Does not throw.</simpara></throws>
+ <throws><simpara>Does not throw.<sbr/>
+ 不会抛出异常。</simpara></throws>
</function>
</free-function-group>
@@ -198,7 +236,8 @@
<returns><simpara><computeroutput><classname>unwrap_reference</classname><T>::type&(t)</computeroutput></simpara></returns>
- <throws><simpara>Does not throw.</simpara></throws>
+ <throws><simpara>Does not throw.<sbr/>
+ 不会抛出异常。</simpara></throws>
</function>
</free-function-group>
</class>
@@ -208,13 +247,19 @@
<template-type-parameter name="T"/>
</template>
- <purpose>Determine if a type <computeroutput>T</computeroutput> is
an instantiation of
<computeroutput><classname>reference_wrapper</classname></computeroutput>.</purpose>
+ <purpose>Determine if a type <computeroutput>T</computeroutput> is
an instantiation of
<computeroutput><classname>reference_wrapper</classname></computeroutput>.<sbr/>
+ 判定类型 <computeroutput>T</computeroutput> 是否是一个
+
<computeroutput><classname>reference_wrapper</classname></computeroutput> 实
例。</purpose>
<description>
<para>The <computeroutput>value</computeroutput> static
constant will be <computeroutput>true</computeroutput> iff the
type <computeroutput>T</computeroutput> is a specialization of
-
<computeroutput><classname>reference_wrapper</classname></computeroutput>.</para>
+
<computeroutput><classname>reference_wrapper</classname></computeroutput>.<sbr/>
+ 如果类型 <computeroutput>T</computeroutput> 是
+
<computeroutput><classname>reference_wrapper</classname></computeroutput>
+ 的特化，<computeroutput>value</computeroutput> 静态地持续性地为
+ <computeroutput>true</computeroutput>。</para>
</description>
<static-constant name="value">
@@ -228,14 +273,19 @@
<template-type-parameter name="T"/>
</template>
- <purpose>Find the type in a
<computeroutput><classname>reference_wrapper</classname></computeroutput>.</purpose>
+ <purpose>Find the type in a
<computeroutput><classname>reference_wrapper</classname></computeroutput>.<sbr/>
+ 在一个
<computeroutput><classname>reference_wrapper</classname></computeroutput> 中
寻找类型。</purpose>
<description>
<para>The typedef <computeroutput>type</computeroutput> is
<computeroutput>T::type</computeroutput> if
<computeroutput>T</computeroutput> is a
<computeroutput><classname>reference_wrapper</classname></computeroutput>,
- <computeroutput>T</computeroutput> otherwise.</para>
+ <computeroutput>T</computeroutput> otherwise.<sbr/>
+ 如果 <computeroutput>T</computeroutput> 是一个
+
<computeroutput><classname>reference_wrapper</classname></computeroutput>，
+ 则 typedef <computeroutput>type</computeroutput> 为
<computeroutput>T::type</computeroutput>，
+ 否则为 <computeroutput>T</computeroutput>。</para>
</description>
<typedef
name="type"><type><emphasis>unspecified</emphasis></type></typedef>
@@ -245,7 +295,7 @@
</library-reference>
<section id="ref.ack">
- <title>Acknowledgements</title>
+ <title>Acknowledgements 鸣谢</title>
<using-namespace name="boost"/>
@@ -256,7 +306,11 @@
Dave Abrahams contributed
<classname>is_reference_wrapper</classname> and
<classname>unwrap_reference</classname>. Frank Mori Hess and Ronald
- Garcia contributed <functionname>boost::unwrap_ref</functionname></para>
+ Garcia contributed <functionname>boost::unwrap_ref</functionname><sbr/>
+ <functionname>ref</functionname> 和 <functionname>cref</functionname> 最
初曾经是 Jaakko Järvi 做的
+ <libraryname>Tuple</libraryname> 库的一部分。他们被 Peter Dimov “提拔到
boost::status 中”，因为它们有更广泛的用途。
+ Douglas Gregor 和 Dave Abrahams 贡献了
<classname>is_reference_wrapper</classname> 和
<classname>unwrap_reference</classname>。
+ Frank Mori Hess 和 Ronald Garcia 贡献了
<functionname>boost::unwrap_ref</functionname></para>
</section>
</library>
=======================================
--- /trunk/libs/signals/doc/design.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/signals/doc/design.xml Sat Jan 23 06:27:10 2010
@@ -2,13 +2,13 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section last-revision="$Date: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov
2007) $">
- <title>Design Overview</title>
+ <title>Design Overview 设计概览</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals"/>
<section>
- <title>Type Erasure</title>
+ <title>Type Erasure 类型删除</title>
<para>"Type erasure", where static type information is eliminated
by the use of dynamically dispatched interfaces, is used
@@ -19,7 +19,12 @@
their associated connections. However, instantiating this map for
every token type, and perhaps within each translation unit (for
some popular template instantiation strategies) increase compile
- time overhead and space overhead.</para>
+ time overhead and space overhead.<sbr/>
+ “类型删除”是通过动态分派的接口消除静态类型信息，它在 Boost.Signals 库中
广泛使用，
+ 以减少模板实例化所产生的代码总数。每个信号必须管理一序列插槽及其相关的
连接，
+ 还有一个 <code>std::map</code>，从编组标识符映射到它们相关的连接。然
而，
+ 为每个标记类型实例化该映射，并且可能在每个翻译单元中都要实例化
+ （因为某些流行的模板实例化策略），增加了编译的时间开销和空间开销。
</para>
<para> To combat this so-called "template bloat", we use
Boost.Function and Boost.Any to store unknown types and
@@ -32,11 +37,16 @@
actual <code><classname>signalN</classname></code> class templates
deal only with code that will change depending on the number of
arguments or which is inherently template-dependent (such as
- connection).</para>
+ connection).<sbr/>
+ 为了防止这种所谓的“模板膨胀”， 我们使用了 Boost.Function 和 Boost.Any
来保存未知的类型和操作。
+ 然后，处理插槽链表和插槽标识符到连接的映射的所有代码都移到了
<code><classname>signal_base</classname></code> 类中，
+ 它专门处理 <code>any</code> 和
<code><classname>function</classname></code> 对象，使用著名的 pimpl 惯用法隐
藏了实际的实现。
+ 实际的 <code><classname>signalN</classname></code> 类模板仅处理根据参数
个数而变化的代码，
+ 或本来就是模板相关的代码（如连接）。</para>
</section>
<section>
- <title><code>connection</code> class</title>
+ <title><code>connection</code> class <code>connection</code>类</title>
<para> The <code><classname>connection</classname></code> class is
central to the behavior of the Boost.Signals library. It is the
@@ -45,7 +55,11 @@
specific, the <code><classname>connection</classname></code> class
itself is merely a thin wrapper over a
<code><classname>shared_ptr</classname></code> to a
- <code>basic_connection</code> object.</para>
+ <code>basic_connection</code> object.<sbr/>
+ <code><classname>connection</classname></code> 类是 Boost.Signals 库行
为的中心。
+ 它是 Boost.Signals 系统中的唯一的实体，知道与特定连接相关联的所有对象。
+ 确切地说，<code><classname>connection</classname></code> 类本身只是指向
+ <code>basic_connection</code> 对象的
<code><classname>shared_ptr</classname></code> 之上的薄封装。</para>
<para> <code><classname>connection</classname></code> objects are
stored by all participants in the Signals system: each
@@ -59,11 +73,17 @@
to slots is based on the key value in a
<code><classname>std::multimap</classname></code> (the stored data
in the <code><classname>std::multimap</classname></code> is the
- slot pair).</para>
+ slot pair).<sbr/>
+ <code><classname>connection</classname></code> 对象被信号系统中所有参与
者保存：
+ 每个 <code><classname>trackable</classname></code> 对象包含一个
<code><classname>connection</classname></code> 对象链表，
+ 该链表描述了包含这个可跟踪对象的所有连接；同样，所有信号包含一组定义插
槽的配对（pair）。
+ 该配对由插槽函数对象（一般是 Boost.Function 对象）和
<code><classname>connection</classname></code> 对象
+ （析构时会断开）所组成。最后，从插槽组到插槽的映射是基于
<code><classname>std::multimap</classname></code> 中的键值
+ （保存于 <code><classname>std::multimap</classname></code> 中的数据即插
槽配对）。 </para>
</section>
<section>
- <title>Slot Call Iterator</title>
+ <title>Slot Call Iterator 插槽调用迭代器</title>
<para> The slot call iterator is conceptually a stack of iterator
adaptors that modify the behavior of the underlying iterator
@@ -72,68 +92,90 @@
only a conceptual model: the implementation collapses all these
layers into a single iterator adaptor because several popular
compilers failed to compile the implementation of the conceptual
- model.</para>
+ model.<sbr/>
+ 插槽调用迭代器概念上是一堆迭代器适配器， 它们会更改底层插槽链表迭代器的
行为。
+ 下表描述了每个迭代器所要求的类型和行为。注意这仅仅是个概念模型：
+ 实现时所有这些层次合并为单个迭代器适配器，因为有些流行的编译器无法编译
概念模型的实现。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Iterator Adaptor</entry>
- <entry>Purpose</entry>
+ <entry>Iterator Adaptor 迭代器适配器</entry>
+ <entry>Purpose 目的</entry>
</row>
</thead>
<tbody>
<row>
- <entry><para>Slot List Iterator</para></entry>
+ <entry><para>Slot List Iterator<sbr/>
+ 插槽链表迭代器</para></entry>
<entry><para>An iterator through the list of slots
connected to a signal. The <code>value_type</code> of this
iterator will be
<code><classname>std::pair</classname><any,
connection></code>, where the
<code><classname>any</classname></code> contains an
- instance of the slot function type.</para></entry>
+ instance of the slot function type.<sbr/>
+ 连接到信号的插槽链表的迭代器。该迭代器的
<code>value_type</code> 是
+ <code><classname>std::pair</classname><any,
connection></code>，
+ 其中 <code><classname>any</classname></code> 包含插槽函数类型的
一个实例。</para></entry>
</row>
<row>
- <entry><para>Filter Iterator Adaptor</para></entry>
+ <entry><para>Filter Iterator Adaptor<sbr/>
+ 过滤迭代器适配器</para></entry>
<entry><para>This filtering iterator adaptor filters out
slots that have been disconnected, so we never see a
- disconnected slot in later stages.</para></entry>
+ disconnected slot in later stages.<sbr/>
+ 这个过滤迭代器适配器过滤掉已断开的插槽，因此我们在后面的阶段不
会见到已断开的插槽。</para></entry>
</row>
<row>
- <entry><para>Projection Iterator Adaptor</para></entry>
+ <entry><para>Projection Iterator Adaptor 投影迭代器适配器
</para></entry>
<entry><para>The projection iterator adaptor returns a
reference to the first member of the pair that constitutes
a connected slot (e.g., just the
<code><classname>boost::any</classname></code> object that
- holds the slot function).</para></entry>
+ holds the slot function).<sbr/>
+ 投影迭代器适配器返回一个引用，指向构成一个已连接插槽的 pair 的
第一个成员
+ （例如保存插槽函数的
<code><classname>boost::any</classname></code> 对象）。</para></entry>
</row>
<row>
- <entry><para>Transform Iterator Adaptor</para></entry>
+ <entry><para>Transform Iterator Adaptor 转换迭代器适配器
</para></entry>
<entry><para>This transform iterator adaptor performs an
<code><functionname>any_cast</functionname></code> to
extract a reference to the slot function with the
- appropriate slot function type.</para></entry>
+ appropriate slot function type.<sbr/>
+ 这个转换迭代器适配器执行
<code><functionname>any_cast</functionname></code>，
+ 以提取一个插槽函数的引用， 并具有适当的插槽函数类型。
</para></entry>
</row>
<row>
- <entry><para>Transform Iterator Adaptor</para></entry>
+ <entry><para>Transform Iterator Adaptor<sbr/>
+ 转换迭代器适配器</para></entry>
<entry><para>This transform iterator adaptor calls the
function object returned by dereferencing the underlying
iterator with the set of arguments given to the signal
itself, and returns the result of that slot
- call.</para></entry>
+ call.<sbr/>
+ 这个转换迭代器适配器调用底层迭代器解引用所返回的函数对象，
+ 参数为输入信号本身的那组参数，并返回那个插槽调用的结果。
</para></entry>
</row>
<row>
- <entry><para>Input Caching Iterator Adaptor</para></entry>
+ <entry><para>Input Caching Iterator Adaptor<sbr/>
+ 输入缓存迭代器适配器</para></entry>
<entry><para>This iterator adaptor caches the result of
dereferencing the underlying iterator. Therefore,
dereferencing this iterator multiple times will only
result in the underlying iterator being dereferenced once;
thus, a slot can only be called once but its result can be
- used multiple times.</para></entry>
+ used multiple times.<sbr/>
+ 这个迭代器适配器缓存底层迭代器解引用的结果。 因此，
+ 该迭代器多次解引用将只会引起底层迭代器的一次解引用；
+ 这样，插槽可以一次调用但其结果可多次使用。</para></entry>
</row>
<row>
- <entry><para>Slot Call Iterator</para></entry>
- <entry><para>Iterates over calls to each slot.</para></entry>
+ <entry><para>Slot Call Iterator<sbr/>
+ 插槽调用迭代器</para></entry>
+ <entry><para>Iterates over calls to each slot.<sbr/>
+ 迭代调用每个插槽。</para></entry>
</row>
</tbody>
</tgroup>
@@ -141,14 +183,17 @@
</section>
<section>
- <title><code>visit_each</code> function template</title>
+ <title><code>visit_each</code> function template
<code>visit_each</code>函数模板</title>
<para> The <code><functionname>visit_each</functionname></code>
function template is a mechanism for discovering objects that are
stored within another object. Function template
<code><functionname>visit_each</functionname></code> takes three
arguments: an object to explore, a visitor function object that is
- invoked with each subobject, and the <code>int</code> 0. </para>
+ invoked with each subobject, and the <code>int</code> 0. <sbr/>
+ <code><functionname>visit_each</functionname></code> 函数模板是一种机
制，
+ 用于发现保存于另一个对象中的对象。
<code><functionname>visit_each</functionname></code> 有三个参数：
+ 待探测的对象、对每个子对象进行调用的访问者函数和 <code>int</code> 0。
</para>
<para> The third parameter is merely a temporary solution to the
widespread lack of proper function template partial ordering. The
@@ -163,7 +208,14 @@
<code>long</code>. The ordering determined by this conversion thus
achieves partial ordering of the function templates in a limited,
but successful, way. The following example illustrates the use of
- this technique:</para>
+ this technique:<sbr/>
+ 第三个参数仅仅是个临时的解决方案，针对普遍缺乏正确的函数模板特化次序这
一问题。
+ <code><functionname>visit_each</functionname></code> 函数主模板指定这个
第三个参数类型为 <code>long</code>，
+ 而任何用户特化必须指定他们的第三个参数类型为 <code>int</code>。这样，
+ 即使不合标准的编译器不能例如在匹配参数 <code>T</code> 和参数
<code>A<T></code> 之间判断次序，
+ 它也可以决定从整数 0 到 <code>int</code> 的转换比到 <code>long</code>
的转换更好。
+ 这个转换所决定的次序就这样做到了函数模板特化的次序化，以一种有限的但是
成功的方式。
+ 下面的例子显示了该技术的使用：</para>
<programlisting>
template<typename> class A {};
@@ -179,6 +231,9 @@
cannot be ordered based on that parameter. Then the conversion
from 0 to <code>int</code> is better than the conversion from 0 to
<code>long</code>, and the second function template is
- chosen. </para>
+ chosen. <sbr/>
+ 在本例中，我们假定我们的编译器不能判断 <code>A<T></code> 比
<code>T</code> 更匹配，
+ 并因此假定函数模板不能基于那个参数排序。于是从 0 到 <code>int</code> 的
转换比从 0 到 <code>long</code> 的转换更好，
+ 并且第二个函数模板被选中。</para>
</section>
</section>
=======================================
--- /trunk/libs/signals/doc/faq.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/signals/doc/faq.xml Sat Jan 23 06:27:10 2010
@@ -2,42 +2,51 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section last-revision="$Date: 2008-05-21 16:57:05 -0400 (Wed, 21 May
2008) $">
- <title>Frequently Asked Questions</title>
+ <title>Frequently Asked Questions 常见问题</title>
<qandaset>
<qandaentry>
<question>
<para>Don't noncopyable signal semantics mean that a class
- with a signal member will be noncopyable as well?</para>
+ with a signal member will be noncopyable as well?<sbr/>
+ signal 的不可复制语义并不是意味着带有 signal 成员的类也是不可复制
的？</para>
</question>
<answer>
<para>No. The compiler will not be able to generate a copy
constructor or copy assignment operator for your class if it
has a signal as a member, but you are free to write your own
copy constructor and/or copy assignment operator. Just don't
- try to copy the signal.</para>
+ try to copy the signal.<sbr/>
+ 对。如果你的类有一个 signal 成员，编译器就不能为你的类生成一个复制
构造函数或复制赋值操作符，
+ 但是你可以自己编写复制构造函数和/或赋值操作符。只是不要试图复制那
个 signal。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>Is Boost.Signals thread-safe?</para>
+ <para>Is Boost.Signals thread-safe?<sbr/>
+ Boost.Signals 是线程安全的吗？</para>
</question>
<answer>
<para>No. Using Boost.Signals in a multithreaded concept is
very dangerous, and it is very likely that the results will be
less than satisfying. Boost.Signals will support thread safety
- in the future.</para>
+ in the future.<sbr/>
+ 不是。在多线程中使用 Boost.Signals 是很危险的，这个结果不能满足需
要。
+ Boost.Signals 在未来将会支持线程安全。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>How do I get Boost.Signals to work with Qt?</para>
+ <para>How do I get Boost.Signals to work with Qt?<sbr/>
+ 我如何让 Boost.Signals 与 Qt 一起使用呢？</para>
</question>
<answer>
<para>When building with Qt, the Moc keywords
<code>signals</code> and <code>slots</code> are defined using
preprocessor macros, causing programs using Boost.Signals and
- Qt together to fail to compile.</para>
+ Qt together to fail to compile.<sbr/>
+ 与 Qt 一起构建时，Moc 关键字 <code>signals</code> 和
<code>slots</code> 采用预处理器宏来定义，
+ 这使得同时使用 Boost.Signals 和 Qt 的程序无法通过编译。</para>
<para><emphasis>For Qt 4.1 and later</emphasis>, This behavior
can be turned off in Qt on a per-project or per-file basis
@@ -46,7 +55,12 @@
re-configure, re-build, or duplicate existing libraries. For a
project where you want to use both Boost.Signals and Qt
Signals and Slots, the relevant part of your .pro file might
- look like this:</para>
+ look like this:<sbr/>
+ <emphasis>对于 Qt 4.1 及后续版本</emphasis>，这一行为可以在 Qt 中关
闭，
+ 方法是在一个 per-project 或 per-file 基础上使用
<code>no_keywords</code> 选项。
+ 这可以用于缺省构建的 Boost 和 Qt。你不需要重新配置、重新构建或复制
已有的库。
+ 对于你想要同时使用 Boost.Signals 和 Qt Signals 以及 Slots 的项目，
+ 你的 .pro 文件的相应部分如下：</para>
<programlisting>
CONFIG += no_keywords # so Qt won't #define any non-all-caps
`keywords'
@@ -61,14 +75,22 @@
url="http://scottcollins.net/articles/a-deeper-look-at-signals-and-slots.html";>A
Deeper Look at Signals and Slots</ulink> [off-site] for more
complete examples and a survey of the strengths of the two
- systems.</para>
+ systems.<sbr/>
+ 现在你可以在同一个文件中混用 Boost.Signals 和 Qt Signals 及 Slots
了，
+ 即使是在同一个类或函数中。你必须在你的代码中使用大写字母的 Qt 宏。
+ 更多的完整例子和共用这两个系统的纵览，请见论文 <ulink
+
url="http://scottcollins.net/articles/a-deeper-look-at-signals-and-slots.html";>A
+ Deeper Look at Signals and Slots</ulink> [off-site]。</para>
<para><emphasis>Older versions of Qt</emphasis> did not
provide a reliable mechanism for avoiding these unfriendly,
all lower-case `keyword'-like macros. Although this is a
problem with Qt and not Boost.Signals, a user can use the two
systems together with a little extra effort. There are two
- ways to do this:</para>
+ ways to do this:<sbr/>
+ <emphasis>旧版本的 Qt</emphasis> 不提供避免这些不便的方法，
+ 所有'关键字'样式的宏都是小写的。虽然这是 Qt 的问题而不是
Boost.Signals 的，
+ 用户还是可以通过一些小的努力来一起使用这两个系统。有两种方法可以做
到这一点：</para>
<para>The first way involves defining
the <code>BOOST_SIGNALS_NAMESPACE</code>
@@ -78,7 +100,10 @@
<code>boost::BOOST_SIGNALS_NAMESPACE</code> instead of
<code>boost::signals</code>. To retain the original namespace
name in translation units that do not interact with Qt, you
- can use a namespace alias:</para>
+ can use a namespace alias:<sbr/>
+ 第一种方法是在构建和使用 Boost.Signals 库时将
<code>BOOST_SIGNALS_NAMESPACE</code> 宏定义为其它标识符
+ (如 <code>signalslib</code>)。这样 Boost.Signals 库的名字空间就是
<code>boost::BOOST_SIGNALS_NAMESPACE</code>
+ 而不是 <code>boost::signals</code>。要在没有与 Qt 共用的编译单元中
保留原有名字空间，你可以使用名字空间别名：</para>
<programlisting>
namespace boost {
@@ -89,7 +114,9 @@
<para>The second way, provided by Frank Hess and improved by
Niels Dekker, involves
creating a header <code>signalslib.hpp</code> that contains
- the following code:</para>
+ the following code:<sbr/>
+ 第二种方法是由 Frank Hess 提供并由 Niels Dekker 改进的，
+ 创建一个头文件 <code>signalslib.hpp</code>，包含以下代码：</para>
<programlisting>#ifndef SIGNALSLIB_HPP_INCLUDED
#define SIGNALSLIB_HPP_INCLUDED
@@ -120,7 +147,9 @@
to it in the namespace <code>boost::signalslib</code>. This
option is often
preferable to the first option because it can be used without
- recompiling the Signals library binary. </para>
+ recompiling the Signals library binary. <sbr/>
+ 使用这个头文件来包含 Boost 库，然后在名字空间
<code>boost::signalslib</code> 中引用它。
+ 这一方法通常优于第一种方法，因为它无需重新编译 Signals 库的二进制代
码就可以使用。</para>
</answer>
</qandaentry>
</qandaset>
=======================================
--- /trunk/libs/signals/doc/introduction.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/signals/doc/introduction.xml Sat Jan 23 06:27:10 2010
@@ -2,14 +2,17 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section last-revision="$Date: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov
2007) $">
- <title>Introduction</title>
+ <title>Introduction 介绍</title>
<para>The Boost.Signals library is an implementation of a managed
signals and slots system. Signals represent callbacks with multiple
targets, and are also called publishers or events in similar
systems. Signals are connected to some set of slots, which are
callback receivers (also called event targets or subscribers), which
-are called when the signal is "emitted."</para>
+are called when the signal is "emitted."<sbr/>
+Boost.Signals 库实现了一个可控的信号插槽系统。信号代表了具有多个目标的回
调，
+在类似的系统中也称为发布者或事件。 信号与某组插槽相连接，插槽即回调的接收者
+（也称为事件目标或订阅者），它们在信号“发出”时被调用。</para>
<para>Signals and slots are managed, in that signals and slots (or,
more properly, objects that occur as part of the slots) track all
@@ -17,12 +20,17 @@
connections when either is destroyed. This enables the user to make
signal/slot connections without expending a great effort to manage the
lifetimes of those connections with regard to the lifetimes of all
-objects involved.</para>
+objects involved.<sbr/>
+信号和插槽是可控的，因为信号和插槽（或严格地说是作为插槽出现的对象）跟踪所
有的连接，
+并能够在信号或插槽销毁时自动断开信号/插槽的连接。这让使用者能够在建立信号
/插槽连接的同时，
+不必费力地根据相关对象的生命期去管理那些连接的生命期。</para>
<para>When signals are connected to multiple slots, there is a
question regarding the relationship between the return values of the
slots and the return value of the signals. Boost.Signals allows the
user to specify the manner in which multiple return values are
-combined.</para>
+combined.<sbr/>
+当信号连接多个插槽时，插槽的返回值和信号的返回值之间是什么关系呢？这是个问
题。
+Boost.Signals 允许用户合并多个返回值，并指定合并的方式。</para>
</section>
=======================================
--- /trunk/libs/signals/doc/rationale.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/signals/doc/rationale.xml Sat Jan 23 06:27:10 2010
@@ -2,14 +2,14 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section last-revision="$Date: 2007-11-25 13:38:02 -0500 (Sun, 25 Nov
2007) $">
- <title>Design Rationale</title>
+ <title>Design Rationale 设计原理</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals"/>
<using-class name="boost::signalN"/>
<section>
- <title>Choice of Slot Definitions</title>
+ <title>Choice of Slot Definitions 插槽定义的选择</title>
<para> The definition of a slot differs amongst signals and slots
libraries. Within Boost.Signals, a slot is defined in a very loose
@@ -18,7 +18,11 @@
value is convertible to the result type expected by the
signal. However, alternative definitions have associated pros and
cons that were considered prior to the construction of
- Boost.Signals.</para>
+ Boost.Signals.<sbr/>
+ 不同的信号和插槽库中，插槽的定义是不同的。在 Boost.Signals 中，
+ 插槽的定义很宽松： 它可以是任意函数对象，只要它可以输入信号所指定类型的
参数进行调用，
+ 并且其返回值可转换为信号所要求的结果类型。 然而，不同的定义各有好坏，
+ 需要在 Boost.Signals 的构造之前进行仔细考虑。</para>
<itemizedlist>
<listitem>
@@ -32,11 +36,17 @@
adaptor classes containing virtual functions has been found to
cause an unacceptable increase in the size of executables
(polymorphic class types require more code than
- non-polymorphic types).</para>
+ non-polymorphic types).<sbr/>
+ <emphasis role="bold">插槽派生自特殊的基类</emphasis>：
+ 通常这样的方案要求所有用户定义的插槽派生自库所指定的某个
<code>Slot</code> 抽象类，
+ 该抽象类定义了一个调用插槽的虚函数。可以使用一个适配器将这样一个定
义转换到类似 Boost.Signals 所用的定义。
+ 但是发现使用大量包含虚函数的小适配类会导致执行程序的大小增长到不可
接受的程度
+ （多态类类型比非多态类型需要更多的代码）。 </para>
<para> This approach does have the benefit of simplicity of
implementation and user interface, from an object-oriented
- perspective.</para>
+ perspective.<sbr/>
+ 从面向对象的观点看，这种方法不具有实现上和用户接口上简单性的好处。
</para>
</listitem>
<listitem>
@@ -56,17 +66,26 @@
primitives, but instead provides a hook (via the
<code><functionname>visit_each</functionname></code>
mechanism) that allows existing binder/composition libraries
- to provide the necessary information to Signals.</para>
+ to provide the necessary information to Signals.<sbr/>
+ <emphasis role="bold">插槽构造自一套原语</emphasis>：在这个方案中，
+ 插槽可以具有一组有限的类型 （往往是派生自共同的抽象基类）， 它们构
造自某套由库定义的原语，
+ 原语往往包括从自由函数指针和成员函数指针到插槽的转换，和一组有限的
绑定能力。
+ 这样一种方法比较简单并适用于大多数的普通情况，但是它不允许插槽构造
中的高度灵活性。
+ 用于函数对象组合的库已经变得相当发达， 信号和插槽库不应该加入这种增
强功能。
+ 所以 Boost.Signals 没有包含参数绑定或函数对象组合原语，但是转而提供
了一个钩子
+ （通过 <code><functionname>visit_each</functionname></code> 机制
），
+ 以允许现有的绑定/组合库向 Signals 库提供必要的信息。</para>
</listitem>
</itemizedlist>
<para> Users not satisfied with the slot definition choice may opt
to replace the default slot function type with an alternative that
- meets their specific needs.</para>
+ meets their specific needs.<sbr/>
+ 如果不满意该插槽定义的选择，用户可以选择用另外的符合他们需要的类型替换
默认的插槽函数类型。</para>
</section>
<section>
- <title>User-level Connection Management</title>
+ <title>User-level Connection Management 用户层连接管理</title>
<para> Users need to have fine control over the connection of
signals to slots and their eventual disconnection. The approach
@@ -74,7 +93,10 @@
<code><classname>connection</classname></code> object that enables
connected/disconnected query, manual disconnection, and an
automatic disconnection on destruction mode. Some other possible
- interfaces include:</para>
+ interfaces include:<sbr/>
+ 用户需要精确控制信号到插槽的连接和它们最后的断开。Boost.Signals 所采用
的方法是返回一个
+ <code><classname>connection</classname></code> 对象，让人能够进行已连接
/已断开查询、手工断开，
+ 及在析构模式下自动断开。 其他一些可能的接口包括：</para>
<itemizedlist>
<listitem>
@@ -94,7 +116,15 @@
slot given in the call to
<code><methodname>disconnect</methodname></code> with an
existing slot we would need to be able to compare arbitrary
- function objects, which is not feasible.</para>
+ function objects, which is not feasible.<sbr/>
+ <emphasis role="bold">断开时传递插槽</emphasis>：在这个接口模型下，
+ 通过 <code>sig.<methodname>connect</methodname>(slot)</code> 连接的
插槽，
+ 断开时是通过
<code>sig.<methodname>disconnect</methodname>(slot)</code> 进行的。
+ 在内部，将利用插槽比较，执行一个线性搜索，如果找到该插槽，就从链表
中删除。
+ 不幸的是，查询连接一般也将成为线性时间的操作。当插槽变得更复杂
时，比简单函数指针、
+ 成员函数指针和一组有限的组合和参数绑定更复杂时，该模型也因实现上的
原因而不可用：
+ 为了在现存插槽中匹配
<code><methodname>disconnect</methodname></code> 调用中输入的插槽，
+ 我们需要能够比较任意函数对象，而这是不可能的。</para>
</listitem>
<listitem>
@@ -103,7 +133,11 @@
token that is easily comparable (e.g., a string), enabling
slots to be arbitrary function objects. While this approach is
essentially equivalent to the approach taken by Boost.Signals,
- it is possibly more error-prone for several reasons:</para>
+ it is possibly more error-prone for several reasons:<sbr/>
+ <emphasis role="bold">断开时传递一个标记</emphasis>：
+ 这个方法用一个容易比较的标记来标识插槽（例如用字符串），
+ 插槽可以是任意的函数对象。虽然这个方法本质上等效于 Boost.Signals 所
采用的方法，
+ 但是因为以下几个原因，它更容易出错：</para>
<itemizedlist>
<listitem>
@@ -113,7 +147,10 @@
dynamic memory allocation. While errors of this sort would
not be catastrophic for a signals and slots
implementation, their detection is generally
- nontrivial.</para>
+ nontrivial.<sbr/>
+ 连接与断开必须配对，因此问题变得类似于动态内存分配中的
+ <code>new</code> 和 <code>delete</code> 配对时所产生的问题。
+ 虽然这种错误对于信号插槽库实现来说并不是灾难性的，但是要检测它
们通常并不容易。</para>
</listitem>
<listitem>
@@ -123,27 +160,34 @@
dynamically, name generation becomes an additional task
for the user. Uniqueness of tokens also results in an
additional failure mode when attempting to connect a slot
- using a token that has already been used.</para>
+ using a token that has already been used.<sbr/>
+ 标记必须唯一，否则两个插槽就会具有相同的名字而不可区分。
+ 在动态产生许多连接的环境下，名字生成将成为用户的额外负担。
+ 标记的唯一性也导致了额外的失败模式，如试图用一个已经被使用的标
记连接一个插槽。</para>
</listitem>
<listitem>
<para>More parameterization would be required, because the
token type must be user-defined. Additional
parameterization steepens the learning curver and
- overcomplicates a simple interface.</para>
+ overcomplicates a simple interface.<sbr/>
+ 需要更多的参数，因为标记的类型必须是用户定义的。
+ 额外的参数使学习曲线变得陡峭，使简单的接口过度复杂。</para>
</listitem>
</itemizedlist>
<para> This type of interface is supported in Boost.Signals
via the slot grouping mechanism. It augments the
<code><classname>connection</classname></code> object-based
- connection management scheme.</para>
+ connection management scheme.<sbr/>
+ 这类接口在 Boost.Signals 中通过插槽编组机制获得支持。它是支持基于
+ <code><classname>connection</classname></code> 对象的连接管理机制的
理由。</para>
</listitem>
</itemizedlist>
</section>
<section>
- <title>Combiner Interface</title>
+ <title>Combiner Interface 合并器接口</title>
<para> The Combiner interface was chosen to mimic a call to an
algorithm in the C++ standard library. It is felt that by viewing
@@ -157,7 +201,12 @@
libraries, the combiners are unfortunately not reusable (either in
other signals & slots libraries or within other generic
algorithms), and the learning curve is steepened slightly to learn
- the specific combiner interface.</para>
+ the specific combiner interface.<sbr/>
+ 合并器接口模仿了对C++标准库算法的调用。 对熟练的C++程序员来说，合并器是
感觉最自然的接口，
+ 因为它把插槽调用的结果看作仅仅是一系列通过输入迭代器访问的值。
+ 与之匹敌的接口设计一般要求合并器构造成符合一定的接口，使之可以为信号库
定制（并局限于库）。
+ 虽然这些接口通常使信号插槽库的实现更简单，但可惜这种合并器不可重用（在
其他信号插槽库或在其他通用算法中），
+ 并且学习特殊的合并器接口的学习曲线有点陡。</para>
<para> The Signals formulation of combiners is based on the
combiner using the "pull" mode of communication, instead of the
@@ -171,14 +220,20 @@
the combiner's routines will be invoked for each signal
called. Compare, for example, a combiner that returns the maximum
element from calling the slots. If the maximum element ever
- exceeds 100, no more slots are to be called.</para>
+ exceeds 100, no more slots are to be called.<sbr/>
+ Signals 库的合并器设计方案基于使用“拉（pull）”模式通讯的合并器，而不是
更复杂的“推（push）”机制。
+ 用“拉”机制，合并器的状态可以保存在栈上，并保持程序计数器寄存器，因为无
论何时需要新数据时
+ （即调用下一插槽来提取其返回值），有一个简单的接口来立即提取那个数据，
+ 而不必从合并器的代码中返回。“推”机制与此相反，它的合并器必须在类成员中
保存所有的状态，
+ 因为每次调用信号都会引起合并器函数的调用。比较下例合并器的两种实现，该
合并器返回插槽调用的最大元素。
+ 如果最大元素超过 100，就不再调用以后的插槽。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry><para>Pull</para></entry>
- <entry><para>Push</para></entry>
+ <entry><para>Pull 拉</para></entry>
+ <entry><para>Push 推</para></entry>
</row>
</thead>
<tbody>
@@ -259,7 +314,11 @@
received. Though code quality and ease-of-use is generally
subjective, the "pull" model is clearly shorter and more reusable
and will often be construed as easier to write and understand,
- even outside the context of a signals & slots library.</para>
+ even outside the context of a signals & slots library.<sbr/>
+ 该例中要注意几点。“拉”的版本是个可重用的函数对象，基于
<code>value_type</code> 为整数的输入迭代器序列，
+ 并且设计上非常简单。 另一方面，“推”的版本依赖于调用者专有的接口，一般不
是可重用的。
+ 它同时要求额外的状态值，例如，是否已经接收过元素。尽管代码质量和易用性
是主观性的，
+ “拉”模式明显更短并且重用性更好，并且往往更容易编写和理解，即使是脱离信
号插槽库的上下文。</para>
<para> The cost of the "pull" combiner interface is paid in the
implementation of the Signals library itself. To correctly handle
@@ -274,18 +333,27 @@
invoking slots one sees that the overhead is nearly equivalent to
that in the "push" model, but we have inverted the control
structures to make iteration and dereference complex (instead of
- making combiner state-finding complex).</para>
+ making combiner state-finding complex).<sbr/>
+ “拉”合并器接口的代价支付于 Signals 库本身的实现中。为了正确处理在调用中
的插槽断开
+ （例如当调用解引用运算符时），你必须让迭代器跳过已断开的插槽。另外，
+ 迭代器必须携带一组参数以传送到每个插槽（尽管一个包含那些参数的结构的引
用就足够了），
+ 并且必须缓存插槽调用的结果，这样多次解引用才不会导致多次调用。这显然需
要很大的开销，
+ 尽管如果考虑调用插槽整个过程，该开销几乎等同于“推”模型的开销，但是我们
颠倒了控制结构，
+ 让迭代和解引用变复杂了（替代了合并器状态查找的复杂性）。</para>
</section>
<section>
- <title>Connection Interfaces: += operator</title>
+ <title>Connection Interfaces: += operator 连接的接口：+= 运算符
</title>
<para> Boost.Signals supports a connection syntax with the form
<code>sig.<methodname>connect</methodname>(slot)</code>, but a
more terse syntax <code>sig += slot</code> has been suggested (and
has been used by other signals & slots implementations). There
are several reasons as to why this syntax has been
- rejected:</para>
+ rejected:<sbr/>
+ Boost.Signals 支持形如
<code>sig.<methodname>connect</methodname>(slot)</code> 的连接语法，
+ 但是有人建议用更简洁的语法 <code>sig += slot</code>（并已被其他信号插槽
实现所用）。
+ 为什么拒绝这个语法有以下几个原因：</para>
<itemizedlist>
<listitem>
@@ -295,7 +363,12 @@
operator. The savings in typing (<code>connect()</code>
vs. <code>+=</code>) is essentially negligible. Furthermore,
one could argue that calling <code>connect()</code> is more
- readable than an overload of <code>+=</code>.</para>
+ readable than an overload of <code>+=</code>.<sbr/>
+ <emphasis role="bold">没必要</emphasis>：Boost.Signals 提供的连接语
法并不比 <code>+=</code> 运算符差。
+ 少打几个字符（<code>connect()</code> vs. <code>+=</code>）根本是可
以忽略的。另外，
+ 有人主张调用 <code>connect()</code> 比 <code>+=</code> 重载可读性更
好。
+
+</para>
</listitem>
<listitem>
<para><emphasis role="bold">Ambiguous return type</emphasis>:
@@ -304,7 +377,10 @@
signal itself, to enable <code>sig += slot1 += slot2</code>,
or should it return a
<code><classname>connection</classname></code> for the
- newly-created signal/slot connection?</para>
+ newly-created signal/slot connection?<sbr/>
+ <emphasis role="bold">返回类型二义性</emphasis>：<code>+=</code> 运
算符的返回值存在二义性。
+ 它应该是返回信号本身的引用，可以 <code>sig += slot1 +=
slot2</code>，
+ 还是返回新建的信号/插槽连接的一个
<code><classname>connection</classname></code>？</para>
</listitem>
<listitem>
@@ -315,20 +391,26 @@
the library allows arbitrary function objects to implicitly
become slots, because slots are no longer comparable. <!--
(see the discussion on this topic in User-level Connection
- Management). --></para>
+ Management). --><sbr/>
+ <emphasis role="bold">通往运算符 -=、+</emphasis>：当添加一个连接运
算符 <code>+=</code>，
+ 好像自然地要有一个断开运算符 <code>-=</code>。然而，当库允许任意的
函数对象隐式地变成插槽时，
+ 这里出现了问题，因为插槽不再具有比较性。</para>
<para> The second obvious addition when one has
<code>operator+=</code> would be to add a <code>+</code>
operator that supports addition of multiple slots, followed by
assignment to a signal. However, this would require
implementing <code>+</code> such that it can accept any two
- function objects, which is technically infeasible.</para>
+ function objects, which is technically infeasible.<sbr/>
+ 当具有 <code>operator+=</code> 时，第二个明显会添加的是
<code>+</code> 运算符，
+ 以支持多个插槽相加，然后再赋值到信号。然而，这要求实现
<code>+</code> 可以接收任意两个函数对象，
+ 这在技术上是不可行的。</para>
</listitem>
</itemizedlist>
</section>
<section>
- <title><code>trackable</code> rationale</title>
+ <title><code>trackable</code> rationale <code>trackable</code>的原理
</title>
<para> The <code><classname>trackable</classname></code>
class is the primary user interface to automatic connection
@@ -336,10 +418,13 @@
issues stick out most: the odd copying behavior of
<code>trackable</code>, and the limitation requiring users to
derive from <code>trackable</code> to create types that can
- participate in automatic connection management.</para>
+ participate in automatic connection management.<sbr/>
+ <code><classname>trackable</classname></code> 类是自动连接生命期管理
主要的用户接口，
+ 它的设计直接影响用户。有两个问题最为突出：<code>trackable</code> 古怪
的复制行为，
+ 和用户创建可以参与自动连接管理的类型时，要求派生自
<code>trackable</code> 的限制。</para>
<section>
- <title><code>trackable</code> copying behavior</title>
+ <title><code>trackable</code> copying behavior
<code>trackable</code>的复制行为</title>
<para> The copying behavior of
<code><classname>trackable</classname></code> is essentially
@@ -354,37 +439,51 @@
don't refer to the target entity - they refer to the source
entity. This reason is dual to the reason signals are
noncopyable: the slots connected to them are connected to that
- particular signal, not the data contained in the signal.</para>
+ particular signal, not the data contained in the signal.<sbr/>
+ <code><classname>trackable</classname></code> 的复制行为基本上是
+ <code><classname>trackable</classname></code> 子对象不可复制。
+ 相反，复制运算符只是个空操作。为理解这一点，我们来看看信号-插槽连接的
性质，
+ 并留意该连接是基于正在被连接的实体的；当实体之一被销毁时，连接就被销
毁。
+ 因此，当一个 <code><classname>trackable</classname></code> 子对象被复
制时，
+ 我们不能复制连接，因为连接不能引用目标实体――它们只能引用原实体。
+ 这个原因是因为信号是不可复制的：连接到信号的插槽是连接到该特定的信
号，
+ 而不是信号中所包含的数据。</para>
</section>
<section>
- <title>Why derivation from <code>trackable</code>?</title>
+ <title>Why derivation from <code>trackable</code>? 为什么要派生自
<code>trackable</code>？</title>
<para> For <code><classname>trackable</classname></code> to work
- properly, there are two constraints:</para>
+ properly, there are two constraints:<sbr/>
+ 为了让 <code><classname>trackable</classname></code> 正常工作，有两个
约束：</para>
<itemizedlist>
<listitem>
<para><code><classname>trackable</classname></code> must
have storage space to keep track of all connections made to
- this object.</para>
+ this object.<sbr/>
+ <code><classname>trackable</classname></code> 必须跟踪保存这个对
象的所作的所有连接。</para>
</listitem>
<listitem>
<para><code><classname>trackable</classname></code> must be
notified when the object is being destructed so that it can
- disconnect its connections.</para>
+ disconnect its connections.<sbr/>
+ 当 <code><classname>trackable</classname></code> 正在被析构时，
+ 必须通知该对象，以使它能够断开它的所有连接。</para>
</listitem>
</itemizedlist>
<para>Clearly, deriving from
<code><classname>trackable</classname></code> meets these two
- guidelines. We have not yet found a superior solution.</para>
+ guidelines. We have not yet found a superior solution.<sbr/>
+ 显然，派生自 <code><classname>trackable</classname></code> 符合这两个
方针。
+ 我们还没有找到更好的解决安案。</para>
</section>
</section>
<section>
- <title>Comparison with other Signal/Slot implementations</title>
+ <title>Comparison with other Signal/Slot implementations 与其他信号/插
槽实现的比较</title>
<section>
<title>libsigc++</title>
@@ -401,7 +500,12 @@
similar syntax for the construction of signals and in the use of
connections and automatic connection lifetime management. There
are some major differences in design that separate these
- libraries:</para>
+ libraries:<sbr/>
+ <ulink url="http://libsigc.sourceforge.net";>libsigc++</ulink> 是个
C++信号插槽库，
+ 最初开始于一个项目的一部分，用C++封装 <ulink
url="http://www.gtk.org";>GTK</ulink> 库的C接口，
+ 并且发展成为一个独立的库，由 Karl Nelson 维护。libsigc++ 和
Boost.Signals 之间有很多相同之处，
+ 其实 Boost.Signals 受 Karl Nelson 和 libsigc++ 影响很大。粗略地检查这
两个库就会发现相似的语法，
+ 如在信号的构造，和连接及自动连接生命期管理的使用。这两个库在设计上的
主要区别是：</para>
<itemizedlist>
<listitem>
@@ -413,7 +517,11 @@
and return types of the slot (libsigc++ is, by default, more
strict about types than Boost.Signals). A discussion of this
approach with a comparison against the approach taken by
- Boost.Signals is given in Choice of Slot Definitions.</para>
+ Boost.Signals is given in Choice of Slot Definitions.<sbr/>
+ <emphasis role="bold">插槽定义</emphasis>：libsigc++ 中的插槽用一
套库定义的原语创建。
+ 这些原语允许对象绑定（作为库的一部分），显式地把信号的参数和返回
类型适配为插槽的参数和返回类型
+ （相比 Boost.Signals，libsigc++ 在默认情况下对类型更严格）。对这
个方法的讨论，
+ 同时还有与 Boost.Signals 所采用方法的比较，见“插槽定义的选择”一
节。</para>
</listitem>
<listitem>
@@ -422,7 +530,9 @@
combiners in libsigc++ are the marshallers. Marshallers are
similar to the "push" interface described in Combiner
Interface, and a proper treatment of the topic is given
- there.</para>
+ there.<sbr/>
+ <emphasis role="bold">合并器/集结器接口</emphasis>：libsigc++ 中
与 Boost.Signals 的合并器等效的是集结器。
+ 集结器类似于“合并器接口”一节中描述的“推”接口，那里对该主题进行了
适当的分析。</para>
</listitem>
</itemizedlist>
</section>
@@ -435,18 +545,24 @@
languages and language extensions, one of which is the
delegate. Delegates are similar to signals and slots, but they
are more limited than most C++ signals and slots implementations
- in that they:</para>
+ in that they:<sbr/>
+ <ulink url="http://www.microsoft.com";>Microsoft</ulink> 引入了 .NET
框架，
+ 并关联了一组语言和语言扩展，其中之一就是委托。委托类似于信号插槽，
+ 但是它比大多数C++信号插槽的实现具有更多的限制，表现在：</para>
<itemizedlist>
<listitem>
<para>Require exact type matches between a delegate and what
- it is calling.</para>
+ it is calling.<sbr/>
+ 在委托和它的调用之间，要求精确的类型匹配。</para>
</listitem>
- <listitem><para>Only return the result of the last target called,
with no option for customization.</para></listitem>
+ <listitem><para>Only return the result of the last target called,
with no option for customization.<sbr/>
+ 仅返回最后调用目标的结果，无法定制。</para></listitem>
<listitem>
<para>Must call a method with <code>this</code> already
- bound.</para>
+ bound.<sbr/>
+ 必须调用一个 <code>this</code> 已绑定的方法。</para>
</listitem>
</itemizedlist>
</section>
=======================================
--- /trunk/libs/signals/doc/tests.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/signals/doc/tests.xml Sat Jan 23 06:27:10 2010
@@ -8,7 +8,8 @@
<purpose>
<para>Ensure that calling <methodname>connect</methodname> with a slot
that has already been disconnected via deletion does not actually
-connect to the slot.</para>
+connect to the slot.<sbr/>
+确保对一个已经通过删除被断开的插槽调用 <methodname>connect</methodname> 不
会真正地连接该插槽。</para>
</purpose>
</run-test>
@@ -16,14 +17,18 @@
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<lib>../build/boost_signals</lib>
<purpose>
-<para>Test deletion of slots.</para>
+<para>Test deletion of slots.<sbr/>
+测试插槽的删除。
+</para>
</purpose>
</run-test>
<run-test filename="ordering_test.cpp">
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<lib>../build/boost_signals</lib>
- <purpose><para>Test slot group ordering.</para></purpose>
+ <purpose><para>Test slot group ordering.<sbr/>
+ 测试插槽组排序。
+</para></purpose>
</run-test>
<run-test filename="signal_n_test.cpp">
@@ -31,7 +36,8 @@
<lib>../build/boost_signals</lib>
<purpose>
<para>Basic test of signal/slot connections and invocation using the
-<classname>boost::signalN</classname> class templates.</para>
+<classname>boost::signalN</classname> class templates.<sbr/>
+用 <classname>boost::signalN</classname> 类模板的信号/插槽连接和调用的基本
测试。</para>
</purpose>
</run-test>
@@ -40,13 +46,17 @@
<lib>../build/boost_signals</lib>
<purpose>
<para>Basic test of signal/slot connections and invocation using the
-<classname>boost::signal</classname> class template.</para>
+<classname>boost::signal</classname> class template.<sbr/>
+用 <classname>boost::signal</classname> 类模板的信号/插槽连接和调用的基本测
试。</para>
</purpose>
<if-fails>
<para>The <classname>boost::signal</classname> class template may not
be usable on your compiler. However, the
<classname>boost::signalN</classname> class templates may still be
-usable.</para>
+usable.<sbr/>
+在你的编译器上，<classname>boost::signal</classname> 类模板可能不可用。
+然而 <classname>boost::signalN</classname> 类模板仍是可用的。
+</para>
</if-fails>
</run-test>
@@ -55,7 +65,8 @@
<lib>../build/boost_signals</lib>
<purpose>
<para>Test automatic lifetime management using
- <classname>boost::trackable</classname> objects.</para>
+ <classname>boost::trackable</classname> objects.<sbr/>
+ 测试使用 <classname>boost::trackable</classname> 对象的自动生命期管
理。</para>
</purpose>
</run-test>
</testsuite>
=======================================
--- /trunk/libs/signals/doc/tutorial.xml Mon Dec 28 23:05:14 2009
+++ /trunk/libs/signals/doc/tutorial.xml Sat Jan 23 06:27:10 2010
@@ -2,14 +2,14 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd";>
<section last-revision="$Date: 2007-01-29 15:05:29 -0500 (Mon, 29 Jan
2007) $" id="signals.tutorial">
- <title>Tutorial</title>
+ <title>Tutorial 教程</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals"/>
<using-class name="boost::signalN"/>
<section>
- <title>How to Read this Tutorial</title>
+ <title>How to Read this Tutorial 如何阅读本教程</title>
<para>This tutorial is not meant to be read linearly. Its top-level
structure roughly separates different concepts in the library
(e.g., handling calling multiple slots, passing values to and from
@@ -25,10 +25,17 @@
the <emphasis>Advanced</emphasis> sections detail very advanced uses of the
Signals library, that often require a solid working knowledge of
the <emphasis>Beginner</emphasis> and <emphasis>Intermediate</emphasis>
topics; most users
-will not need to read the <emphasis>Advanced</emphasis> sections.</para>
+will not need to read the <emphasis>Advanced</emphasis> sections.<sbr/>
+本教程不是用来线性阅读的。 其顶层结构大致按库中不同的概念划分，（如处理多个
插槽的调用、传值到插槽及回传），
+并且在每一个概念中，首先介绍其基本思想，然后说明库较复杂的使用。 每个部分都
标注了<emphasis>初级</emphasis>、
+<emphasis>中级</emphasis>，或<emphasis>高级</emphasis>，以帮助指导读者。
+<emphasis>初级</emphasis>部分包括库的所有使用者都该了解的信息；只要阅读了初
级部分，就可以很好地使用信号库。
+<emphasis>中级</emphasis>部分建立在<emphasis>初级</emphasis>部分之上，是库
的稍复杂的使用。
+最后，<emphasis>高级</emphasis>部分详述了信号库很高级的应用，这往往需要对
<emphasis>初级</emphasis>
+和<emphasis>中级</emphasis>内容扎实的实践经验；大多数用户无需阅读
<emphasis>高级</emphasis>部分。</para>
</section>
-<section><title>Compatibility Note</title>
+<section><title>Compatibility Note 对兼容性的注释</title>
<para>Boost.Signals has two syntactical forms: the preferred form and
the compatibility form. The preferred form fits more closely with the
@@ -39,18 +46,24 @@
Boost.Signals. Consult the table below to determine which syntactic
form to use for your compiler. Users of Boost.Function, please note
that the preferred syntactic form in Signals is equivalent to that of
-Function's preferred syntactic form.</para>
+Function's preferred syntactic form.<sbr/>
+Boost.Signals 有两种句法形式：首选形式和兼容形式。 首选形式能更紧密地适合
C++语言，
+并减少需要考虑的独立模板参数的个数，往往能提高可读性；然而，由于编译器的错
误，
+首选形式并非所有平台都支持。 兼容形式可工作于 Boost.Signals 支持的所有编译
器。
+参考下表，以确定为你的编译器使用哪种句法形式。 Boost.Function 的用户请注
意，
+Signals 中的首选句法形式等效于 Function 的首选句法形式。</para>
<para>If your compiler does not appear in this list, please try the
preferred syntax and report your results to the Boost list so that
-we can keep this table up-to-date.</para>
+we can keep this table up-to-date.<sbr/>
+如果你的编译器不在这个清单上，请试用首选句法并向Boost列表报告你的结果，以使
我们能保持更新该表。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -67,7 +80,8 @@
</entry>
<entry>
<itemizedlist>
- <listitem><para><emphasis>Any compiler supporting the
preferred syntax</emphasis></para></listitem>
+ <listitem><para><emphasis>Any compiler supporting the
preferred syntax<sbr/>
+ 支持首选句法的任意编译器</emphasis></para></listitem>
<listitem><para>Microsoft Visual C++ 6.0,
7.0</para></listitem>
<listitem><para>Borland C++ 5.5.1</para></listitem>
<listitem><para>Sun WorkShop 6 update 2 C++
5.3</para></listitem>
@@ -80,7 +94,7 @@
</informaltable>
</section>
-<section><title>Hello, World! (Beginner)</title>
+<section><title>Hello, World! (Beginner 初级)</title>
<para>The following example writes "Hello, World!" using signals and
slots. First, we create a signal <code>sig</code>, a signal that
takes no arguments and has a void return value. Next, we connect
@@ -88,13 +102,16 @@
<code>connect</code> method. Finally, use the signal
<code>sig</code> like a function to call the slots, which in turns
invokes <code>HelloWorld::operator()</code> to print "Hello,
-World!".</para>
+World!".<sbr/>
+下例将使用信号和插槽写出“Hello, World!”。首先，我们创建信号
<code>sig</code>，
+该信号无参数并且返回值为空。接着，我们使用 <code>connect</code> 方法将
<code>hello</code> 函数对象连接到信号。
+最后，像函数一样使用信号 <code>sig</code> 来调用插槽，它将转而调用
<code>HelloWorld::operator()</code> 打印 “Hello, World!”。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -151,13 +168,15 @@
</informaltable>
</section>
-<section><title>Calling multiple slots</title>
-<section><title>Connecting multiple slots (Beginner)</title>
+<section><title>Calling multiple slots 调用多个插槽</title>
+<section><title>Connecting multiple slots (Beginner) 连接多个插槽（初级
）</title>
<para>Calling a single slot from a signal isn't very interesting, so
we can make the Hello, World program more interesting by splitting
the work of printing "Hello, World!" into two completely separate
slots. The first slot will print "Hello" and may look like
-this:</para>
+this:<sbr/>
+从信号调用单个插槽不是很有意思，因此我们将打印“Hello, World!”的工作拆分到两
个完全独立的插槽，
+让 Hello, World 程序更有趣点。 第一个插槽将打印“Hello”，可能看起来像这
样：</para>
<programlisting>
struct Hello
{
@@ -168,7 +187,8 @@
};
</programlisting>
<para>The second slot will print ", World!" and a newline, to complete
-the program. The second slot may look like this:</para>
+the program. The second slot may look like this:<sbr/>
+第二个插槽将打印“, World!”和换行，以完成该程序。第二个插槽可能看起来像这
样：</para>
<programlisting>
struct World
{
@@ -182,13 +202,16 @@
<code>sig</code> that takes no arguments and has a
<code>void</code> return value. This time, we connect both a
<code>hello</code> and a <code>world</code> slot to the same
-signal, and when we call the signal both slots will be called.</para>
+signal, and when we call the signal both slots will be called.<sbr/>
+和上个例子一样，我们创建信号 <code>sig</code>，它没有参数并且返回值为
<code>void</code>。
+这次，我们将 <code>hello</code> 和 <code>world</code> 插槽都连接到同一个信
号，
+当我们调用该信号，两个插槽都将会被调用。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -218,13 +241,14 @@
</tgroup>
</informaltable>
<para>By default, slots are called in first-in first-out (FIFO) order,
-so the output of this program will be as expected:</para>
+so the output of this program will be as expected:<sbr/>
+默认情况下，插槽以先进先出（FIFO）的次序被调用，因此该程序的输出应该
是：</para>
<programlisting>
Hello, World!
</programlisting>
</section>
-<section><title>Ordering slot call groups (Intermediate)</title>
+<section><title>Ordering slot call groups (Intermediate) 插槽调用组排序（中
级）</title>
<para>Slots are free to have side effects, and that can mean that some
slots will have to be called before others even if they are not connected
in that order. The Boost.Signals
library allows slots to be placed into groups that are ordered in
@@ -234,13 +258,18 @@
can supply an extra parameter at the beginning of the
<code>connect</code> call that specifies the group. Group values
are, by default, <code>int</code>s, and are ordered by the integer
-< relation. Here's how we construct Hello, World:</para>
+< relation. Here's how we construct Hello, World:<sbr/>
+插槽可以有副作用，这意味着某些插槽必须在另一些之前调用，即使它们不是按那个
次序连接的。
+Boost.Signals 库允许插槽进行分组，并按某种方式排序编组。 对于我们的 Hello,
World 程序，
+我们要“Hello”在“, World!”之前打印，所以我们将“Hello”放入一个组，该组将在“,
World!”所在组之前执行。
+为了做到这一点，我们可以在 <code>connect</code> 调用的头部提供一个额外的参
数，以指定编组。
+编组值默认为 <code>int</code>，并按整型的 < 关系排序。 我们这样构造
Hello, World：</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -280,7 +309,13 @@
alt="boost::signalN::connect">connect</methodname></code>, respectively),
and defaults to the end of the list. When
a group is specified, the final parameter describes where the slot
will be placed within the group ordering. If we add a new slot
-to our example like this:</para>
+to our example like this:<sbr/>
+该程序将正确打印出“Hello, World!”，因为 <code>Hello</code> 对象在组 0，它
在 <code>World</code> 对象所在的组 1 之前。
+编组参数实际上是可选的。在第一个 Hello World 例子中我们省略了它，因为当所有
的插槽都独立时，编组是不必要的。
+那么，如果我们混合调用使用和不使用编组参数的连接会怎样？ “未命名”插槽（即那
些连接时未指定组名的插槽）
+可置于插槽链表的头部或尾部（通过向 <code><methodname
alt="boost::signalN::connect">connect</methodname></code>
+分别传入 <code>boost::signals::at_front</code> 或
<code>boost::signals::at_back</code> 作为最后的参数），
+而默认为链表的结尾。当指定了编组时，最后的参数描述的是插槽在组内的次序。如
果在我们的例子中添加新的插槽，如下：</para>
<programlisting>
struct GoodMorning
{
@@ -292,7 +327,8 @@
sig.<methodname>connect</methodname>(GoodMorning());
</programlisting>
-<para>... we will get the result we wanted:</para>
+<para>... we will get the result we wanted:<sbr/>
+... 我们会得到想要的结果：</para>
<programlisting>
Hello, World!
... and good morning!
@@ -300,16 +336,19 @@
</section>
</section>
-<section><title>Passing values to and from slots</title>
-<section><title>Slot Arguments (Beginner)</title>
+<section><title>Passing values to and from slots 传值到插槽及回传</title>
+<section><title>Slot Arguments (Beginner) 插槽的参数（初级）</title>
<para>Signals can propagate arguments to each of the slots they call.
For instance, a signal that propagates mouse motion events might
want to pass along the new mouse coordinates and whether the mouse
-buttons are pressed.</para>
+buttons are pressed.<sbr/>
+信号可以向它们调用的每个插槽传递参数。例如，一个传递鼠标移动事件的信号可能
要传入新的鼠标坐标以及是否按了鼠标键。</para>
<para>As an example, we'll create a signal that passes two
<code>float</code> arguments to its slots. Then we'll create a few
slots that print the results of various arithmetic operations on
-these values.</para>
+these values.<sbr/>
+例如，我们创建一个信号，它将传入两个 float 参数到它的插槽。然后我们再创建几
个插槽，
+打印对这两个参数进行算术运算的各种结果。</para>
<programlisting>
void print_sum(float x, float y)
{
@@ -336,8 +375,8 @@
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -371,7 +410,8 @@
</tgroup>
</informaltable>
-<para>This program will print out the following:</para>
+<para>This program will print out the following:<sbr/>
+该程序将打印输出如下：</para>
<programlisting>
The sum is 8
The product is 15
@@ -385,10 +425,14 @@
float)></code> means that the signal has a <code>void</code>
return value and takes two <code>float</code> values. Any slot
connected to <code>sig</code> must therefore be able to take two
-<code>float</code> values.</para>
+<code>float</code> values.<sbr/>
+当像函数一样调用 <code>sig</code> 时，输入它的任何值都传给了每一个插槽。
+创建信号时，我们必须预先声明这些值的类型。类型
<code><classname>boost::signal</classname><void (float, float)></code>
+表明信号具有 <code>void</code> 返回值并接受两个 <code>float</code> 值。
+因此任何连接到 <code>sig</code> 的插槽都必须能够接受两个
<code>float</code> 值。</para>
</section>
-<section><title>Signal Return Values (Advanced)</title>
+<section><title>Signal Return Values (Advanced) 信号返回值（高级）</title>
<para>Just as slots can receive arguments, they can also return
values. These values can then be returned back to the caller of the
signal through a <firstterm>combiner</firstterm>. The combiner is a
mechanism
@@ -398,17 +442,23 @@
The single result is often a simple function of the results of the
slot calls: the result of the last slot call, the maximum value
returned by any slot, or a container of all of the results are some
-possibilities.</para>
+possibilities.<sbr/>
+正如插槽可以接收参数，它们也可以返回值。然后这些值可以通过 <firstterm>合并
器</firstterm> 返回给信号的调用者。
+合并器是这样一种工具，它接收插槽调用的结果（可能没有结果，也可能有100个结
果；程序运行时才知道），
+并且把它们合并成单一的结果返回给调用者。 该单一的结果往往是插槽调用结果的一
个简单函数，可能是：
+最后的插槽调用的结果、所有插槽返回值的最大值，或包含所有结果的容器。</para>
<para>We can modify our previous arithmetic operations example
slightly so that the slots all return the results of computing the
product, quotient, sum, or difference. Then the signal itself can
-return a value based on these results to be printed:</para>
+return a value based on these results to be printed:<sbr/>
+我们可以稍微修改前面的算术运算的例子，使插槽分别返回加减乘除的计算结果。
+然后信号本身就可以根据这些结果返回一个值，并打印出来。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -458,10 +508,15 @@
<code><classname>boost::signal</classname></code> class template) is to
call all slots and
then return the result returned by the last slot called. This
behavior is admittedly silly for this example, because slots have
-no side effects and the result is the last slot connect.</para>
+no side effects and the result is the last slot connect.<sbr/>
+该例程将输出 <code>2</code>。这是因为具有返回类型（<code>float</code>，
+即输入 <code><classname>boost::signal</classname></code> 类模板的第一个模板
参数）的信号的默认行为是，
+调用所有的插槽，然后返回最后一个被调用插槽的结果。对本例来说，该行为确实有
点傻，
+因为这些插槽没有副作用，所以结果就是最后连接的插槽。</para>
<para>A more interesting signal result would be the maximum of the
values returned by any slot. To do this, we create a custom
-combiner that looks like this:</para>
+combiner that looks like this:<sbr/>
+求所有插槽返回值的最大值，这样的信号结果才有点意思。为些，我们创建一个自定
义合并器如下：</para>
<programlisting>
template<typename T>
struct maximum
@@ -496,16 +551,23 @@
iterator sequence <code>[first, last)</code> that includes the
results of calling all of the slots. <code>maximum</code> uses this
input iterator sequence to calculate the maximum element, and
-returns that maximum value.</para>
+returns that maximum value.<sbr/>
+<code>maximum</code> 类模板就像一个函数对象。它的结果类型由其模板参数给出，
+并且它正是基于该类型计算最大值（例如，<code>maximum<float></code> 将
在一系列
+<code>float</code> 中查找最大的 <code>float</code>）。当调用
<code>maximum</code> 对象时，
+将给出一个输入迭代器序列 <code>[first, last)</code>，其中包含了所有插槽调用
的结果。
+<code>maximum</code> 利用该输入迭代器序列来计算最大元素，并返回那个最大值。
</para>
<para>We actually use this new function object type by installing it
as a combiner for our signal. The combiner template argument
-follows the signal's calling signature:</para>
+follows the signal's calling signature:<sbr/>
+我们要把这个新的函数对象作为合并器安装到我们的信号，才能实际使用它。
+合并器模板参数跟在信号的调用签名式之后。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -528,7 +590,8 @@
</informaltable>
<para>Now we can connect slots that perform arithmetic functions and
-use the signal:</para>
+use the signal:<sbr/>
+现在我们可以连接执行算术功能的插槽并使用信号了：</para>
<programlisting>
sig.<methodname>connect</methodname>(&quotient);
sig.<methodname>connect</methodname>(&product);
@@ -540,10 +603,14 @@
<para>The output of this program will be <code>15</code>, because
regardless of the order in which the slots are connected, the product
of 5 and 3 will be larger than the quotient, sum, or
-difference.</para>
+difference.<sbr/>
+该程序的输出为 <code>15</code>，因为不管插槽的连接次序如何，
+5 和 3 的乘积将大于商、和，或差。</para>
<para>In other cases we might want to return all of the values
computed by the slots together, in one large data structure. This
-is easily done with a different combiner:</para>
+is easily done with a different combiner:<sbr/>
+在其他情况下，我们可能需要同时返回插槽计算的所有值，如保存在一个大型的数据
结构中。
+用一个不同的合并器就可以轻松做到：</para>
<programlisting>
template<typename Container>
struct aggregate_values
@@ -558,14 +625,15 @@
};
</programlisting>
<para>
-Again, we can create a signal with this new combiner:
+Again, we can create a signal with this new combiner: <sbr/>
+我们再次用这个新的合并器创建信号：
</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -613,7 +681,11 @@
also be the <code>value_type</code> of the input iterators passed
to the combiner. The combiner itself is a function object and its
<code>result_type</code> member type becomes the return type of the
-signal.</para>
+signal.<sbr/>
+该程序的输出将包含 15、8、1.6667，和 2。有趣的是，<code>signal</code> 类的
第一个模板参数，
+<code>float</code>，竟然不是信号的返回类型。相反，该参数是所连接插槽的返回
类型，
+并且它也是传入合并器的输入迭代器的 <code>value_type</code>。合并器本身是个
函数对象，
+并且它的 <code>result_type</code> 成员类型将成为信号的返回类型。</para>
<para>The input iterators passed to the combiner transform dereference
operations into slot calls. Combiners therefore have the option to
invoke only some slots until some particular criterion is met. For
@@ -626,7 +698,12 @@
return when the value is acceptable. The following combiner returns
the first non-NULL pointer to a <code>FulfilledRequest</code> data
structure, without asking any later slots to fulfill the
-request:</para>
+request:<sbr/>
+传给合并器的输入迭代器会将解引用操作转换为插槽调用。因此合并器可选择仅调用
某些符合特定条件的插槽。
+例如，在分布计算系统中，合并器可能会询问每个远程系统能否处理请求。对于一个
特定请求，
+仅需一个远程系统进行处理，因此当一个远程系统接受该工作后，我们将不再要求任
何其他远程系统来做同一个任务。
+这样一个合并器只需检查迭代器解引用的返回值，并当该值可以接受时就返回。
+以下的合并器返回第一个指向 <code>FulfilledRequest</code> 数据结构的非空指
针，而不必要求任何以后的插槽来完成请求：</para>
<programlisting>
struct DistributeRequest {
typedef FulfilledRequest* result_type;
@@ -646,12 +723,14 @@
</section>
</section>
-<section><title>Connection Management</title>
-<section><title>Disconnecting Slots (Beginner)</title>
+<section><title>Connection Management 连接管理</title>
+<section><title>Disconnecting Slots (Beginner) 断开插槽（初级）</title>
<para>Slots aren't expected to exist indefinately after they are
connected. Often slots are only used to receive a few events and
are then disconnected, and the programmer needs control to decide
-when a slot should no longer be connected.</para>
+when a slot should no longer be connected.<sbr/>
+插槽在连接之后不必无限期地存在。插槽往往只是用来接收一些事件然后断开，
+当插槽不再需要保持连接时，程序员可以做出决定并控制。</para>
<para>The entry point for managing connections explicitly is the
<code><classname>boost::signals::connection</classname></code> class. The
<code><classname>connection</classname></code> class uniquely represents
the connection
@@ -661,7 +740,12 @@
disconnects the signal and slot if they are connected before it is
called. Each call to the signal's <code>connect()</code> method
returns a connection object, which can be used to determine if the
-connection still exists or to disconnect the signal and slot.</para>
+connection still exists or to disconnect the signal and slot.<sbr/>
+显式管理连接的入口点是
<code><classname>boost::signals::connection</classname></code> 类。
+<code><classname>connection</classname></code> 类唯一代表了特定信号与特定插
槽之间的连接。
+<code><methodname
alt="connection::connected">connected</methodname>()</code> 方法检查信号与插
槽是否仍保持连接，
+如果信号与插槽是连接着的，<code><methodname
alt="connection::disconnect">disconnect()</methodname></code> 方法断开它们的
连接。
+每次调用信号的 <code>connect()</code> 方法，就返回一个连接对象，该对象用于
确定连接是否仍然存在，或者用于断开信号和插槽。</para>
<programlisting>
boost::signals::connection c =
sig.<methodname>connect</methodname>(HelloWorld());
if (c.<methodname>connected</methodname>()) {
@@ -676,14 +760,17 @@
</programlisting>
</section>
-<section><title>Blocking Slots (Beginner)</title>
+<section><title>Blocking Slots (Beginner) 阻塞插槽（初级）</title>
<para>Slots can be temporarily "blocked", meaning that they will be
ignored when the signal is invoked but have not been disconnected. The
<code><methodname>block</methodname></code> member function
temporarily blocks a slot, which can be unblocked via
<code><methodname>unblock</methodname></code>. Here is an example of
-blocking/unblocking slots:</para>
+blocking/unblocking slots:<sbr/>
+插槽可以被临时“阻塞”，即当信号被调用时，这些插槽将被忽略，但并没有被断开。
+<code><methodname>block</methodname></code> 成员函数临时地阻塞一个插槽，
+可通过 <code><methodname>unblock</methodname></code> 解除阻塞。这是一个阻塞
/开启插槽的例子：</para>
<programlisting>
boost::signals::connection c =
sig.<methodname>connect</methodname>(HelloWorld());
@@ -699,12 +786,15 @@
</section>
-<section><title>Scoped connections (Intermediate)</title>
+<section><title>Scoped connections (Intermediate) 域内连接（中级）</title>
<para>The <code>boost::signals::scoped_connection</code> class
references a signal/slot connection that will be disconnected when
the <code>scoped_connection</code> class goes out of scope. This
ability is useful when a connection need only be temporary,
-e.g.,</para>
+e.g.,<sbr/>
+<code>boost::signals::scoped_connection</code> 类引用了一个信号/插槽的连
接，
+当 <code>scoped_connection</code> 类出作用域时，该连接将会被断开。
+当仅需临时连接时，该功能很有用，如：</para>
<programlisting>
{
boost::signals::scoped_connection c =
sig.<methodname>connect</methodname>(ShortLived());
@@ -714,20 +804,21 @@
</programlisting>
</section>
-<section><title>Disconnecting equivalent slots (Intermediate)</title>
+<section><title>Disconnecting equivalent slots (Intermediate) 断开等价的插
槽（中级）</title>
<para>One can disconnect slots that are equivalent to a given function
object using a form of the
<code><methodname>disconnect</methodname></code> method, so long as
the type of the function object has an accessible <code>==</code>
-operator. For instance:
-
+operator. For instance:<sbr/>
+你可以使用 <code><methodname>disconnect</methodname></code> 方法断开与给定
函数对象等价的多个插槽，
+只要该函数对象的类型具有可访问的 <code>==</code> 运算符。例如：
</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -767,20 +858,23 @@
</section>
-<section><title>Automatic connection management (Intermediate)</title>
+<section><title>Automatic connection management (Intermediate) 自动连接管理
（中级）</title>
<para>Boost.Signals can automatically track the lifetime of objects
involved in signal/slot connections, including automatic
disconnection of slots when objects involved in the slot call are
destroyed. For instance, consider a simple news delivery service,
where clients connect to a news provider that then sends news to
all connected clients as information arrives. The news delivery
-service may be constructed like this: </para>
+service may be constructed like this: <sbr/>
+Boost.Signals 能自动跟踪信号/插槽连接中所涉及对象的生命期，包括当插槽调用中
涉及的对象销毁时自动断开插槽。
+例如，考虑一个简单的新闻发送服务，其中客户会连接到新闻提供者，而新闻提供者
一有信息到达，就发送新闻到所有连接的客户。
+该新闻发送服务可能像这样构造：</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -808,7 +902,8 @@
function object that can receive news items to the
<code>deliverNews</code> signal. For instance, we may have a
special message area in our application specifically for news,
-e.g.,:</para>
+e.g.,:<sbr/>
+希望接收新闻更新的客户只需连接一个函数对象，该对象可以接收传给
<code>deliverNews</code> 信号的新闻条目，例如：</para>
<programlisting>
struct NewsMessageArea : public MessageArea
{
@@ -837,7 +932,11 @@
<code>newsMessageArea</code> is destroyed. The
<code>NewsMessageArea</code> class is made trackable by deriving
publicly from the <code>boost::signals::trackable</code> class,
-e.g.:</para>
+e.g.:<sbr/>
+不过，如果用户关闭新闻讯息区，销毁了 <code>deliverNews</code> 所知的
<code>newsMessageArea</code> 对象，那会怎么样？
+最有可能的是产生段错误。然而，你只需在使用 Boost.Signals 时，让
<code>NewsMessageArea</code> <emphasis>可跟踪</emphasis>，
+那么当 <code>newsMessageArea</code> 被销毁时，调用
<code>newsMessageArea</code> 的插槽就会被断开。
+通过公有继承自 <code>boost::signals::trackable</code>
类，<code>NewsMessageArea</code> 类就会变成可跟踪的，例如：</para>
<programlisting>
struct NewsMessageArea : public MessageArea, public
boost::signals::trackable
{
@@ -848,54 +947,71 @@
<code>trackable</code> objects in making slot connections: function
objects built using Boost.Bind are understood, such that pointers
or references to <code>trackable</code> objects passed to
-<code>boost::bind</code> will be found and tracked.</para>
+<code>boost::bind</code> will be found and tracked.<sbr/>
+目前，用 <code>trackable</code> 对象制作插槽连接有个重要的限制：它理解使用
Boost.Bind 构建的函数对象，
+如传入 <code>boost::bind</code> 的 <code>trackable</code> 对象指针或引用将
会被发现和跟踪。</para>
<para><emphasis role="bold">Warning</emphasis>: User-defined function
objects and function
objects from other libraries (e.g., Boost.Function or Boost.Lambda)
do not implement the required interfaces for <code>trackable</code>
object detection, and <emphasis>will silently ignore any bound trackable
objects</emphasis>. Future versions of the Boost libraries will address
-this limitation.</para>
+this limitation.<sbr/>
+<emphasis role="bold">警告</emphasis>：用户自定义函数对象和来自其他库的函数
对象（例如来自 Boost.Function 或 Boost.Lambda）， 没有实现所要求的
<code>trackable</code> 对象检测接口，<emphasis>将会默默地忽略任何绑定的可跟
踪对象</emphasis>。 Boost库的未来版本将会解除该限制。</para>
</section>
-<section><title>When can disconnections occur? (Intermediate)</title>
+<section><title>When can disconnections occur? (Intermediate) 何时断
开？（中级）</title>
<para>Signal/slot disconnections occur when any of these conditions
-occur:</para>
+occur:<sbr/>
+以下任一条件发生时，信号/插槽将断开：</para>
<itemizedlist>
<listitem><para>The connection is explicitly disconnected via the
connection's
<code>disconnect</code> method directly, or indirectly via the
signal's <code>disconnect</code> method or
-<code>scoped_connection</code>'s destructor.</para></listitem>
+<code>scoped_connection</code>'s destructor.<sbr/>
+连接被显式地断开：直接通过连接的 <code>disconnect</code> 方法， 或间接地通
过信号的
+<code>disconnect</code> 方法或 <code>scoped_connection</code> 的析构函数。
</para></listitem>
<listitem><para>A <code>trackable</code> object bound to the slot is
-destroyed.</para></listitem>
-<listitem><para>The signal is destroyed.</para></listitem></itemizedlist>
+destroyed.<sbr/>
+绑定于插槽的 <code>trackable</code> 对象被销毁。</para></listitem>
+<listitem><para>The signal is destroyed.<sbr/>
+信号被销毁。</para></listitem></itemizedlist>
<para>These events can occur at any time without disrupting a signal's
calling sequence. If a signal/slot connection is disconnected at
any time during a signal's calling sequence, the calling sequence
will still continue but will not invoke the disconnected slot.
Additionally, a signal may be destroyed while it is in a calling
sequence, and which case it will complete its slot call sequence
-but may not be accessed directly.</para>
+but may not be accessed directly.<sbr/>
+这些事件可以发生于任何时间，而不会破坏信号的调用序列。如果信号/插槽的连接在
信号调用序列的任意时刻被断开，
+调用序列仍将继续，只是不会调用被断开的插槽。此外，信号可以在调用序列中间被
销毁，这时，
+它将完成其插槽调用序列，只是不可以被直接访问。</para>
<para>Signals may be invoked recursively (e.g., a signal A calls a
slot B that invokes signal A...). The disconnection behavior does
not change in the recursive case, except that the slot calling
sequence includes slot calls for all nested invocations of the
-signal.</para>
+signal.<sbr/>
+信号可以被递归调用（例如，信号A调用插槽B，而插槽B又调用信号A……）。递归情况
下，
+断开的行为不会改变，只是插槽调用序列包括所有嵌套的信号调用。</para>
</section>
-<section><title>Passing slots (Intermediate)</title>
+<section><title>Passing slots (Intermediate) 传递插槽（中级）</title>
<para>Slots in the Boost.Signals library are created from arbitrary
function objects, and therefore have no fixed type. However, it is
commonplace to require that slots be passed through interfaces that
cannot be templates. Slots can be passed via the
<code>slot_type</code> for each particular signal type and any
function object compatible with the signature of the signal can be
-passed to a <code>slot_type</code> parameter. For instance:</para>
+passed to a <code>slot_type</code> parameter. For instance:<sbr/>
+Boost.Signals 库中的插槽可以从任意的函数对象创建，因此没有固定的类型。
+不过通常要求通过不可模板化的接口传递插槽。对于每个特定的信号类型，
+都可以通过 <code>slot_type</code> 传递插槽，而与信号的签名式兼容的任意函数
对象，
+都可以传给 <code>slot_type</code> 参数。例如：</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -970,19 +1086,24 @@
<para>The <code>doOnClick</code> method is now functionally equivalent
to the <code>connect</code> method of the <code>onClick</code>
signal, but the details of the <code>doOnClick</code> method can be
-hidden in an implementation detail file.</para>
+hidden in an implementation detail file.<sbr/>
+<code>doOnClick</code> 方法现在功能上等效于 <code>onClick</code> 信号的
<code>connect</code> 方法，
+但是 <code>doOnClick</code> 方法的细节可以隐藏于细节实现文件中。 </para>
</section>
</section>
<section>
- <title>Example: Document-View</title>
+ <title>Example: Document-View 例子：文档-视图</title>
<para>Signals can be used to implement flexible Document-View
architectures. The document will contain a signal to which each of
the views can connect. The following <code>Document</code> class
defines a simple text document that supports mulitple views. Note
that it stores a single signal to which all of the views will be
- connected.</para>
+ connected.<sbr/>
+ 信号可用于实现灵活的文档-视图（Document-View）架构。文档包含一个信号，
+ 而每个视图连接该信号。下面的 <code>Document</code> 类定义了一个简单的支持
多视图的文本文档。
+ 注意它保存了一个单一的信号，所有视图都连接到该信号。</para>
<programlisting>class Document
{
@@ -1024,7 +1145,10 @@
views can derive. This isn't strictly required, but it keeps the
Document-View logic separate from the logic itself. Note that the
constructor just connects the view to the document and the
- destructor disconnects the view.</para>
+ destructor disconnects the view.<sbr/>
+ 接下来，我们可以定义视图的基类 <code>View</code>。这并非严格需要，
+ 但它能让文档-视图的逻辑与逻辑本身分离。注意构造函数仅仅连接视图到文档，
+ 而析构函数断开视图。</para>
<programlisting>
class View
@@ -1053,7 +1177,8 @@
<para>Finally, we can begin to define views. The
following <code>TextView</code> class provides a simple view of the
- document text.</para>
+ document text.<sbr/>
+ 最后，我们可以开始定义视图。下面的 <code>TextView</code> 类提供了文档文
本的一个简单视图。</para>
<programlisting>class TextView : public View
{
@@ -1070,7 +1195,8 @@
<para>Alternatively, we can provide a view of the document
translated into hex values using the <code>HexView</code>
- view:</para>
+ view:<sbr/>
+ 此外，我们可以提供文档翻译成16进制后的视图，如 <code>HexView</code> 视
图：</para>
<programlisting>class HexView : public View
{
@@ -1094,7 +1220,8 @@
<para>To tie the example together, here is a
simple <code>main</code> function that sets up two views and then
- modifies the document:</para>
+ modifies the document:<sbr/>
+ 为了把例子串起来，有个简单的 <code>main</code> 函数，它建立了两个视
图，然后更改文档：</para>
<programlisting>int main(int argc, char* argv[])
{
@@ -1108,18 +1235,23 @@
<para>The complete example source, contributed by Keith MacDonald,
is available in <ulink
-
url="../../libs/signals/example/doc_view.cpp"><code>libs/signals/example/doc_view.cpp</code></ulink>.</para>
+
url="../../libs/signals/example/doc_view.cpp"><code>libs/signals/example/doc_view.cpp</code></ulink>.<sbr/>
+ 完整的例程源码，由 Keith MacDonald 提供，在 <ulink
url="../../libs/signals/example/doc_view.cpp">
+ <code>libs/signals/example/doc_view.cpp</code></ulink>。</para>
</section>
<section>
- <title>Linking against the Signals library</title>
+ <title>Linking against the Signals library 链接信号库</title>
<para>Part of the Boost.Signals library is compiled into a binary
library that must be linked into your application to use
Signals. Please refer to
the <ulink url="../../more/getting_started.html">Getting
Started</ulink>
guide. You will need to link against the <code>boost_signals</code>
- library.</para>
+ library.<sbr/>
+ Boost.Signals 库要编译成二进制库， 为使用信号库，应用程序必须链接该二进制
库。请参考
+ <ulink url="../../more/getting_started.html">Getting Started</ulink> 指
导。
+ 你将需要链接 <code>boost_signals</code> 库。</para>
</section>
</section>
=======================================
--- /trunk/libs/signals2/doc/examples.xml Thu May 7 20:34:38 2009
+++ /trunk/libs/signals2/doc/examples.xml Sat Jan 23 06:27:10 2010
@@ -9,18 +9,19 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.examples">
- <title>Example programs</title>
+ <title>Example programs 例程</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
<section id="signals2.examples.misc">
- <title>Miscellaneous Tutorial Examples</title>
+ <title>Miscellaneous Tutorial Examples 各种教学示例</title>
<section id="signals2.examples.tutorial.hello_world_slot">
<title>hello_world_slot</title>
<para>
This example is a basic example of connecting a slot to a signal
- and then invoking the signal.
+ and then invoking the signal.<sbr/>
+ 本例是把插槽连接到信号并调用信号的基本例子。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/hello_world_slot.cpp">hello_world_slot.cpp</ulink>.
@@ -30,7 +31,8 @@
<title>hello_world_multi_slot</title>
<para>
This example extends the hello_world_slot example slightly by
connecting more than one
- slot to the signal before invoking it.
+ slot to the signal before invoking it.<sbr/>
+ 本例稍稍扩展了 hello_world_slot 的例子，它所调用的信号连接了多个插
槽。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/hello_world_multi_slot.cpp">hello_world_multi_slot.cpp</ulink>.
@@ -41,7 +43,8 @@
<para>
This example extends the hello_world_multi_slot example slightly by
using slot groups to specify
- the order slots should be invoked.
+ the order slots should be invoked.<sbr/>
+ 本例稍稍扩展了 hello_world_multi_slot 的例子，它使用插槽组来指定插
槽调用的顺序。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/ordering_slots.cpp">ordering_slots.cpp</ulink>.
@@ -50,7 +53,8 @@
<section id="signals2.examples.tutorial.slot_arguments">
<title>slot_arguments</title>
<para>
- The slot_arguments program shows how to pass arguments from a
signal invocation to slots.
+ The slot_arguments program shows how to pass arguments from a
signal invocation to slots.<sbr/>
+ 程序 slot_arguments 显示了如何将信号调用的参数传递给插槽。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/slot_arguments.cpp">slot_arguments.cpp</ulink>.
@@ -60,7 +64,8 @@
<title>signal_return_value</title>
<para>
This example shows how to return a value from slots to the signal
invocation.
- It uses the default <classname>optional_last_value</classname>
combiner.
+ It uses the default <classname>optional_last_value</classname>
combiner.<sbr/>
+ 本例显示了如何从插槽向信号调用返回一个值。它使用了默认的
<classname>optional_last_value</classname> 合并器。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/signal_return_value.cpp">signal_return_value.cpp</ulink>.
@@ -70,7 +75,8 @@
<title>custom_combiners</title>
<para>
This example shows more returning of values from slots to the
signal invocation.
- This time, custom combiners are defined and used.
+ This time, custom combiners are defined and used.<sbr/>
+ 本例进一步显示了从插槽向信号调用返回值。这次，定义并使用了自定义合
并器。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/custom_combiners.cpp">custom_combiners.cpp</ulink>.
@@ -80,7 +86,8 @@
<title>disconnect_and_block</title>
<para>
This example demonstrates various means of manually disconnecting
slots, as well as temporarily
- blocking them via <classname>shared_connection_block</classname>.
+ blocking them via
<classname>shared_connection_block</classname>.<sbr/>
+ 本例演示了手工断开插槽的各样方法， 以及通过
<classname>shared_connection_block</classname> 临时阻塞插槽。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/disconnect_and_block.cpp">disconnect_and_block.cpp</ulink>.
@@ -90,7 +97,8 @@
<title>passing_slots</title>
<para>
This example demonstrates the passing of slot functions to a
private signal
- through a non-template interface.
+ through a non-template interface.<sbr/>
+ 本例演示了通过非模板接口，向私有的信号传递插槽函数。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/passing_slots.cpp">passing_slots.cpp</ulink>.
@@ -101,7 +109,9 @@
<para>
This example demonstrates connecting an extended slot to a
signal. An extended slot
accepts a reference to its invoking signal-slot connection as an
additional argument,
- permitting the slot to temporarily block or permanently disconnect
itself.
+ permitting the slot to temporarily block or permanently disconnect
itself.<sbr/>
+ 本例演示了在信号上连接一个扩展插槽。扩展插槽可接受一个附加参数，该
参数指向产生调用的信号-插槽连接，
+ 以允许插槽临时阻塞或永久断开自身。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/extended_slot.cpp">extended_slot.cpp</ulink>.
@@ -109,14 +119,16 @@
</section>
</section>
<section id="signals2.examples.document-view">
- <title>Document-View</title>
+ <title>Document-View 文档-视图</title>
<section id="signals2.examples.document-view.doc_view">
<title>doc_view</title>
<para>
This is the document-view example program which is described in the
<link linkend="signals2.tutorial.document-view">tutorial</link>.
It shows
usage of a signal and slots to implement two different views of
- a text document.
+ a text document.<sbr/>
+ 这就是 <link linkend="signals2.tutorial.document-view">教程</link>
中所述的 document-view 例程。
+ 它显示了如何用信号插槽实现文本文档的两个不同视图。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/doc_view.cpp">doc_view.cpp</ulink>.
@@ -126,7 +138,8 @@
<title>doc_view_acm</title>
<para>
This program modifies the original doc_view.cpp example to employ
- automatic connection management.
+ automatic connection management.<sbr/>
+ 本程序更改了原来的 doc_view.cpp 例子， 它采用了自动连接管理。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/doc_view_acm.cpp">doc_view_acm.cpp</ulink>.
@@ -136,7 +149,8 @@
<title>doc_view_acm_deconstruct</title>
<para>
This program modifies the doc_view_acm.cpp example to use
postconstructors
- and the <functionname>deconstruct()</functionname> factory
function.
+ and the <functionname>deconstruct()</functionname> factory
function.<sbr/>
+ 本程序更改了 doc_view_acm.cpp 例子，以使用后构造器和
<functionname>deconstruct()</functionname> 工厂函数。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/doc_view_acm_deconstruct.cpp">doc_view_acm_deconstruct.cpp</ulink>.
@@ -144,12 +158,13 @@
</section>
</section>
<section id="signals2.examples.deconstruct">
- <title>Postconstructors and Predestructors with
<code>deconstruct()</code></title>
+ <title>Postconstructors and Predestructors with
<code>deconstruct()</code> 用<code>deconstruct()</code>定义后构造器和预析构
器</title>
<section id="signals2.examples.deconstruct.postconstructor_ex1">
<title>postconstructor_ex1</title>
<para>
This program is a basic example of how to define a class with a
postconstructor which
- uses <functionname>deconstruct()</functionname> as its factory
function.
+ uses <functionname>deconstruct()</functionname> as its factory
function.<sbr/>
+ 如何以 <functionname>deconstruct()</functionname> 为工厂函数，来定
义具有后构造器的类？本程序就是一个基本例子。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/postconstructor_ex1.cpp">postconstructor_ex1</ulink>.
@@ -160,7 +175,9 @@
<para>
This program extends the postconstructor_ex1 example slightly, by
additionally passing arguments from
the <functionname>deconstruct()</functionname> call through to the
class' constructor
- and postconstructor.
+ and postconstructor.<sbr/>
+ 本程序稍稍扩展了 postconstructor_ex1 的例子，它可以将
<functionname>deconstruct()</functionname>
+ 的调用参数传递给类的构造函数和后构造器。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/postconstructor_ex2.cpp">postconstructor_ex2</ulink>.
@@ -170,7 +187,8 @@
<title>predestructor_example</title>
<para>
This program is a basic example of how to define a class with a
predestructor which
- uses <functionname>deconstruct()</functionname> as its factory
function.
+ uses <functionname>deconstruct()</functionname> as its factory
function.<sbr/>
+ 如何以 <functionname>deconstruct()</functionname> 为工厂函数，来定
义具有预析构器的类？本程序就是一个基本例子。
</para>
<para>
Download <ulink
url="boost:/libs/signals2/example/predestructor_example.cpp">predestructor_example</ulink>.
=======================================
--- /trunk/libs/signals2/doc/faq.xml Thu May 7 20:34:38 2009
+++ /trunk/libs/signals2/doc/faq.xml Sat Jan 23 06:27:10 2010
@@ -9,7 +9,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.faq">
- <title>Frequently Asked Questions</title>
+ <title>Frequently Asked Questions 常见问题</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
@@ -18,19 +18,23 @@
<qandaentry>
<question>
<para>Don't noncopyable signal semantics mean that a class
- with a signal member will be noncopyable as well?</para>
+ with a signal member will be noncopyable as well?<sbr/>
+ singal 不可复制的语义是否意味着带有 signal 成员的类也是不可复制
的？</para>
</question>
<answer>
<para>No. The compiler will not be able to generate a copy
constructor or copy assignment operator for your class if it
has a signal as a member, but you are free to write your own
copy constructor and/or copy assignment operator. Just don't
- try to copy the signal.</para>
+ try to copy the signal.<sbr/>
+ 否。如果你的类有个 signal 成员，编译器不能为它生成一个复制构造函数
或复制赋值操作符，
+ 是你可以自己编写复制构造函数和赋值操作符。只是不要试图复制那个
signal。</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>Is Boost.Signals2 thread-safe?</para>
+ <para>Is Boost.Signals2 thread-safe?<sbr/>
+ Boost.Signals2 是否线程安全？</para>
</question>
<answer>
<para>
@@ -43,10 +47,16 @@
<methodname alt="slotN::track">track</methodname>() method
before the slot is connected.
The <classname>trackable</classname> scheme of automatic
connection management
is NOT thread-safe, and is only provided to ease porting of
single-threaded
- code from Boost.Signals to Boost.Signals2.
+ code from Boost.Signals to Boost.Signals2.<sbr/>
+ 是的，只要 Mutex 模板参数不是被设为像
<classname>boost::signals2::dummy_mutex</classname> 这样的假互斥体类型。
+ 此外，如果您的插槽依赖的对象可能在信号调用的同时被销毁，您将需要
使用自动连接管理。
+ 这就是说，在插槽连接之前，需要由
<classname>shared_ptr</classname> 拥有对象，并传递给插槽的
+ <methodname alt="slotN::track">track</methodname>() 方法。自动连
接管理的 <classname>trackable</classname>
+ 方案不是线程安全的，它仅仅用于方便移植单线程代码从 Boost.Signals
到 Boost.Signals2。
</para>
<para>See the documentation section on <link
linkend="signals2.thread-safety">thread-safety</link>
- for more information.
+ for more information.<sbr/>
+ 详情请参阅文档 <link linkend="signals2.thread-safety">线程安全性
</link> 一节。
</para>
</answer>
</qandaentry>
=======================================
--- /trunk/libs/signals2/doc/introduction.xml Thu May 7 20:34:38 2009
+++ /trunk/libs/signals2/doc/introduction.xml Sat Jan 23 06:27:10 2010
@@ -9,14 +9,17 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $">
- <title>Introduction</title>
+ <title>Introduction 介绍</title>
<para>The Boost.Signals2 library is an implementation of a managed
signals and slots system. Signals represent callbacks with multiple
targets, and are also called publishers or events in similar
systems. Signals are connected to some set of slots, which are
callback receivers (also called event targets or subscribers), which
- are called when the signal is "emitted."</para>
+ are called when the signal is "emitted."<sbr/>
+ Boost.Signals2 库实现了一个可控的信号插槽系统。信号代表了具有多个目标的回
调，
+ 在类似的系统中也称为发布者或事件。信号与某组插槽相连接，插槽即回调的接收
者
+ （也称为事件目标或订阅者），它们在信号“发出”时被调用。</para>
<para>Signals and slots are managed, in that signals and slots (or,
more properly, objects that occur as part of the slots) can track
@@ -24,13 +27,18 @@
connections when either is destroyed. This enables the user to make
signal/slot connections without expending a great effort to manage the
lifetimes of those connections with regard to the lifetimes of all
- objects involved.</para>
+ objects involved.<sbr/>
+ 信号和插槽是可控的，因为信号和插槽（或严格地说是作为插槽出现的对象）跟踪
所有的连接，
+ 并能够在信号或插槽销毁时自动断开信号/插槽的连接。这让使用者能够在建立信号
/插槽连接的同时，
+ 不必费力地根据相关对象的生命期去管理那些连接的生命期。</para>
<para>When signals are connected to multiple slots, there is a
question regarding the relationship between the return values of the
slots and the return value of the signals. Boost.Signals2 allows the
user to specify the manner in which multiple return values are
- combined.</para>
+ combined.<sbr/>
+ 当信号连接多个插槽时，插槽的返回值和信号的返回值之间是什么关系呢？这是个
问题。
+ Boost.Signals2 允许用户合并多个返回值，并指定合并的方式。</para>
<section>
<title>Signals2</title>
@@ -41,6 +49,9 @@
Frank Mori Hess. Acknowledgements are also due to Timmo Stange, Peter
Dimov, and Gottlob Frege for ideas and feedback, and to Douglas Gregor
for the original version of Boost.Signals this effort was based on.
- </para>
+ <sbr/>
+ 本文描述的是原 Boost.Signals 库的一个线程安全的变体。接口有所更改以支持
线程安全，
+ 主要是在自动连接管理方面。本实现由 Frank Mori Hess 编写。同时感谢
Timmo Stange、Peter Dimov，
+ 和 Gottlob Frege 的意见和反馈，并感谢 Douglas Gregor，基于他的
Boost.Signals 才会有这个成果。</para>
</section>
</section>
=======================================
--- /trunk/libs/signals2/doc/porting.xml Thu May 7 20:34:38 2009
+++ /trunk/libs/signals2/doc/porting.xml Sat Jan 23 06:27:10 2010
@@ -7,15 +7,21 @@
Distributed under the Boost Software License, Version 1.0. (See
accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
-<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.porting">
- <title>Porting from Boost.Signals to Boost.Signals2</title>
+<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.api_changes">
+ <title>Signals2 API Changes</title>
+ <using-namespace name="boost::signals2"/>
+ <using-namespace name="boost"/>
+ <section id="signals2.porting">
+ <title>Porting from Boost.Signals to Boost.Signals2 从Boost.Signals向
Boost.Signals2移植</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
<para>The changes made to the Boost.Signals2 API compared to the
original Boost.Signals
library are summarized below. We also provide some notes on
- dealing with each change while porting existing Boost.Signals code to
Boost.Signals2.
+ dealing with each change while porting existing Boost.Signals code to
Boost.Signals2.<sbr/>
+ 与原 Boost.Signals 库相比，Boost.Signals2 API 所作的更改总结如下。我们
还提供了一些说明，
+ 说明当现有 Boost.Signals 代码移植到 Boost.Signals2 时，如何处理每一个变
化。
</para>
<itemizedlist>
<listitem>
@@ -23,7 +29,11 @@
to avoid conflict with the original Boost.Signals implementation,
as well as the Qt "signals" macro.
All the Boost.Signals2 classes are inside the
<code>boost::signals2</code> namespace,
unlike the original Boost.Signals which has some classes in the
<code>boost</code>
- namespace in addition to its own <code>boost::signals</code>
namespace.
+ namespace in addition to its own <code>boost::signals</code>
namespace.<sbr/>
+ 名字空间 <code>boost::signals</code> 已被
<code>boost::signals2</code> 取代，
+ 以避免与原 Boost.Signals 实现以及 Qt 的“signals”宏冲突。所有
Boost.Signals2 的类都在
+ <code>boost::signals2</code> 名字空间中，不像原 Boost.Signals 除了
其本身的 <code>boost::signals</code> 名字空间，
+ 有某些类在 <code>boost</code> 名字空间。
</para>
<para>
The Boost.Signals2 header files are contained in the
@@ -32,21 +42,30 @@
for the convenience header <code>boost/signals2.hpp</code> are
inside the
<code>boost/signals2/</code> subdirectory, unlike the original
Boost.Signals which
keeps a few headers in the parent <code>boost/</code> directory
- in addition to its own <code>boost/signals/</code> subdirectory.
+ in addition to its own <code>boost/signals/</code>
subdirectory.<sbr/>
+ Boost.Signals2 头文件位于 <code>boost/signals2/</code> 子目录，而不
是原 Boost.Signals 所使用的
+ <code>boost/signals</code> 子目录。此外，除了便捷头文件
<code>boost/signals2.hpp</code>，
+ 所有头文件都在 <code>boost/signals2/</code> 子目录，不像原
Boost.Signals 除了其本身的
+ <code>boost/signals/</code> 子目录，另外在父目录
<code>boost/</code> 中也有几个头文件。
</para>
<para>
For example, the <code>signal</code> class is now
in the <code>boost::signals2</code> namespace instead of the
<code>boost</code> namespace,
and it's header file is now at
<code>boost/signals2/signal.hpp</code> instead of
- <code>boost/signal.hpp</code>.
+ <code>boost/signal.hpp</code>.<sbr/>
+ 例如，<code>signal</code> 类目前在 <code>boost::signals2</code> 名
字空间，而不是 <code>boost</code> 名字空间，
+ 它的头文件目前是 <code>boost/signals2/signal.hpp</code> 而不是
<code>boost/signal.hpp</code>。
</para>
<para>
While porting, only trivial changes to <code>#include</code>
directives
and namespace qualifications should be required to deal with these
changes.
Furthermore, the new namespace and header locations for
Boost.Signals2
allow it to coexist in the same program with the original
Boost.Signals library,
- and porting can be performed piecemeal.
+ and porting can be performed piecemeal.<sbr/>
+ 移植时，为处理这些更改，应该只需对 <code>#include</code> 指示和名字
空间限定作些微不足道的更改。
+ 此外，Boost.Signals2 新的名字空间和头文件位置使它能够与原
Boost.Signals 库共存于同一程序，
+ 这样移植就可以逐渐进行。
</para>
</listitem>
<listitem>
@@ -56,7 +75,12 @@
and <methodname alt="slotN::track">slot::track</methodname>(), as
described in the
<link
linkend="signals2.tutorial.connection-management">tutorial</link>.
However, the old (thread-unsafe) Boost.Signals scheme of automatic
connection management
- is still supported via the
<classname>boost::signals2::trackable</classname> class.
+ is still supported via the
<classname>boost::signals2::trackable</classname> class.<sbr/>
+ 自动连接管理现在是通过利用
<classname>shared_ptr</classname>/<classname>weak_ptr</classname> 和
+ <methodname alt="slotN::track">slot::track</methodname>() 达到
的，见
+ <link linkend="signals2.tutorial.connection-management">教程
</link> 所述。
+ 然而，通过 <classname>boost::signals2::trackable</classname> 类，
+ 旧的（线程不安全的）Boost.Signals 的自动连接管理方案仍被支持。
</para>
<para>
If you do not intend to make your program multi-threaded, the
easiest porting path is to simply replace
@@ -64,7 +88,11 @@
<classname>boost::signals2::trackable</classname>. Boost.Signals2
uses the same
<functionname>boost::visit_each</functionname> mechanism to
discover
<classname>trackable</classname> objects
- as used by the original Boost.Signals library.
+ as used by the original Boost.Signals library.<sbr/>
+ 如果您不打算让您的程序多线程化，最方便的移植路径是，简单地把作为基
类使用的
+ <classname>boost::signals::trackable</classname> 替换为
<classname>boost::signals2::trackable</classname>。
+ 与原 Boost.Signals 库一样，Boost.Signals2 使用同样的
<functionname>boost::visit_each</functionname>
+ 机制来发现 <classname>trackable</classname> 对象。
</para>
</listitem>
<listitem>
@@ -75,7 +103,11 @@
<code>shared_ptr</code> for the new connection tracking scheme,
and the
inability to obtain a <code>shared_ptr</code> to an object in its
constructor.
The use of <functionname>deconstruct</functionname> is described
in the
- <link linkend="signals2.tutorial.deconstruct">tutorial</link>.
+ <link
linkend="signals2.tutorial.deconstruct">tutorial</link>.<sbr/>
+ 对于由 <classname>shared_ptr</classname> 所管理的对象，增加了对后构
造器（和预析构器）的支持，
+ 以及 <functionname>deconstruct</functionname> 工厂函数。这样做的动
机在于 <code>shared_ptr</code>
+ 对新的连接跟踪方案的重要性，并且不能在对象的造构函数中获得它的
<code>shared_ptr</code>。
+ <functionname>deconstruct</functionname> 的使用在 <link
linkend="signals2.tutorial.deconstruct">教程</link> 中描述。
</para>
<para>
The use of <functionname>deconstruct</functionname> is in no way
required,
@@ -92,14 +124,23 @@
of the class and run their associated
<code>adl_postconstruct</code> function.
You can enforce use of <functionname>deconstruct</functionname> by
making the class' constructors private and declaring
- <classname>deconstruct_access</classname> a friend.
+ <classname>deconstruct_access</classname> a friend.<sbr/>
+ <functionname>deconstruct</functionname> 的使用绝不是必需的，提供它
只是希望它有用。
+ 如果您移植的代码中，一个类在其构造函数中创建连接到其自身的成员函
数，并且你还希望使用新的自动连接管理方案，
+ 这时您就可以使用它。然后，您可以将创建连接从构造函数移到
<code>adl_postconstruct</code> 函数，其中有个引用，
+ 指向拥有该对象的 <classname>shared_ptr</classname>，它可以传递给
<methodname alt="slotN::track">slot::track</methodname>。
+ <functionname>deconstruct</functionname> 函数将被用于创建类的对
象，并运行其相关的 <code>adl_postconstruct</code> 函数。
+ 您可以使类的构造函数私有，并声明
<classname>deconstruct_access</classname> 为友元，
+ 来强制使用 <functionname>deconstruct</functionname>。
</para>
</listitem>
<listitem>
<para>
The <classname>slot</classname> class takes a new
<code>Signature</code> template parameter,
is useable as a function object, and has some additional features
to support the
- new Boost.Signals2 automatic connection management scheme.
+ new Boost.Signals2 automatic connection management scheme.<sbr/>
+ <classname>slot</classname> 类需要一个新的 <code>Signature</code>
模板参数，该参数用作一个函数对象，
+ 并具有一些附加功能以支持新的 Boost.Signals2 自动连接管理方案。
</para>
<para>
The changes to the slot class should generally not cause any
porting difficulties,
@@ -107,20 +148,26 @@
compatibility class mentioned above. If you are converting your
code over to
use the new automatic connection management scheme, you will need
to
employ some of the new slot features, as described in the
- <link
linkend="signals2.tutorial.connection-management">tutorial</link>.
+ <link
linkend="signals2.tutorial.connection-management">tutorial</link>.<sbr/>
+ 对插槽类的更改一般应不会造成任何移植困难，尤其是如果您使用的是上述
的兼容类
+ <classname>boost::signals2::trackable</classname>。如果您是要将您的
代码转换为使用新的自动连接管理方案，
+ 您将需要用到一些新的插槽功能，请见 <link
linkend="signals2.tutorial.connection-management">教程</link> 所述。
</para>
</listitem>
<listitem>
<para>
The <classname>optional_last_value</classname> class has replaced
<classname>last_value</classname>
- as the default combiner for signals.
+ as the default combiner for signals.<sbr/>
+ <classname>optional_last_value</classname> 类已取代
<classname>last_value</classname>，成为了信号的默认合并器。
</para>
<para>
The <classname>last_value</classname> combiner is still provided,
although its
behavior is slightly changed in that it
throws an exception when no slots are connected on signal
invocation, instead of
always requiring at least one slot to be connected (except for its
void specialization
- which never required any slots to be connected).
+ which never required any slots to be connected).<sbr/>
+ <classname>last_value</classname> 合并器仍然存在，但其行为略有改
变，当信号调用时无插槽连接会抛异常，
+ 而不是总是要求至少有一个插槽连接 （除了 void 特化，它从不要求任何插
槽连接）。
</para>
<para>
If you are porting signals which have a <code>void</code> return
type in their signature
@@ -130,11 +177,18 @@
<classname>optional_last_value</classname> returns a
<classname>boost::optional</classname> instead of a plain value.
One simple
way to deal with this is to use
<code>boost::optional::operator*()</code> to access the
- value wrapped inside the returned
<classname>boost::optional</classname>.
+ value wrapped inside the returned
<classname>boost::optional</classname>.<sbr/>
+ 如果您移植的信号返回类型是 <code>void</code>，并且使用默认的合并
器，那就不需要任何更改。
+ 如果您使用的是返回类型非空的默认合并器，并且关心信号调用的返回
值，您就必须考虑到
+ <classname>optional_last_value</classname> 返回的是
<classname>boost::optional</classname>，
+ 而不是一个简单的值。处理该问题最简单的一种方法，就是使用
<code>boost::optional::operator*()</code>
+ 来访问返回的 <classname>boost::optional</classname> 中所封装的值。
</para>
<para>
Alternatively, you could do a port by specifying the
<code>Combiner</code> template parameter
- for your <code>signals2::signal</code> to be
<classname>last_value</classname>.
+ for your <code>signals2::signal</code> to be
<classname>last_value</classname>.<sbr/>
+ 或者，您也可以这样移植：指定 <code>signals2::signal</code> 的
<code>Combiner</code>
+ 模板参数为 <classname>last_value</classname>。
</para>
</listitem>
<listitem>
@@ -146,7 +200,13 @@
which take an additional <classname>connection</classname>
argument, giving them thread-safe
access to their signal/slot connection when they are invoked.
There is also a
new <code>ExtendedSlotFunction</code> template parameter for
specifying the underlying slot function
- type for the new extended slots.
+ type for the new extended slots.<sbr/>
+ <classname>signal</classname> 类添加了一个
+ <classname
alt="signalN::extended_slot_type">signal::extended_slot_type</classname> 类
型定义，
+ 和新的 <methodname
alt="signalN::connect_extended">signal::connect_extended</methodname>() 方
法。
+ 这使得连接的插槽可以接受一个额外的
<classname>connection</classname> 参数，
+ 使插槽被调用时可以线程安全地访问其信号/插槽连接。
+ 还有一个新的 <code>ExtendedSlotFunction</code> 模板参数，来为新的扩
展插槽指定底层的插槽函数类型。
</para>
<para>
These additions should have no effect on porting unless you are
also converting
@@ -157,13 +217,20 @@
<methodname
alt="signalN::connect_extended">signal::connect_extended</methodname>().
This also requires adding an additional connection argument to the
slot.
More information on how and why to use extended slots is available
- in the <link
linkend="signals2.tutorial.extended-slot-type">tutorial</link>.
+ in the <link
linkend="signals2.tutorial.extended-slot-type">tutorial</link>.<sbr/>
+ 这些添加应该不会影响移植，除非您同时在把程序从单线程转换为多线程
的。在这种情况下，
+ 如果您有插槽需要访问其 <classname>connection</classname> （例如，阻
止或断开其连接，
+ 即插槽与调用插槽的信号之间的连接），您可能希望用
+ <methodname
alt="signalN::connect_extended">signal::connect_extended</methodname>() 来连
接插槽。
+ 这也要求插槽增加一个额外的连接参数。<link
linkend="signals2.tutorial.extended-slot-type">教程</link>
+ 中有如何以及为什么使用扩展插槽的详细信息。
</para>
</listitem>
<listitem>
<para>
The <classname>signal</classname> class has a new
<code>Mutex</code> template parameter for specifying
- the mutex type used internally by the signal and its connections.
+ the mutex type used internally by the signal and its
connections.<sbr/>
+ signal 类有个新的 Mutex 模板参数，用来指定信号及其连接内部使用的互
斥体类型。
</para>
<para>
The <code>Mutex</code> template parameter can be left to its
default value of
@@ -172,13 +239,20 @@
concerned about incuring a performance overhead from unneeded
mutex locking, you may
wish to use a different mutex for your signals such as
<classname>dummy_mutex</classname>.
See the <link
linkend="signals2.tutorial.signal-mutex-template-parameter">tutorial</link>
- for more information on the <code>Mutex</code> parameter.
+ for more information on the <code>Mutex</code> parameter.<sbr/>
+ <code>Mutex</code> 模板参数可保持缺省值
<classname>boost::signals2::mutex</classname>，应该不会影响移植。
+ 但是，如果你有一个单线程程序，担心因不必要的互斥锁而招致性能开
销，你不妨为你的信号使用不同的互斥体，
+ 如 <classname>dummy_mutex</classname>。关于 <code>Mutex</code> 参数
的更多信息请见
+ <link
linkend="signals2.tutorial.signal-mutex-template-parameter">教程</link>。
</para>
</listitem>
<listitem>
<para>The <code>signal::combiner()</code> method, which formerly
returned a reference to the
signal's combiner has been replaced by <methodname
alt="signalN::combiner">signal::combiner</methodname>
- (which now returns the combiner by value) and <methodname
alt="signalN::set_combiner">signal::set_combiner</methodname>.
+ (which now returns the combiner by value) and <methodname
alt="signalN::set_combiner">signal::set_combiner</methodname>.<sbr/>
+ <code>signal::combiner()</code>方法，原来返回一个指向信号合并器的引
用，已被
+ <methodname
alt="signalN::combiner">signal::combiner</methodname>（现在按值返回合并器
）和
+ <methodname
alt="signalN::set_combiner">signal::set_combiner</methodname> 取代。
</para>
<para>
During porting it should be straightforward to replace uses of the
old reference-returning
@@ -187,16 +261,23 @@
and <methodname
alt="signalN::set_combiner">signal::set_combiner</methodname> functions.
However, you will need to inspect each call of the
<code>combiner</code> method in your code
to determine if your program logic has been broken by the changed
- return type.
+ return type.<sbr/>
+ 移植过程中，将旧的返回引用的 <code>signal::combiner()</code> 函数替
换为新的“按值”方式的
+ <methodname alt="signalN::combiner">signal::combiner</methodname>
和
+ <methodname
alt="signalN::set_combiner">signal::set_combiner</methodname> 函数，应该是简
单的。
+ 但是，您需要检查代码中每个 <code>combiner</code> 方法调用，以确定您
的程序逻辑没有因更改返回类型而破坏。
</para>
</listitem>
<listitem>
<para>Connections no longer have <code>block()</code> and
<code>unblock()</code> methods. Blocking
of connections is now accomplished by creating
<classname>shared_connection_block</classname> objects,
- which provide RAII-style blocking.
+ which provide RAII-style blocking.<sbr/>
+ 连接不再有 <code>block()</code> 和 <code>unblock()</code> 方法。连
接的阻塞现在通过创建
+ <classname>shared_connection_block</classname> 对象完成，它提供了
RAII 方式的阻塞。
</para>
<para>
- If you have existing Boost.Signals code that blocks, for example:
+ If you have existing Boost.Signals code that blocks, for
example:<sbr/>
+ 如果您现有的 Boost.Signals 代码有阻塞，例如：
</para>
<programlisting>
namespace bs = boost::signals;
@@ -209,7 +290,8 @@
my_connection.unblock();
</programlisting>
<para>
- then the version ported to Boost.Signals2 would look like:
+ then the version ported to Boost.Signals2 would look
like:<sbr/>
+ 那么移植到 Boost.Signals2 的版本将如下所示：
</para>
<programlisting>
namespace bs2 = boost::signals2;
@@ -225,3 +307,79 @@
</listitem>
</itemizedlist>
</section>
+ <section id="signals2.api_history">
+ <title>Signals2 API Development Signals API发展</title>
+ <section id="signals2.api_history.1-40">
+ <title>Version 1.40</title>
+ <para>
+ Version 1.40 adds a few new features to the
<classname>shared_connection_block</classname>
+ class to make it more flexible:<sbr/>
+ 版本1.40为 <classname>shared_connection_block</classname> 类增加了
一些新的特性令其更为灵活：
+ <itemizedlist>
+ <listitem>
+ <para>
+ <classname>shared_connection_block</classname> is now
default constructible.<sbr/>
+ <classname>shared_connection_block</classname> 现在可以缺省构
造。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A <classname>shared_connection_block</classname> may now be
constructed without
+ immediately blocking its connection.<sbr/>
+ <classname>shared_connection_block</classname> 现在可以无须立
即阻塞其连接而被构造。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The
<methodname>shared_connection_block::connection</methodname>() query has
been
+ added, to provide access to the
<code>shared_connection_block</code>s associated
+ connection.<sbr/>
+ 增加了
<methodname>shared_connection_block::connection</methodname>() 查询，
+ 以提供对 <code>shared_connection_block</code> 相关联连接的访
问。
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>Version 1.40 also introduces a variadic templates
implementation of
+ Signals2, which is used when Boost detects compiler support for
variadic templates
+ (variadic templates are a new feature of C++0x).
+ This change is mostly transparent to the user, however it does
introduce a few
+ visible tweaks to the interface as described in the
following.<sbr/>
+ 版本1.40还引入了一个 Signals2 的可变参数模板实现，当 Boost 检测到编
译器支持可变参数模板
+ (可变参数是C++0x的新特性)时即会使用该实现。该变化对于用户而言基本上
是透明的，
+ 但是也确实对接口带来一些可见的调整，说明如下。
+ </para>
+ <para>
+ The following library features are
+ deprecated, and are only available if your compiler is NOT using
+ variadic templates (i.e. BOOST_NO_VARIADIC_TEMPLATES is defined
+ by Boost.Config).<sbr/>
+ 以下的库特性已过时，仅当你的编译器不使用可变参数模板(即
Boost.Config定义了BOOST_NO_VARIADIC_TEMPLATES)时可用。
+ <itemizedlist>
+ <listitem>
+ <para>
+ The "portable syntax" signal and slot classes, i.e.
signals2::signal0, signal1, etc.<sbr/>
+ "兼容句法"的信号和插槽类，即 signals2::signal0, signal1, 等
等。
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The arg1_type, arg2_type, etc. member typedefs in the
<classname>signals2::signal</classname> and
+ <classname>signals2::slot</classname> classes. They are
replaced by the
+ template member classes
<classname>signals2::signal::arg</classname> and
+ <classname>signals2::slot::arg</classname>.<sbr/>
+ <classname>signals2::signal</classname> 和
<classname>signals2::slot</classname> 类中的 arg1_type,
+ arg2_type 等成员typedef。它们被模板成员类
<classname>signals2::signal::arg</classname> 和
+ <classname>signals2::slot::arg</classname> 所替代。
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="signals2.api_history.1-39">
+ <title>Version 1.39</title>
+ <para>Version 1.39 is the first release of Boost to include the
Signals2 library.<sbr/>
+ 版本1.39是包含 Signals2 库的第一个 Boost 发布。</para>
+ </section>
+ </section>
+</section>
=======================================
--- /trunk/libs/signals2/doc/rationale.xml Thu May 7 20:34:38 2009
+++ /trunk/libs/signals2/doc/rationale.xml Sat Jan 23 06:27:10 2010
@@ -9,14 +9,14 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.rationale">
- <title>Design Rationale</title>
+ <title>Design Rationale 设计原理</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
<using-class name="boost::signals2::signalN"/>
<section>
- <title>User-level Connection Management</title>
+ <title>User-level Connection Management 用户层连接管理</title>
<para> Users need to have fine control over the connection of
signals to slots and their eventual disconnection. The primary approach
@@ -25,7 +25,11 @@
connected/disconnected query, manual disconnection, and an
automatic disconnection on destruction mode
(<classname>scoped_connection</classname>).
In addition, two other interfaces are supported by the
- <methodname alt="signalN::disconnect">signal::disconnect</methodname>
overloaded method:</para>
+ <methodname alt="signalN::disconnect">signal::disconnect</methodname>
overloaded method:<sbr/>
+ 用户需要精确控制信号到插槽的连接和它们最后的断开。Boost.Signals2 所采用
的主要方法是，
+ 返回一个 <code><classname>connection</classname></code> 对象，让人能够
进行已连接/已断开查询、手工断开，
+ 以及在析构模式(<classname>scoped_connection</classname>)下自动断开。另
外，
+ <methodname alt="signalN::disconnect">signal::disconnect</methodname>
重载方法还支持其他两个接口：</para>
<itemizedlist>
<listitem>
@@ -38,7 +42,12 @@
a linear search using slot comparison is performed and the
slot, if found, is removed from the list. Unfortunately,
querying connectedness ends up as a
- linear-time operation.</para>
+ linear-time operation.<sbr/>
+ <emphasis role="bold">断开时传递插槽</emphasis>：在这个接口模型
下，通过
+
<code>sig.<methodname>connect</methodname>(typeof(sig)::slot_type(slot_func))</code>
连接的插槽，
+ 断开时是通过
<code>sig.<methodname>disconnect</methodname>(slot_func)</code> 进行的。
+ 在内部，将利用插槽比较，执行一个线性搜索， 如果找到该插槽，就从链表
中删除。
+ 不幸的是，连接查询是线性时间的操作。</para>
</listitem>
<listitem>
@@ -47,7 +56,10 @@
token that is easily comparable (e.g., a string), enabling
slots to be arbitrary function objects. While this approach is
essentially equivalent to the connection approach taken by
Boost.Signals2,
- it is possibly more error-prone for several reasons:</para>
+ it is possibly more error-prone for several reasons:<sbr/>
+ <emphasis role="bold">断开时传递一个标记</emphasis>：这个方法用一个
容易比较的标记来标识插槽（例如用字符串），
+ 插槽可以是任意的函数对象。虽然这个方法本质上等效于 Boost.Signals2
所采用的方法，
+ 但是因为以下几个原因，它更容易出错：</para>
<itemizedlist>
<listitem>
@@ -57,7 +69,9 @@
dynamic memory allocation. While errors of this sort would
not be catastrophic for a signals and slots
implementation, their detection is generally
- nontrivial.</para>
+ nontrivial.<sbr/>
+ 连接与断开必须配对，因此问题变得类似于动态内存分配中的
<code>new</code> 和 <code>delete</code>
+ 配对时所产生的问题。虽然这种错误对于信号插槽库实现来说并不是灾
难性的，但是要检测它们通常并不简单。</para>
</listitem>
<listitem>
@@ -65,20 +79,24 @@
the same name and be indistinguishable. In
environments where many connections will be made
dynamically, name generation becomes an additional task
- for the user.</para>
+ for the user.<sbr/>
+ 如果标记不唯一，两个插槽可能会具有相同的名字而不可区分。
+ 在动态产生许多连接的环境下，名字生成将成为用户的额外负担。
</para>
</listitem>
</itemizedlist>
<para> This type of interface is supported in Boost.Signals2
via the slot grouping mechanism, and the overload of
<methodname
alt="signalN::disconnect">signal::disconnect</methodname>
- which takes an argument of the signal's <code>Group</code>
type.</para>
+ which takes an argument of the signal's <code>Group</code>
type.<sbr/>
+ Boost.Signals2 支持此类接口是通过插槽编组机制，以及以信号的
<code>Group</code> 类型为参数的
+ <methodname
alt="signalN::disconnect">signal::disconnect</methodname> 重载。</para>
</listitem>
</itemizedlist>
</section>
<section>
- <title>Automatic Connection Management</title>
+ <title>Automatic Connection Management 自动连接管理</title>
<para>Automatic connection management in Signals2
depends on the use of <classname>boost::shared_ptr</classname> to
@@ -87,7 +105,10 @@
from the
<code><classname>boost::signals::trackable</classname></code> class.
The library would be
notified of an object's destruction by the
- <code><classname>boost::signals::trackable</classname></code>
destructor.
+ <code><classname>boost::signals::trackable</classname></code>
destructor.<sbr/>
+ Signals2 的自动连接管理利用了
<classname>boost::shared_ptr</classname> 来管理可跟踪对象的生命期。
+ 这不同于原 Boost.Signals 库，Boost.Signals 库是通过派生
<code><classname>boost::signals::trackable</classname></code>
+ 类实现的。对象析构
时，<code><classname>boost::signals::trackable</classname></code> 的析构函数
会通知库。
</para>
<para>Unfortunately, the
<code><classname>boost::signals::trackable</classname></code>
scheme cannot be made thread safe due
@@ -99,7 +120,12 @@
Otherwise, if an object being destroyed
in one thread is connected to a signal concurrently
invoking in another thread, the signal may call into
- a partially destroyed object.
+ a partially destroyed object.<sbr/>
+ 不幸的
是，<code><classname>boost::signals::trackable</classname></code> 方案因为析
构函数的次序问题，
+ 不能做成线程安全的。
<code><classname>boost::signals::trackable</classname></code> 派生类的析构函
数总是在其基类
+ <code><classname>boost::signals::trackable</classname></code> 的析构
函数之前被调用。然而，为了线程安全性，
+ 信号和对象之间的连接需要在对象运行它的析构函数之前断开。否则，如果对
象在一个线程中被销毁，
+ 而在另一个线程中，并发调用它所连接的信号，该信号可能会调用到部份销毁
的对象。
</para>
<para>We solve this problem by requiring that tracked objects be
managed by <classname>shared_ptr</classname>. Slots keep a
@@ -108,7 +134,12 @@
<classname>weak_ptr</classname>s expire. Additionally, signals
create their own temporary <classname>shared_ptr</classname>s to
all of a slot's tracked objects prior to invoking the slot. This
- insures none of the tracked objects destruct in mid-invocation.
+ insures none of the tracked objects destruct in mid-invocation.<sbr/>
+ 我们通过要求可跟踪对象由 <classname>shared_ptr</classname> 管理，来解
决这个问题。
+ 插槽持有它所依赖的每个对象的 <classname>weak_ptr</classname>。当插槽
跟踪的任一
+ <classname>weak_ptr</classname> 到期，该插槽的所有连接都会被断开。此
外，在触发插槽之前，
+ 信号会为所有的插槽跟踪对象创建它们自己的临时
<classname>shared_ptr</classname>。
+ 这保证了在调用过程中，被跟踪对象不会被析构。
</para>
<para>The new connection management scheme has the advantage of being
non-intrusive. Objects of any type may be tracked using the
@@ -116,12 +147,15 @@
<code><classname>boost::signals::trackable</classname></code>
scheme requires the tracked objects to be derived from the
<code>trackable</code>
base class, which is not always practical when interacting
- with classes from 3rd party libraries.
+ with classes from 3rd party libraries.<sbr/>
+ 新的连接管理方案的优点在于它是非侵入性的。任何类型的对象都可使用
<classname>shared_ptr/weak_ptr</classname> 方案来跟踪。
+ 旧的 <code><classname>boost::signals::trackable</classname></code> 方
案要求被跟踪对象派生自 <code>trackable</code> 基类，
+ 当使用来自第3方库的类时，这并不总是可行。
</para>
</section>
<section>
- <title><code>optional_last_value</code> as the Default Combiner</title>
+ <title><code>optional_last_value</code> as the Default Combiner 默认合
并器为<code>optional_last_value</code></title>
<para>
The default combiner for Boost.Signals2 has changed from the
<code>last_value</code>
combiner used by default in the original Boost.Signals library.
@@ -132,11 +166,16 @@
to fulfill this requirement. When using
<classname>optional_last_value</classname>,
there is no requirement for slots to be connected when a signal
is invoked, since in that case the combiner may simply return an
empty
- <classname>boost::optional</classname>.
+ <classname>boost::optional</classname>.<sbr/>
+ Boost.Signals2 的默认合并器已经改了，不再是原 Boost.Signals 所默认使
用的 <code>last_value</code> 合并器。
+ 这是因为 <code>last_value</code> 要求信号调用时，至少有1个插槽连接到
信号（除非是 <code>last_value<void></code>
+ 特化）。在多线程环境下，信号调用与插槽的连接和断开可能同时发生，很难
满足这一要求。当使用
+ <classname>optional_last_value</classname>，不要求信号调用时已连接插
槽，因为在这种情况下，
+ 合并器可以只是返回一个空的 <classname>boost::optional</classname>。
</para>
</section>
<section>
- <title>Combiner Interface</title>
+ <title>Combiner Interface 合并器接口</title>
<para> The Combiner interface was chosen to mimic a call to an
algorithm in the C++ standard library. It is felt that by viewing
@@ -150,7 +189,11 @@
libraries, the combiners are unfortunately not reusable (either in
other signals & slots libraries or within other generic
algorithms), and the learning curve is steepened slightly to learn
- the specific combiner interface.</para>
+ the specific combiner interface.<sbr/>
+ 合并器接口模仿了对C++标准库算法的调用。 对熟练的C++程序员来说，合并器是
感觉最自然的接口，
+ 因为它把插槽调用的结果看作仅仅是一系列通过输入迭代器访问的值。与之匹敌
的接口设计一般要求合并器构造成符合一定的接口，
+ 使之可以为 Signals2 库定制（并局限于库）。虽然这些接口通常使信号插槽库
的实现更简单，但可惜这种合并器不可重用
+ （在其他信号插槽库或在其他通用算法中），并且学习特殊的合并器接口的学习
曲线有点陡。</para>
<para> The Signals2 formulation of combiners is based on the
combiner using the "pull" mode of communication, instead of the
@@ -164,14 +207,20 @@
the combiner's routines will be invoked for each signal
called. Compare, for example, a combiner that returns the maximum
element from calling the slots. If the maximum element ever
- exceeds 100, no more slots are to be called.</para>
+ exceeds 100, no more slots are to be called.<sbr/>
+ Signals2 库的合并器设计方案基于使用“拉”模式通讯的合并器，而不是更复杂的
“推”机制。
+ 用“拉”机制，合并器的状态可以保存在栈上，并保持程序计数器寄存器，因为无
论何时需要新数据时
+ （即调用下一插槽来提取其返回值），有一个简单的接口来立即提取那个数据，
+ 而不必从合并器的代码中返回。 “推”机制与此相反，它的合并器必须在类成员中
保存所有的状态，
+ 因为每次调用信号都会引起合并器函数的调用。比较下例合并器的两种实现，该
合并器返回插槽调用的最大元素。
+ 如果最大元素超过 100，就不再调用以后的插槽。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry><para>Pull</para></entry>
- <entry><para>Push</para></entry>
+ <entry><para>Pull 拉</para></entry>
+ <entry><para>Push 推</para></entry>
</row>
</thead>
<tbody>
@@ -252,7 +301,11 @@
received. Though code quality and ease-of-use is generally
subjective, the "pull" model is clearly shorter and more reusable
and will often be construed as easier to write and understand,
- even outside the context of a signals & slots library.</para>
+ even outside the context of a signals & slots library.<sbr/>
+ 该例中要注意几点。“拉”的版本是个可重用的函数对象，基于
<code>value_type</code> 为整数的输入迭代器序列，
+ 并且设计上非常简单。另一方面，“推”的版本依赖于调用者专有的接口，一般不
是可重用的。
+ 它同时要求额外的状态值，例如，是否已经接收过元素。尽管代码质量和易用性
是主观性的，
+ “拉”模式明显更短并且重用性更好，并且往往更容易编写和理解，即使是脱离信
号插槽库的上下文。</para>
<para> The cost of the "pull" combiner interface is paid in the
implementation of the Signals2 library itself. To correctly handle
@@ -267,18 +320,27 @@
invoking slots one sees that the overhead is nearly equivalent to
that in the "push" model, but we have inverted the control
structures to make iteration and dereference complex (instead of
- making combiner state-finding complex).</para>
+ making combiner state-finding complex).<sbr/>
+ “拉”合并器接口的代价支付于 Signals2 库本身的实现中。为了正确处理在调用
中的插槽断开
+ （例如当调用解引用运算符时），你必须让迭代器跳过已断开的插槽。另外，
+ 迭代器必须携带一组参数以传送到每个插槽（尽管一个包含那些参数的结构的引
用就足够了），
+ 并且必须缓存插槽调用的结果，这样多次解引用才不会导致多次调用。这显然需
要很大的开销，
+ 尽管如果考虑调用插槽整个过程，该开销几乎等同于“推”模型的开销，但是我们
颠倒了控制结构，
+ 让迭代和解引用变复杂了（替代了合并器状态查找的复杂性）。 </para>
</section>
<section>
- <title>Connection Interfaces: += operator</title>
+ <title>Connection Interfaces: += operator 连接的接口：+= 运算符
</title>
<para> Boost.Signals2 supports a connection syntax with the form
<code>sig.<methodname>connect</methodname>(slot)</code>, but a
more terse syntax <code>sig += slot</code> has been suggested (and
has been used by other signals & slots implementations). There
are several reasons as to why this syntax has been
- rejected:</para>
+ rejected:<sbr/>
+ Boost.Signals2 支持形如
<code>sig.<methodname>connect</methodname>(slot)</code> 的连接语法，
+ 但是有人建议用更简洁的语法 <code>sig += slot</code> （并已被其他信号插
槽实现所用）。
+ 为什么拒绝这个语法有以下几个原因：</para>
<itemizedlist>
<listitem>
@@ -288,7 +350,10 @@
operator. The savings in typing (<code>connect()</code>
vs. <code>+=</code>) is essentially negligible. Furthermore,
one could argue that calling <code>connect()</code> is more
- readable than an overload of <code>+=</code>.</para>
+ readable than an overload of <code>+=</code>.<sbr/>
+ <emphasis role="bold">没必要</emphasis>：Boost.Signals2 提供的连接
语法并不比 <code>+=</code> 运算符差。
+ 少打几个字符(<code>connect()</code> vs. <code>+=</code>)根本是可以
忽略的。
+ 另外，有人主张调用 <code>connect()</code> 比 <code>+=</code> 重载可
读性更好。</para>
</listitem>
<listitem>
<para><emphasis role="bold">Ambiguous return type</emphasis>:
@@ -297,7 +362,10 @@
signal itself, to enable <code>sig += slot1 += slot2</code>,
or should it return a
<code><classname>connection</classname></code> for the
- newly-created signal/slot connection?</para>
+ newly-created signal/slot connection?<sbr/>
+ <emphasis role="bold">返回类型二义性</emphasis>：<code>+=</code> 运
算符的返回值存在二义性。
+ 它应该是返回信号本身的引用，可以 <code>sig += slot1 +=
slot2</code>，
+ 还是返回新建的信号/插槽连接的一个
<code><classname>connection</classname></code>？</para>
</listitem>
<listitem>
@@ -308,19 +376,25 @@
the library allows arbitrary function objects to implicitly
become slots, because slots are no longer comparable. <!--
(see the discussion on this topic in User-level Connection
- Management). --></para>
+ Management). --><sbr/>
+ <emphasis role="bold">通往运算符 -=、+</emphasis>：当添加一个连接运
算符 <code>+=</code>，
+ 好像自然地要有一个断开运算符 <code>-=</code>。然而，当库允许任意的
函数对象隐式地变成插槽时，
+ 这里出现了问题，因为插槽不再具有比较性。</para>
<para> The second obvious addition when one has
<code>operator+=</code> would be to add a <code>+</code>
operator that supports addition of multiple slots, followed by
assignment to a signal. However, this would require
implementing <code>+</code> such that it can accept any two
- function objects, which is technically infeasible.</para>
+ function objects, which is technically infeasible.<sbr/>
+ 当具有 <code>operator+=</code> 时，第二个明显会添加的是
<code>+</code> 运算符，
+ 以支持多个插槽相加，然后再赋值到信号。然而，这要求实现
<code>+</code> 可以接收任意两个函数对象，
+ 这在技术上是不可行的。</para>
</listitem>
</itemizedlist>
</section>
<section>
- <title>Signals2 Mutex Classes</title>
+ <title>Signals2 Mutex Classes Signals2互斥类</title>
<para>
The Boost.Signals2 library provides 2 mutex classes:
<classname>boost::signals2::mutex</classname>,
and <classname>boost::signals2::dummy_mutex</classname>. The
motivation for providing
@@ -330,16 +404,23 @@
a header-only library. In the future,
<classname>boost::signals2::mutex</classname>
will probably be turned into a typedef to
<classname>std::mutex</classname> when
compiling in C++0x mode. You may still choose to use
<classname>boost::mutex</classname>
- if you wish, by specifying it as the <code>Mutex</code> template
type for your signals.
+ if you wish, by specifying it as the <code>Mutex</code> template
type for your signals.<sbr/>
+ Boost.Signals2 库提供了两个互斥
类：<classname>boost::signals2::mutex</classname>，和
+ <classname>boost::signals2::dummy_mutex</classname>。提供
<classname>boost::signals2::mutex</classname>
+ 类的动机只是因为 Boost.Thread 库当前的
<classname>boost::mutex</classname> 类要求链接 libboost_thread。
+ <classname>boost::signals2::mutex</classname> 类让 Signals2 保持为纯
头文件库。以后，在C++0x模式下编译时
+ <classname>boost::signals2::mutex</classname> 可能被转为对
<classname>std::mutex</classname> 的一个typedef。
+ 如果您愿意，您仍然可以选择使用
<classname>boost::mutex</classname>，只要将它指定为信号的
<code>Mutex</code> 模板类型。
</para>
<para>
The <classname>boost::signals2::dummy_mutex</classname> class is
provided to allow
performance sensitive single-threaded applications to minimize
overhead by avoiding unneeded
- mutex locking.
+ mutex locking.<sbr/>
+ 提供 <classname>boost::signals2::dummy_mutex</classname> 类允许性能敏
感的单线程应用避免不必要的互斥锁，尽量减少开销。
</para>
</section>
<section>
- <title>Comparison with other Signal/Slot implementations</title>
+ <title>Comparison with other Signal/Slot implementations 与其他信号/插
槽实现的比较</title>
<section>
<title>libsigc++</title>
@@ -356,7 +437,12 @@
similar syntax for the construction of signals and in the use of
connections. There
are some major differences in design that separate these
- libraries:</para>
+ libraries:<sbr/>
+ <ulink url="http://libsigc.sourceforge.net";>libsigc++</ulink> 是个
C++信号插槽库，
+ 最初开始于一个项目的一部分，用C++封装 <ulink
url="http://www.gtk.org";>GTK</ulink> 库的C接口，
+ 并且发展成为一个独立的库，由 Karl Nelson 维护。libsigc++ 和
Boost.Signals2 之间有很多相同之处，
+ 其实原 Boost.Signals 受 Karl Nelson 和 libsigc++ 影响很大。粗略地检查
这两个库就会发现相似的语法，
+ 如信号的构造和连接的使用。这两个库在设计上的主要区别是：</para>
<itemizedlist>
<listitem>
@@ -366,7 +452,10 @@
objects (as part of the library), explicit adaptation from
the argument and return types of the signal to the argument
and return types of the slot (libsigc++ is, by default, more
- strict about types than Boost.Signals2).</para>
+ strict about types than Boost.Signals2).<sbr/>
+ <emphasis role="bold">插槽定义</emphasis>： libsigc++ 中的插槽用
一套库定义的原语创建。
+ 这些原语允许对象绑定（作为库的一部分），显式地把信号的参数和返回
类型适配为插槽的参数和返回类型
+ （相比 Boost.Signals2，libsigc++ 在默认情况下对类型更严格）。
</para>
</listitem>
<listitem>
@@ -375,31 +464,39 @@
combiners in libsigc++ are the marshallers. Marshallers are
similar to the "push" interface described in Combiner
Interface, and a proper treatment of the topic is given
- there.</para>
+ there.<sbr/>
+ <emphasis role="bold">合并器/集结器接口</emphasis>：libsigc++ 中
与 Boost.Signals 的合并器等效的是集结器。
+ 集结器类似于“合并器接口”一节中描述的“推”接口，那里对该主题进行了
适当的分析。</para>
</listitem>
</itemizedlist>
</section>
<section>
- <title>.NET delegates</title>
+ <title>.NET delegates .NET委托</title>
<para> <ulink url="http://www.microsoft.com";>Microsoft</ulink>
has introduced the .NET Framework and an associated set of
languages and language extensions, one of which is the
delegate. Delegates are similar to signals and slots, but they
are more limited than most C++ signals and slots implementations
- in that they:</para>
+ in that they:<sbr/>
+ <ulink url="http://www.microsoft.com";>Microsoft</ulink> 引入了 .NET
框架，
+ 并关联了一组语言和语言扩展，其中之一就是委托。委托类似于信号插槽，
+ 但是它比大多数C++信号插槽的实现具有更多的限制，表现在：</para>
<itemizedlist>
<listitem>
<para>Require exact type matches between a delegate and what
- it is calling.</para>
+ it is calling.<sbr/>
+ 在委托和它的调用之间，要求精确的类型匹配。</para>
</listitem>
- <listitem><para>Only return the result of the last target called,
with no option for customization.</para></listitem>
+ <listitem><para>Only return the result of the last target called,
with no option for customization.<sbr/>
+ 仅返回最后调用目标的结果，无法定制。</para></listitem>
<listitem>
<para>Must call a method with <code>this</code> already
- bound.</para>
+ bound.<sbr/>
+ 必须调用一个 <code>this</code> 已绑定的方法。</para>
</listitem>
</itemizedlist>
</section>
=======================================
--- /trunk/libs/signals2/doc/tests.xml Thu May 7 20:34:38 2009
+++ /trunk/libs/signals2/doc/tests.xml Sat Jan 23 06:27:10 2010
@@ -14,7 +14,9 @@
<purpose>
<para>Test functionality of
<classname>boost::signals2::connection</classname>
and <classname>boost::signals2::scoped_connection</classname>
- objects, including release() and swap().</para>
+ objects, including release() and swap().<sbr/>
+ 测试 <classname>boost::signals2::connection</classname> 和
<classname>boost::signals2::scoped_connection</classname> 对象，
+ 包括 release() 和 swap()。</para>
</purpose>
</run-test>
@@ -23,7 +25,8 @@
<purpose>
<para>Ensure that calling <methodname
alt="boost::signals2::signalN::connect">connect</methodname> with a slot
that has already expired does not actually
-connect to the slot.</para>
+connect to the slot.<sbr/>
+确保用已经过期失效的插槽调用 <methodname
alt="boost::signals2::signalN::connect">connect</methodname> 实际上并不连接
该插槽。</para>
</purpose>
</run-test>
@@ -31,33 +34,38 @@
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<purpose>
<para>Test postconstruction/predestruction functionality of
- <functionname>boost::signals2::deconstruct</functionname>.</para>
+ <functionname>boost::signals2::deconstruct</functionname>.<sbr/>
+ 测试 <functionname>boost::signals2::deconstruct</functionname> 的
后构造/预析构 功能。</para>
</purpose>
</run-test>
<run-test filename="deletion_test.cpp">
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<purpose>
-<para>Test deletion of slots.</para>
+<para>Test deletion of slots.<sbr/>
+测试插槽的删除。</para>
</purpose>
</run-test>
<run-test filename="ordering_test.cpp">
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
- <purpose><para>Test slot group ordering.</para></purpose>
+ <purpose><para>Test slot group ordering.<sbr/>
+ 测试插槽组排序。</para></purpose>
</run-test>
<run-test filename="regression_test.cpp">
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<purpose><para>Tests for various bugs that have occurred in the past,
- to make sure they are fixed and stay fixed.</para></purpose>
+ to make sure they are fixed and stay fixed.<sbr/>
+ 测试过去发生的各种错误，以确保它们已被修复并保持修复。
</para></purpose>
</run-test>
<run-test filename="signal_n_test.cpp">
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<purpose>
<para>Basic test of signal/slot connections and invocation using the
-<classname>boost::signals2::signalN</classname> class templates.</para>
+<classname>boost::signals2::signalN</classname> class templates.<sbr/>
+使用 <classname>boost::signals2::signalN</classname> 类模板时，信号/插槽连
接和调用的基本测试。</para>
</purpose>
</run-test>
@@ -65,13 +73,16 @@
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<purpose>
<para>Basic test of signal/slot connections and invocation using the
-<classname>boost::signals2::signal</classname> class template.</para>
+<classname>boost::signals2::signal</classname> class template.<sbr/>
+使用 <classname>boost::signals2::signal</classname> 类模板时，信号/插槽连接
和调用的基本测试。</para>
</purpose>
<if-fails>
<para>The <classname>boost::signals2::signal</classname> class template
may not
be usable on your compiler. However, the
<classname>boost::signals2::signalN</classname> class templates may still
be
-usable.</para>
+usable.<sbr/>
+<classname>boost::signals2::signal</classname> 类模板不能用于你的编译器。
+不过 <classname>boost::signals2::signalN</classname> 可能还是可用的。
</para>
</if-fails>
</run-test>
@@ -79,7 +90,8 @@
<lib>../../../libs/test/build/boost_test_exec_monitor</lib>
<purpose>
<para>Test automatic connection management of signals
- and slots.</para>
+ and slots.<sbr/>
+ 测试信号和插槽的自动连接管理。</para>
</purpose>
</run-test>
</testsuite>
=======================================
--- /trunk/libs/signals2/doc/thread_safety.xml Thu May 7 20:34:38 2009
+++ /trunk/libs/signals2/doc/thread_safety.xml Sat Jan 23 06:27:10 2010
@@ -8,13 +8,13 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.thread-safety">
- <title>Thread-Safety</title>
+ <title>Thread-Safety 线程安全性</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
<section>
- <title>Introduction</title>
+ <title>Introduction 介绍</title>
<para>
The primary motivation for Boost.Signals2 is to provide a version of
the original Boost.Signals library which can be used safely in a
@@ -26,16 +26,24 @@
The second change was the introduction of a <code>Mutex</code>
template type
parameter to the <classname>signal</classname> class. This section
details how
the library employs these changes to provide thread-safety, and
- the limits of the provided thread-safety.
+ the limits of the provided thread-safety.<sbr/>
+ Boost.Signals2 的原始动机是提供原 Boost.Signals 库的另一版本，使之可
以安全地用于多线程环境。
+ 做到这一点主要是通过对原 Boost.Signals API 的两个更改。一是采用了新
的，依赖于 <classname>shared_ptr</classname>
+ 和 <classname>weak_ptr</classname> 的自动连接管理方式，详见
+ <link linkend="signals2.tutorial.connection-management">教程</link>
的描述。
+ 二是 <classname>signal</classname> 类引入了模板类型参数
<code>Mutex</code>。
+ 本节详述了库如何采用这些更改来提供线程安全性，以及它所提供的线程安全
性的局限性。
</para>
</section>
<section>
- <title>Signals and combiners</title>
+ <title>Signals and combiners 信号与合并器</title>
<para>
Each signal object default-constructs a <code>Mutex</code> object to
protect
its internal state. Furthermore, a <code>Mutex</code> is created
each time a new slot is connected to the signal, to protect the
- associated signal-slot connection.
+ associated signal-slot connection.<sbr/>
+ 每个信号对象会缺省构造一个 <code>Mutex</code> 对象，以保护其内部状
态。
+ 此外，每当一个新的插槽连接到信号，都会创建一个 <code>Mutex</code>，以
保护相关的信号插槽连接。
</para>
<para>
A signal's mutex is automatically locked whenever any of the
@@ -55,17 +63,26 @@
recursive locking attempts on any of the library's internal mutexes.
Therefore, if you invoke a signal concurrently from multiple threads,
it is possible for the signal's combiner to be invoked concurrently
- and thus the slots to execute concurrently.
+ and thus the slots to execute concurrently.<sbr/>
+ 调用信号的任何方法时，信号的互斥体都会自动加锁。通常互斥体会保持锁
定，直到方法结束，但是有一个重要的例外。
+ 当信号通过 <methodname
alt="signalN::operator()">signal::operator()</methodname> 调用时，
+ 该调用首先会获取信号互斥体上的锁。然后，它会获得一个句柄，指向信号的
插槽链表与合并器。
+ 接着，它会在调用合并器遍历插槽链表之前，释放信号的互斥体。因此，当插
槽执行时，信号并没有持有互斥体。
+ 选择这种设计杜绝了以下可能：插槽中运行的用户代码死锁于
Boost.Signals2 库内部使用的互斥体。
+ 它还可防止插槽意外造成对库的内部互斥体递归加锁。因此，如果您从多个线
程并发调用信号，
+ 有可能会造成信号的合并器被并发调用，从而造成插槽并发执行。
</para>
<para>
During a combiner invocation, the following steps are performed in
order to
find the next callable slot while iterating through the signal's
- slot list.
+ slot list.<sbr/>
+ 在合并器的调用中，遍历信号的插槽链表时会执行以下步骤，以找到下一个可
调用插槽。
</para>
<itemizedlist>
<listitem>
<para>The <code>Mutex</code> associated with the connection to the
- slot is locked.</para>
+ slot is locked.<sbr/>
+ 插槽的连接所关联的 <code>Mutex</code> 被锁定。</para>
</listitem>
<listitem>
<para>All the tracked <classname>weak_ptr</classname> associated
with the
@@ -76,7 +93,11 @@
automatically disconnected. Therefore a slot will never be run
if any of its tracked <classname>weak_ptr</classname> have
expired,
and none of its tracked <classname>weak_ptr</classname> will
- expire while the slot is running.
+ expire while the slot is running.<sbr/>
+ 与插槽相关的所有被跟踪的 <classname>weak_ptr</classname> 被复制到
临时的 <classname>shared_ptr</classname>，
+ 并一直生存直到插槽完成调用。如果 <classname>weak_ptr</classname>
过期无法复制，连接将自动断开。
+ 因此，如果插槽跟踪的任何 <classname>weak_ptr</classname> 过期，插
槽就不会运行，而当插槽运行时，
+ 其跟踪的 <classname>weak_ptr</classname> 不会过期。
</para>
</listitem>
<listitem>
@@ -87,7 +108,10 @@
start again from the beginning with the next slot in the slot
list.
Otherwise, we commit to executing the slot when the combiner next
dereferences the slot call iterator (unless the combiner should
increment
- the iterator without ever dereferencing it).
+ the iterator without ever dereferencing it).<sbr/>
+ 插槽的连接被检查，看它是否被阻塞或断开，然后，连接的互斥体被解
锁。如果连接被阻塞或断开，
+ 则取插槽链表中的下一个插槽重新开始。否则，当合并器下一步解引用插
槽调用迭代器时，
+ 就执行插槽，（除非合并器递增迭代器而未对其解引用）。
</para>
</listitem>
</itemizedlist>
@@ -96,7 +120,10 @@
its associated slot, it is possible a slot will still be executing
after it has been disconnected by a
<code><methodname>connection::disconnect</methodname>()</code>, if
- the disconnect was called concurrently with signal invocation.
+ the disconnect was called concurrently with signal invocation.<sbr/>
+ 注意，因为我们在执行插槽前就解锁了其对应连接的互斥体，所以有可能插槽
在用
+ <code><methodname>connection::disconnect</methodname>()</code> 断开后
仍将继续执行，
+ 如在信号调用时并发调用断开。
</para>
<para>
You may have noticed above that during signal invocation, the
invocation only
@@ -115,7 +142,15 @@
<methodname
alt="signalN::set_combiner">signal::set_combiner</methodname>
while a signal invocation is running concurrently, the concurrent
signal invocation will continue to use the old combiner undisturbed,
- while future signal invocations will receive a handle to the new
combiner.
+ while future signal invocations will receive a handle to the new
combiner.<sbr/>
+ 您可能已经注意到，在上述信号调用中，在持有信号的互斥体时，仅仅获取了
信号的插槽链表与合并器的句柄。
+ 因此并发调用信号仍可导致并发操作同一插槽链表与合并器。那么，如果插槽
链表被更改，例如，
+ 当信号调用正在进行中时，并发地连接新的插槽，会发生什么事？如果插槽链
表已在使用中，
+ 信号会在更改它之前进行深拷贝。因此，并发的信号调用将继续使用旧的未修
改的插槽链表，
+ 对于新建的插槽链表深拷贝的更改，将不会干扰到该信号调用。以后的信号调
用收到的句柄将指向新建的插槽链表深拷贝，
+ 旧的插槽链表一旦不再使用，将会被销毁。同样，如果信号调用正在运行时，
+ 用 <methodname
alt="signalN::set_combiner">signal::set_combiner</methodname> 并发地更改信号
的合并器，
+ 并发的信号调用将继续使用旧的合并器而不受干扰，而以后的信号调用将会收
到新的合并器的句柄。
</para>
<para>
The fact that concurrent signal invocations use the same combiner
object
@@ -129,14 +164,21 @@
these perils is for your combiner to release any locks before
dereferencing a slot call iterator. The combiner classes provided by
the Boost.Signals2 library are all thread-safe, since they do not
maintain
- any state across invocations.
+ any state across invocations.<sbr/>
+ 并发的信号调用使用的是同一个合并器对象，这一事实意味着，你需要确保你
写的任何自定义合并器是线程安全的。
+ 所以，如果你的合并器需要维护状态，该状态会在合并器被调用时更改，你就
可能需要用互斥体保护该状态。
+ 注意，如果您在您的合并器中持有互斥体，当插槽调用迭代器解引用时，如果
有个插槽导致了额外的互斥锁的发生，
+ 你就会有死锁和递归锁的危险。避免这些危险的一个方法是，让你的合并器在
信号调用迭代器解引用之前释放锁。
+ Boost.Signals2 库提供的合并器类都是线程安全的，因为它们在调用之间并没
有维护任何状态。
</para>
<para>
Suppose a user writes a slot which connects another slot to the
invoking signal.
Will the newly connected slot be run during the same signal
invocation in
which the new connection was made? The answer is no. Connecting a
new slot
modifies the signal's slot list, and as explained above, a signal
invocation
- already in progress will not see any modifications made to the slot
list.
+ already in progress will not see any modifications made to the slot
list.<sbr/>
+ 假设用户写了个插槽，该插槽把另一个插槽连接到调用的信号。在同一信号调
用中，这个新连接的插槽会不会运行？
+ 答案是否定的。连接新的插槽更改了信号的插槽链表，正如上文所述，正在进
行的信号调用将不会看到对插槽链表的任何更改。
</para>
<para>
Suppose a user writes a slot which disconnects another slot from the
invoking signal.
@@ -145,11 +187,15 @@
This time the answer is yes. Even if the disconnected slot is still
present in the signal's slot list, each slot is checked to see if it
is
disconnected or blocked immediately before it is executed (or not
executed as
- the case may be), as was described in more detail above.
+ the case may be), as was described in more detail above.<sbr/>
+ 假设用户写了个插槽，该插槽把另一个插槽从调用的信号断开。在同一信号调
用中，这个被断开的插槽是否无法运行？
+ 如果它在插槽链表中出现的位置在那个断开它的插槽之后呢？这一次，答案是
肯定的。
+ 即使被断开的插槽仍然存在于信号的插槽链表中，每个插槽在执行（或视情况
并不执行）前，
+ 会检查它是否已被断开或阻塞，这在上文中已有详述。
</para>
</section>
<section>
- <title>Connections and other classes</title>
+ <title>Connections and other classes 连接与其他类</title>
<para>
The methods of the <classname>signals2::connection</classname> class
are thread-safe,
with the exception of assignment and swap. This is achived via
locking the mutex
@@ -160,7 +206,13 @@
there may be many copies of a
<classname>signals2::connection</classname> object,
all of which reference the same underlying connection. There is not
a mutex
for each <classname>signals2::connection</classname> object, there
is only
- a single mutex protecting the underlying connection they reference.
+ a single mutex protecting the underlying connection they
reference.<sbr/>
+ <classname>signals2::connection</classname> 类的方法是线程安全的，除
了赋值和交换swap。
+ 这是通过对象底层的信号-插槽连接所对应的互斥体加锁实现的。赋值和交换不
是线程安全的，
+ 因为互斥体保护的是底层的连接，它是由
<classname>signals2::connection</classname> 对象所引用的，
+ 而不是 <classname>signals2::connection</classname> 对象本身。也就是
说，可能有许多份
+ <classname>signals2::connection</classname> 对象的拷贝，所有拷贝都引
用了同一个底层连接。
+ 没有针对每个 <classname>signals2::connection</classname> 对象的互斥
体，只有一个互斥体保护它们所引用的底层连接。
</para>
<para>The <classname>shared_connection_block</classname> class obtains
some thread-safety
from the <code>Mutex</code> protecting the underlying connection
which is blocked
@@ -172,14 +224,23 @@
should not be accessed concurrently by multiple threads. As long as
two
threads each have their own
<classname>shared_connection_block</classname> object,
then they may use them in safety, even if both
<classname>shared_connection_block</classname>
- objects are copies and refer to the same underlying connection.
+ objects are copies and refer to the same underlying connection.<sbr/>
+ <classname>shared_connection_block</classname> 类因为有保护其底层连接
的 <code>Mutex</code>，
+ 从而获得了一些线程安全性，该底层连接即被阻塞和解除阻塞的连接。其内部
引用计数也是线程安全的
+ （实现依赖于 <classname>shared_ptr</classname> 的引用计数），该引用计
数用来跟踪有多少
+ <classname>shared_connection_block</classname> 对象宣称阻塞它们的底层
连接。然而，单个的
+ <classname>shared_connection_block</classname> 对象不应该从多个线程并
发访问。
+ 只要两个线程都有自己的
<classname>shared_connection_block</classname> 对象，那么它们可以安全地使用
它们，
+ 即使这两个 <classname>shared_connection_block</classname> 对象是复制
关系，并指向同一个底层连接。
</para>
<para>
The <classname alt="slotN">slot</classname> class has no internal
mutex locking
built into it. It is expected that slot objects will be created then
connected to a signal in a single thread. Once they have been
copied into
a signal's slot list, they are protected by the mutex associated with
- each signal-slot connection.
+ each signal-slot connection.<sbr/>
+ <classname alt="slotN">slot</classname> 类没有内置的内部互斥锁。插槽
对象应该在一个线程内创建，
+ 然后连接到信号。它们一旦被复制到信号的插槽链表，它们就会被每个信号-插
槽连接所关联的互斥体所保护。
</para>
<para>The <classname>signals2::trackable</classname> class does NOT
provide
thread-safe automatic connection management. In particular, it
leaves open the
@@ -187,7 +248,11 @@
if the trackable-derived object is destroyed in a different thread
from the
one invoking the signal.
<classname>signals2::trackable</classname> is only provided as a
convenience
- for porting single-threaded code from Boost.Signals to
Boost.Signals2.
+ for porting single-threaded code from Boost.Signals to
Boost.Signals2.<sbr/>
+ <classname>signals2::trackable</classname> 类不提供线程安全的自动连接
管理。
+ 特别是，它留下了一种可能性，如果可跟踪子类对象在不同于引发信号的线程
中被销毁，
+ 信号调用可能会进入部分析构对象。提供
<classname>signals2::trackable</classname>
+ 仅仅是为了方便单线程代码从 Boost.Signals 移植到 Boost.Signals2。
</para>
</section>
</section>
=======================================
--- /trunk/libs/signals2/doc/tutorial.xml Thu May 7 20:34:38 2009
+++ /trunk/libs/signals2/doc/tutorial.xml Sat Jan 23 06:27:10 2010
@@ -9,7 +9,7 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-->
<section last-revision="$Date: 2007-06-12 14:01:23 -0400 (Tue, 12 Jun
2007) $" id="signals2.tutorial">
- <title>Tutorial</title>
+ <title>Tutorial 教程</title>
<using-namespace name="boost"/>
<using-namespace name="boost::signals2"/>
@@ -17,7 +17,7 @@
<using-class name="boost::signals2::slotN"/>
<section>
- <title>How to Read this Tutorial</title>
+ <title>How to Read this Tutorial 如何阅读本教程</title>
<para>This tutorial is not meant to be read linearly. Its top-level
structure roughly separates different concepts in the library
(e.g., handling calling multiple slots, passing values to and from
@@ -33,10 +33,17 @@
the <emphasis>Advanced</emphasis> sections detail very advanced uses of the
Signals2 library, that often require a solid working knowledge of
the <emphasis>Beginner</emphasis> and <emphasis>Intermediate</emphasis>
topics; most users
-will not need to read the <emphasis>Advanced</emphasis> sections.</para>
+will not need to read the <emphasis>Advanced</emphasis> sections.<sbr/>
+本教程不是用来线性阅读的。其顶层结构大致按库中不同的概念划分，（如处理多个
插槽的调用、传值到插槽及回传），
+并且在每一个概念中，首先介绍其基本思想，然后说明库较复杂的使用。每个部分都
标注了<emphasis>初级</emphasis>、
+<emphasis>中级</emphasis>，或<emphasis>高级</emphasis>，以帮助指导读者。
<emphasis>初级</emphasis>
+部分包括库的所有使用者都该了解的信息；只要阅读了<emphasis>初级</emphasis>部
分，就可以很好地使用 Signals2 库。
+<emphasis>中级</emphasis>部分建立在<emphasis>初级</emphasis> 部分之上，是库
的稍复杂的使用。
+最后，<emphasis>高级</emphasis>部分详述了 Signals2 库很高级的应用，这往往需
要对<emphasis>初级</emphasis>
+和<emphasis>中级</emphasis>内容扎实的实践经验；大多数用户无需阅读
<emphasis>高级</emphasis>部分。</para>
</section>
-<section><title>Compatibility Note</title>
+<section><title>Compatibility Note 对兼容性的注释</title>
<para>Boost.Signals2 has two syntactical forms: the preferred form and
the compatibility form. The preferred form fits more closely with the
@@ -45,11 +52,14 @@
preferred form is not supported on all platforms due to compiler
bugs. Users of Boost.Function, please note
that the preferred syntactic form in Signals2 is equivalent to that of
-Function's preferred syntactic form.</para>
+Function's preferred syntactic form.<sbr/>
+Boost.Signals2 有两种句法形式：首选形式和兼容形式。首选形式能更紧密地适合
C++语言，
+并减少需要考虑的独立模板参数的个数，往往能提高可读性；然而，由于编译器的错
误，
+首选形式并非所有平台都支持。Boost.Function 的用户请注意，Signals2 中的首选
句法形式等效于 Function 的首选句法形式</para>
</section>
-<section><title>Hello, World! (Beginner)</title>
+<section><title>Hello, World! (Beginner 初级)</title>
<para>The following example writes "Hello, World!" using signals and
slots. First, we create a signal <code>sig</code>, a signal that
takes no arguments and has a void return value. Next, we connect
@@ -57,15 +67,19 @@
<code>connect</code> method. Finally, use the signal
<code>sig</code> like a function to call the slots, which in turns
invokes <code>HelloWorld::operator()</code> to print "Hello,
-World!".</para>
+World!".<sbr/>
+下例将使用信号和插槽写出“Hello, World!”。首先，我们创建信号
<code>sig</code>，
+该信号无参数并且返回值为空。接着，我们使用 <code>connect</code> 方法将
<code>hello</code> 函数对象连接到信号。
+最后，像函数一样使用信号 <code>sig</code> 来调用插槽，它将转而调用
<code>HelloWorld::operator()</code>
+打印 “Hello, World!”。 </para>
<programlisting><xi:include href="hello_world_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -92,30 +106,36 @@
</informaltable>
</section>
-<section><title>Calling Multiple Slots</title>
-<section><title>Connecting Multiple Slots (Beginner)</title>
+<section><title>Calling Multiple Slots 调用多个插槽</title>
+<section><title>Connecting Multiple Slots (Beginner) 连接多个插槽（初级
）</title>
<para>Calling a single slot from a signal isn't very interesting, so
we can make the Hello, World program more interesting by splitting
the work of printing "Hello, World!" into two completely separate
slots. The first slot will print "Hello" and may look like
-this:</para>
+this:<sbr/>
+从信号调用单个插槽不是很有意思，因此我们将打印“Hello, World!”的工作拆分到两
个完全独立的插槽，
+让 Hello, World 程序更有趣点。第一个插槽将打印“Hello”，可能看起来像这
样：</para>
<programlisting><xi:include href="hello_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<para>The second slot will print ", World!" and a newline, to complete
-the program. The second slot may look like this:</para>
+the program. The second slot may look like this:<sbr/>
+第二个插槽将打印“, World!”和换行，以完成该程序。第二个插槽可能看起来像这
样：</para>
<programlisting><xi:include href="world_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<para>Like in our previous example, we can create a signal
<code>sig</code> that takes no arguments and has a
<code>void</code> return value. This time, we connect both a
<code>hello</code> and a <code>world</code> slot to the same
-signal, and when we call the signal both slots will be called.</para>
+signal, and when we call the signal both slots will be called.<sbr/>
+和上个例子一样，我们创建信号 <code>sig</code>，它没有参数并且返回值为
<code>void</code>。
+这次，我们将 <code>hello</code> 和 <code>world</code> 插槽都连接到同一个信
号，
+当我们调用该信号，两个插槽都将会被调用。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -138,13 +158,14 @@
</tgroup>
</informaltable>
<para>By default, slots are pushed onto the back of the slot list,
-so the output of this program will be as expected:</para>
+so the output of this program will be as expected:<sbr/>
+默认情况下，插槽会被加到插槽链表的尾部，因此该程序的输出应该是：</para>
<programlisting>
Hello, World!
</programlisting>
</section>
-<section><title>Ordering Slot Call Groups (Intermediate)</title>
+<section><title>Ordering Slot Call Groups (Intermediate) 插槽调用组排序（中
级）</title>
<para>Slots are free to have side effects, and that can mean that some
slots will have to be called before others even if they are not connected
in that order. The Boost.Signals2
library allows slots to be placed into groups that are ordered in
@@ -154,13 +175,18 @@
can supply an extra parameter at the beginning of the
<code>connect</code> call that specifies the group. Group values
are, by default, <code>int</code>s, and are ordered by the integer
-< relation. Here's how we construct Hello, World:</para>
+< relation. Here's how we construct Hello, World:<sbr/>
+插槽可以有副作用，这意味着某些插槽必须在另一些之前调用，即使它们不是按那个
次序连接的。
+Boost.Signals2 库允许插槽进行分组，并按某种方式排序编组。对于我们的 Hello,
World 程序，
+我们要“Hello”在“, World!”之前打印，所以我们将“Hello”放入一个组，该组将在“,
World!”所在组之前执行。
+为了做到这一点，我们可以在 <code>connect</code> 调用的头部提供一个额外的参
数，以指定编组。
+编组值默认为 <code>int</code>，并按整型的 < 关系排序。我们这样构造
Hello, World：</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -198,16 +224,25 @@
will be placed within the group ordering. Ungrouped slots connected with
<code>at_front</code> will always precede all grouped slots. Ungrouped
slots connected with <code>at_back</code> will always succeed all
-grouped slots.
-</para>
+grouped slots.<sbr/>
+调用该信号将正确打印出“Hello, World!”，因为 <code>Hello</code> 对象在组
0，它在 <code>World</code> 对象所在的组 1 之前。
+编组参数实际上是可选的。在第一个 Hello World 例子中我们省略了它，因为当所有
的插槽都独立时，编组是不必要的。
+那么，如果我们混合调用使用和不使用编组参数的连接会怎样？“未命名”插槽（即那
些连接时未指定组名的插槽）
+可置于插槽链表的头部或尾部（通过向 <code><methodname
alt="boost::signals2::signalN::connect">connect</methodname></code>
+分别传入 <code>boost::signals2::at_front</code> 或
<code>boost::signals2::at_back</code> 作为最后的参数），
+而默认为链表的结尾。当指定了编组时，最后的参数 <code>at_front</code> 或
<code>at_back</code> 描述的是插槽在组内的次序。
+以 <code>at_front</code> 连接的未分组的插槽将总是在所有分组的插槽之前。
+以 <code>at_back</code> 连接的未分组的插槽将总是在所有分组的插槽之后。
</para>
<para>
- If we add a new slot to our example like this:
+ If we add a new slot to our example like this:<sbr/>
+ 如果在我们的例子中添加新的插槽，如下：
</para>
<programlisting><xi:include href="good_morning_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<programlisting><xi:include
href="hello_world_ordered_invoke_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
-<para>... we will get the result we wanted:</para>
+<para>... we will get the result we wanted:<sbr/>
+... 我们会得到想要的结果：</para>
<programlisting>
Hello, World!
... and good morning!
@@ -215,24 +250,28 @@
</section>
</section>
-<section><title>Passing Values to and from Slots</title>
-<section><title>Slot Arguments (Beginner)</title>
+<section><title>Passing Values to and from Slots 传值到插槽及回传</title>
+<section><title>Slot Arguments (Beginner) 插槽的参数（初级）</title>
<para>Signals can propagate arguments to each of the slots they call.
For instance, a signal that propagates mouse motion events might
want to pass along the new mouse coordinates and whether the mouse
-buttons are pressed.</para>
+buttons are pressed.<sbr/>
+信号可以向它们调用的每个插槽传递参数。例如，
+一个传递鼠标移动事件的信号可能要传入新的鼠标坐标以及是否按了鼠标键。</para>
<para>As an example, we'll create a signal that passes two
<code>float</code> arguments to its slots. Then we'll create a few
slots that print the results of various arithmetic operations on
-these values.</para>
+these values.<sbr/>
+例如，我们创建一个信号，它将传入两个 float 参数到它的插槽。
+然后我们再创建几个插槽，打印对这两个参数进行算术运算的各种结果。</para>
<programlisting><xi:include
href="slot_arguments_slot_defs_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -257,7 +296,8 @@
</tgroup>
</informaltable>
-<para>This program will print out the following:</para>
+<para>This program will print out the following:<sbr/>
+该程序将打印输出如下：</para>
<programlisting>The arguments are 5 and 3
The sum is 8
The product is 15
@@ -270,10 +310,13 @@
float)></code> means that the signal has a <code>void</code>
return value and takes two <code>float</code> values. Any slot
connected to <code>sig</code> must therefore be able to take two
-<code>float</code> values.</para>
+<code>float</code> values.<sbr/>
+当像函数一样调用 <code>sig</code> 时，输入它的任何值都传给了每一个插槽。创
建信号时，我们必须预先声明这些值的类型。
+类型 <code><classname>boost::signals2::signal</classname><void (float,
float)></code> 表明信号具有 <code>void</code>
+返回值并接受两个 <code>float</code> 值。因此任何连接到 <code>sig</code> 的
插槽都必须能够接受两个 <code>float</code> 值。</para>
</section>
-<section><title>Signal Return Values (Advanced)</title>
+<section><title>Signal Return Values (Advanced) 信号返回值（高级）</title>
<para>Just as slots can receive arguments, they can also return
values. These values can then be returned back to the caller of the
signal through a <firstterm>combiner</firstterm>. The combiner is a
mechanism
@@ -283,19 +326,25 @@
The single result is often a simple function of the results of the
slot calls: the result of the last slot call, the maximum value
returned by any slot, or a container of all of the results are some
-possibilities.</para>
+possibilities.<sbr/>
+正如插槽可以接收参数，它们也可以返回值。然后这些值可以通过 <firstterm>合并
器</firstterm> 返回给信号的调用者。
+合并器是这样一种工具，它接收插槽调用的结果（可能没有结果，也可能有100个结
果；程序运行时才知道），
+并且把它们合并成单一的结果返回给调用者。 该单一的结果往往是插槽调用结果的一
个简单函数，可能是：
+最后的插槽调用的结果、所有插槽返回值的最大值，或包含所有结果的容器。</para>
<para>We can modify our previous arithmetic operations example
slightly so that the slots all return the results of computing the
product, quotient, sum, or difference. Then the signal itself can
-return a value based on these results to be printed:</para>
+return a value based on these results to be printed:<sbr/>
+我们可以稍微修改前面的算术运算的例子，使插槽分别返回加减乘除的计算结果。
+然后信号本身就可以根据这些结果返回一个值，并打印出来。</para>
<programlisting><xi:include
href="signal_return_value_slot_defs_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -320,10 +369,15 @@
then return a <classname>boost::optional</classname> containing
the result returned by the last slot called. This
behavior is admittedly silly for this example, because slots have
-no side effects and the result is the last slot connected.</para>
+no side effects and the result is the last slot connected.<sbr/>
+该例程将输出 <code>2</code>。这是因为具有返回类型（<code>float</code>，即输
入
+<code><classname>boost::signals2::signal</classname></code> 类模板的第一个
模板参数）的信号的默认行为是，
+调用所有的插槽，然后返回一个包含最后一次调用插槽所返回的结果的
<classname>boost::optional</classname>。
+对本例来说，该行为确实有点傻，因为这些插槽没有副作用，所以结果就是最后连接
的插槽。</para>
<para>A more interesting signal result would be the maximum of the
values returned by any slot. To do this, we create a custom
-combiner that looks like this:</para>
+combiner that looks like this:<sbr/>
+求所有插槽返回值的最大值，这样的信号结果才有点意思。为此，我们创建一个自定
义合并器如下：</para>
<programlisting><xi:include
href="custom_combiners_maximum_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<para>The <code>maximum</code> class template acts as a function
@@ -335,16 +389,23 @@
iterator sequence <code>[first, last)</code> that includes the
results of calling all of the slots. <code>maximum</code> uses this
input iterator sequence to calculate the maximum element, and
-returns that maximum value.</para>
+returns that maximum value.<sbr/>
+<code>maximum</code> 类模板就像一个函数对象。它的结果类型由其模板参数给出，
+并且它正是基于该类型计算最大值（例如，<code>maximum<float></code> 将
在一系列
+<code>float</code> 中查找最大的 <code>float</code>）。当调用
<code>maximum</code> 对象时，
+将给出一个输入迭代器序列 <code>[first, last)</code>，其中包含了所有插槽调用
的结果。
+<code>maximum</code> 利用该输入迭代器序列来计算最大元素，并返回那个最大值。
</para>
<para>We actually use this new function object type by installing it
as a combiner for our signal. The combiner template argument
-follows the signal's calling signature:</para>
+follows the signal's calling signature:<sbr/>
+我们要把这个新的函数对象作为合并器安装到我们的信号，才能实际使用它。
+合并器模板参数跟在信号的调用签名式之后。</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -367,27 +428,32 @@
</informaltable>
<para>Now we can connect slots that perform arithmetic functions and
-use the signal:</para>
+use the signal:<sbr/>
+现在我们可以连接执行算术功能的插槽并使用信号了：</para>
<programlisting><xi:include
href="custom_combiners_maximum_usage_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<para>The output of this program will be <code>15</code>, because
regardless of the order in which the slots are connected, the product
of 5 and 3 will be larger than the quotient, sum, or
-difference.</para>
+difference.<sbr/>
+该程序的输出为 <code>15</code>，因为不管插槽的连接次序如何，5 和 3 的乘积将
大于商、和，或差。</para>
<para>In other cases we might want to return all of the values
computed by the slots together, in one large data structure. This
-is easily done with a different combiner:</para>
+is easily done with a different combiner:<sbr/>
+在其他情况下，我们可能需要同时返回插槽计算的所有值，如保存在一个大型的数据
结构中。
+用一个不同的合并器就可以轻松做到：</para>
<programlisting><xi:include
href="custom_combiners_aggregate_values_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<para>
-Again, we can create a signal with this new combiner:
+Again, we can create a signal with this new combiner:<sbr/>
+我们再次用这个新的合并器创建信号：
</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -416,7 +482,11 @@
also be the <code>value_type</code> of the input iterators passed
to the combiner. The combiner itself is a function object and its
<code>result_type</code> member type becomes the return type of the
-signal.</para>
+signal.<sbr/>
+该程序的输出将包含 15、8、1.6667，和 2。有趣的是，<code>signal</code> 类的
第一个模板参数，
+<code>float</code>，竟然不是信号的返回类型。相反，该参数是所连接插槽的返回
类型，
+并且它也是传入合并器的输入迭代器的 <code>value_type</code>。合并器本身是个
函数对象，
+并且它的 <code>result_type</code> 成员类型将成为信号的返回类型。</para>
<para>The input iterators passed to the combiner transform dereference
operations into slot calls. Combiners therefore have the option to
invoke only some slots until some particular criterion is met. For
@@ -429,7 +499,13 @@
return when the value is acceptable. The following combiner returns
the first non-NULL pointer to a <code>FulfilledRequest</code> data
structure, without asking any later slots to fulfill the
-request:</para>
+request:<sbr/>
+传给合并器的输入迭代器会将解引用操作转换为插槽调用。因此合并器可选择仅调用
某些符合特定条件的插槽。
+例如，在分布计算系统中，合并器可能会询问每个远程系统能否处理请求。对于一个
特定请求，
+仅需一个远程系统进行处理，因此当一个远程系统接受该工作后，我们将不再要求任
何其他远程系统来做同一个任务。
+这样一个合并器只需检查迭代器解引用的返回值，并当该值可以接受时就返回。
+以下的合并器返回第一个指向 <code>FulfilledRequest</code> 数据结构的非空指
针，
+而不必要求任何以后的插槽来完成请求：</para>
<programlisting>
struct DistributeRequest {
typedef FulfilledRequest* result_type;
@@ -449,12 +525,14 @@
</section>
</section>
-<section><title>Connection Management</title>
-<section><title>Disconnecting Slots (Beginner)</title>
+<section><title>Connection Management 连接管理</title>
+<section><title>Disconnecting Slots (Beginner) 断开插槽（初级）</title>
<para>Slots aren't expected to exist indefinitely after they are
connected. Often slots are only used to receive a few events and
are then disconnected, and the programmer needs control to decide
-when a slot should no longer be connected.</para>
+when a slot should no longer be connected.<sbr/>
+插槽在连接之后不必无限期地存在。插槽往往只是用来接收一些事件然后断开，
+当插槽不再需要保持连接时，程序员可以做出决定并控制。</para>
<para>The entry point for managing connections explicitly is the
<code><classname>boost::signals2::connection</classname></code> class. The
<code><classname>connection</classname></code> class uniquely represents
the connection
@@ -464,12 +542,18 @@
disconnects the signal and slot if they are connected before it is
called. Each call to the signal's <code>connect()</code> method
returns a connection object, which can be used to determine if the
-connection still exists or to disconnect the signal and slot.</para>
+connection still exists or to disconnect the signal and slot.<sbr/>
+显式管理连接的入口点是
<code><classname>boost::signals2::connection</classname></code> 类。
+<code><classname>connection</classname></code> 类唯一代表了特定信号与特定插
槽之间的连接。
+<code><methodname
alt="connection::connected">connected</methodname>()</code> 方法检查信号与插
槽是否仍保持连接，
+如果信号与插槽是连接着的，<code><methodname
alt="connection::disconnect">disconnect()</methodname></code>
+方法断开它们的连接。每次调用信号的 <code>connect()</code> 方法，就返回一个
连接对象，
+该对象用于确定连接是否仍然存在，或者用于断开信号和插槽。</para>
<programlisting><xi:include href="disconnect_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
</section>
-<section><title>Blocking Slots (Beginner)</title>
+<section><title>Blocking Slots (Beginner) 阻塞插槽（初级）</title>
<para>Slots can be temporarily "blocked", meaning that they will be
ignored when the signal is invoked but have not been permanently
disconnected.
@@ -483,19 +567,27 @@
on all the
<code>shared_connection_block</code> objects that reference the connection.
Here is an example of
-blocking/unblocking slots:</para>
+blocking/unblocking slots:<sbr/>
+插槽可以被临时“阻塞”，即当信号被调用时，这些插槽将被忽略，但并没有被永久地
断开。
+这主要用于防止无限递归，如有时，要没有阻塞，插槽运行时会再次调用它所连接的
信号。
+<classname>boost::signals2::shared_connection_block</classname> 对象会临时
阻塞插槽。
+要解除阻塞，需要销毁所有引用该连接的 <code>shared_connection_block</code>
对象，
+或者调用它们的 <methodname
alt="shared_connection_block::unblock">unblock</methodname>。
+以下是阻塞插槽和解除的例子：</para>
<programlisting><xi:include href="block_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
</section>
-<section><title>Scoped Connections (Intermediate)</title>
+<section><title>Scoped Connections (Intermediate) 域内连接（中级）</title>
<para>The <classname>boost::signals2::scoped_connection</classname> class
references a signal/slot connection that will be disconnected when
the <code>scoped_connection</code> class goes out of scope. This
ability is useful when a connection need only be temporary,
-e.g.,</para>
+e.g.,<sbr/>
+<classname>boost::signals2::scoped_connection</classname> 类引用了一个信号
/插槽的连接，
+当 <code>scoped_connection</code> 类出作用域时，该连接将会被断开。当仅需临
时连接时，该功能很有用，如：</para>
<programlisting><xi:include href="scoped_connection_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
@@ -503,7 +595,9 @@
Note, attempts to initialize a scoped_connection with the assignment
syntax
will fail due to it being noncopyable. Either the explicit
initialization syntax
or default construction followed by assignment from a
<classname>connection</classname>
- will work:
+ will work:<sbr/>
+ 注意，试图用赋值语句初始化 scoped_connection 会失败，因为它是不可拷贝的。
应该使用显式初始化，
+ 或者缺省构造然后用 <classname>connection</classname> 对它赋值：
</para>
<programlisting>
// doesn't compile due to compiler attempting to copy a temporary
scoped_connection object
@@ -518,13 +612,14 @@
</programlisting>
</section>
-<section><title>Disconnecting Equivalent Slots (Intermediate)</title>
+<section><title>Disconnecting Equivalent Slots (Intermediate) 断开等价的插
槽（中级）</title>
<para>One can disconnect slots that are equivalent to a given function
object using a form of the
<code><methodname
alt="signalN::disconnect">signal::disconnect</methodname></code> method, so
long as
the type of the function object has an accessible <code>==</code>
-operator. For instance:
-
+operator. For instance:<sbr/>
+你可以使用 <code><methodname
alt="signalN::disconnect">signal::disconnect</methodname></code>
+方法断开与给定函数对象等价的多个插槽，只要该函数对象的类型具有可访问的
<code>==</code> 运算符。例如：
</para>
<programlisting><xi:include href="disconnect_by_slot_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
@@ -532,8 +627,8 @@
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -553,20 +648,23 @@
<programlisting><xi:include
href="disconnect_by_slot_usage_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
-<section id="signals2.tutorial.connection-management"><title>Automatic
Connection Management (Intermediate)</title>
+<section id="signals2.tutorial.connection-management"><title>Automatic
Connection Management (Intermediate) 自动连接管理（中级）</title>
<para>Boost.Signals2 can automatically track the lifetime of objects
involved in signal/slot connections, including automatic
disconnection of slots when objects involved in the slot call are
destroyed. For instance, consider a simple news delivery service,
where clients connect to a news provider that then sends news to
all connected clients as information arrives. The news delivery
-service may be constructed like this: </para>
+service may be constructed like this: <sbr/>
+Boost.Signals2 能自动跟踪信号/插槽连接中所涉及对象的生命期，包括当插槽调用
中涉及的对象销毁时自动断开插槽。
+例如，考虑一个简单的新闻发送服务，其中客户会连接到新闻提供者，而新闻提供者
一有信息到达，
+就发送新闻到所有连接的客户。该新闻发送服务可能像这样构造：</para>
<informaltable>
<tgroup cols="2" align="left">
<thead>
<row>
- <entry>Preferred syntax</entry>
- <entry>Portable syntax</entry>
+ <entry>Preferred syntax 首选句法</entry>
+ <entry>Portable syntax 兼容句法</entry>
</row>
</thead>
<tbody>
@@ -596,7 +694,8 @@
function object that can receive news items to the
<code>deliverNews</code> signal. For instance, we may have a
special message area in our application specifically for news,
-e.g.,:</para>
+e.g.,:<sbr/>
+希望接收新闻更新的客户只需连接一个函数对象，该对象可以接收传给
<code>deliverNews</code> 信号的新闻条目，例如：</para>
<programlisting>
struct NewsMessageArea : public MessageArea
{
@@ -630,7 +729,13 @@
its lifetime, and pass the shared_ptr to the slot via its
<methodname alt="boost::signals2::slotN::track">slot::track</methodname>
method before connecting it,
-e.g.:</para>
+e.g.:<sbr/>
+不过，如果用户关闭新闻讯息区，销毁了 <code>deliverNews</code> 所知的
<code>newsMessageArea</code> 对象，那会怎么样？
+最有可能的是产生段错误。然而，在Boost.Signals2中，使用 <methodname
alt="boost::signals2::slotN::track">slot::track</methodname>，
+你可以跟踪由 shared_ptr 管理的任何对象，当插槽的任一个被跟踪对象失效时，插
槽会自动断开。另外，当插槽正在执行时，
+Boost.Signals2 会保证它所关联的被跟踪对象不会失效。为此，插槽在执行前会创建
被跟踪对象的临时 shared_ptr 副本。
+为了跟踪 <code>newsMessageArea</code>，我们用 shared_ptr 管理其生命期，并在
连接它之前，
+通过其 <methodname
alt="boost::signals2::slotN::track">slot::track</methodname> 方法，把
shared_ptr 传给插槽。例如：</para>
<programlisting>
// ...
boost::shared_ptr<NewsMessageArea> newsMessageArea(new
NewsMessageArea(/* ... */));
@@ -642,7 +747,9 @@
Note there is no explicit call to bind() needed in the above example.
If the
<classname alt="slotN">slot</classname> constructor is passed more than
one
argument, it will automatically pass all the arguments to
<code>bind</code> and use the
- returned function object.
+ returned function object.<sbr/>
+ 注意上例中不需要显式调用 bind()。 如果 <classname
alt="slotN">slot</classname> 构造函数传入一个以上的参数，
+ 它会自动将所有参数传给 <code>bind</code>， 并使用返回的函数对象。
</para>
<para>Also note, we pass an ordinary pointer as the
second argument to the slot constructor, using
<code>newsMessageArea.get()</code>
@@ -652,19 +759,27 @@
from expiring. However, the use of
<methodname alt="boost::signals2::slotN::track">slot::track</methodname>
implies we wish to allow the tracked object to expire, and automatically
- disconnect the connection when this occurs.
+ disconnect the connection when this occurs.<sbr/>
+ 还要注意插槽构造函数的第2个参数，我们使用
<code>newsMessageArea.get()</code>，传入了一个普通指针，
+ 而不是 <code>shared_ptr</code> 本身。如果传入
<code>newsMessageArea</code> 本身，插槽函数将绑定一个
+ <code>shared_ptr</code> 副本，从而妨碍了 <code>shared_ptr</code> 的失效。
然而，使用
+ <methodname alt="boost::signals2::slotN::track">slot::track</methodname>
意味着我们希望允许被跟踪对象失效，
+ 并且当它发生时自动断开连接。
</para>
</section>
<section id="signals2.tutorial.deconstruct">
- <title>Postconstructors and Predestructors (Advanced)</title>
+ <title>Postconstructors and Predestructors (Advanced) 后构造器和预析构
器（高级）</title>
<para>One limitation of using <code>shared_ptr</code> for tracking is
that
an object cannot setup tracking of itself in its constructor.
However, it is
possible to set up tracking in a post-constructor which is called
after the
object has been created and passed to a
<classname>shared_ptr</classname>.
The Boost.Signals2
library provides support for post-constructors and pre-destructors
- via the <functionname>deconstruct()</functionname> factory function.
+ via the <functionname>deconstruct()</functionname> factory
function.<sbr/>
+ 利用 <code>shared_ptr</code> 跟踪有一个限制：对象不能在其构造函数中建
立对自身的跟踪。
+ 然而，可以在后构造器中建立跟踪，它会在对象创建并传给
<classname>shared_ptr</classname> 之后被调用。
+ Boost.Signals2 库通过 <functionname>deconstruct()</functionname> 工厂
方法， 对后构造器和预析构器提供了支持。
</para>
<para>
For most cases, the simplest and most robust way to setup
postconstructors
@@ -674,12 +789,20 @@
access to the private constructors by declaring
<classname>deconstruct_access</classname>
a friend. This will ensure that objects of the class may only be
created
through the <functionname>deconstruct()</functionname> function, and
their
- associated <code>adl_postconstruct()</code> function will always be
called.
+ associated <code>adl_postconstruct()</code> function will always be
called.<sbr/>
+ 在多数情况下，为类建立后构造器的最简单最可靠的方法是：定义一个相关的
<code>adl_postconstruct</code> 函数，
+ 让它可以被 <functionname>deconstruct()</functionname> 找到，让类的构
造函数为私有的，
+ 并通过声明 <classname>deconstruct_access</classname> 为友元，
+ 让 <functionname>deconstruct</functionname> 可以访问私有的构造函数。
+ 这将保证类的对象只能通过 <functionname>deconstruct()</functionname>
函数创建，
+ 而它们相关的 <code>adl_postconstruct()</code> 函数总是会被调用。
</para>
<para>The <link
linkend="signals2.examples.deconstruct">examples</link> section
contains several examples of defining classes with postconstructors
and
predestructors, and creating objects of these classes using
- <functionname>deconstruct()</functionname>
+ <functionname>deconstruct()</functionname><sbr/>
+ <link linkend="signals2.examples.deconstruct">例程</link> 一节中有几
个例子，
+ 它们用后构造器和预析构器来定义类，并用
<functionname>deconstruct()</functionname> 创建这些类的对象。
</para>
<para>
Be aware that the postconstructor/predestructor support in
Boost.Signals2
@@ -689,51 +812,71 @@
define static factory functions for your classes. The
factory function can create an object, pass ownership of the object
to
a <classname>shared_ptr</classname>, setup tracking for the object,
- then return the <classname>shared_ptr</classname>.
+ then return the <classname>shared_ptr</classname>.<sbr/>
+ 注意，Boost.Signals2 中对 后构造器/预析构器 的支持对于库的使用并非是
必须的。
+ <functionname>deconstruct</functionname> 的使用完全是可选的。另一选择
是为你的类定义静态工厂函数。
+ 该工厂函数可以创建对象，传递对象所有权到
<classname>shared_ptr</classname>，为对象建立跟踪，
+ 然后返回 <classname>shared_ptr</classname>。
</para>
</section>
-<section><title>When Can Disconnections Occur? (Intermediate)</title>
+<section><title>When Can Disconnections Occur? (Intermediate) 何时断
开？（中级）</title>
<para>Signal/slot disconnections occur when any of these conditions
-occur:</para>
+occur:<sbr/>
+以下任一条件发生时，信号/插槽将断开：</para>
<itemizedlist>
<listitem><para>The connection is explicitly disconnected via the
connection's
<code>disconnect</code> method directly, or indirectly via the
signal's <code>disconnect</code> method, or
-<code>scoped_connection</code>'s destructor.</para></listitem>
+<code>scoped_connection</code>'s destructor.<sbr/>
+连接被显式地断开：直接通过连接的 <code>disconnect</code> 方法，或间接地通过
信号的 <code>disconnect</code> 方法，
+或 <code>scoped_connection</code> 的析构函数。</para></listitem>
<listitem><para>An object tracked by the slot is
-destroyed.</para></listitem>
-<listitem><para>The signal is destroyed.</para></listitem></itemizedlist>
+destroyed.<sbr/>
+插槽所跟踪的对象被销毁。</para></listitem>
+<listitem><para>The signal is destroyed.<sbr/>
+信号被销毁。</para></listitem></itemizedlist>
<para>These events can occur at any time without disrupting a signal's
calling sequence. If a signal/slot connection is disconnected at
any time during a signal's calling sequence, the calling sequence
will still continue but will not invoke the disconnected slot.
Additionally, a signal may be destroyed while it is in a calling
sequence, and which case it will complete its slot call sequence
-but may not be accessed directly.</para>
+but may not be accessed directly.<sbr/>
+这些事件可以发生于任何时间，而不会破坏信号的调用序列。如果信号/插槽的连接在
信号调用序列的任意时刻被断开，
+调用序列仍将继续，只是不会调用被断开的插槽。此外，信号可以在调用序列中间被
销毁，这时，
+它将完成其插槽调用序列，只是不可以被直接访问。</para>
<para>Signals may be invoked recursively (e.g., a signal A calls a
slot B that invokes signal A...). The disconnection behavior does
not change in the recursive case, except that the slot calling
sequence includes slot calls for all nested invocations of the
-signal.</para>
+signal.<sbr/>
+信号可以被递归调用（例如，信号A调用插槽B，而插槽B又调用信号A……）。
+递归情况下，断开的行为不会改变，只是插槽调用序列包括所有嵌套的信号调用。
</para>
<para>
Note, even after a connection is disconnected, its's associated slot
may still be in the process of executing. In other words, disconnection
does not block waiting for the connection's associated slot to complete
execution.
This situation may occur in a multi-threaded environment if the
disconnection occurs concurrently with signal invocation,
- or in a single-threaded environment if a slot disconnects itself.
+ or in a single-threaded environment if a slot disconnects itself.<sbr/>
+ 注意，即使在连接断开后，其相关的插槽可能仍处于执行中。也就是说，断开连接
不会停止等待连接相关的插槽完成执行。
+ 该情形可以发生在多线程环境下，如断开连接与信号调用并行发生，或者在单线程
环境下，如插槽断开自身。
</para>
</section>
-<section><title>Passing Slots (Intermediate)</title>
+<section><title>Passing Slots (Intermediate) 传递插槽（中级）</title>
<para>Slots in the Boost.Signals2 library are created from arbitrary
function objects, and therefore have no fixed type. However, it is
commonplace to require that slots be passed through interfaces that
cannot be templates. Slots can be passed via the
<code>slot_type</code> for each particular signal type and any
function object compatible with the signature of the signal can be
-passed to a <code>slot_type</code> parameter. For instance:</para>
+passed to a <code>slot_type</code> parameter. For instance:<sbr/>
+Boost.Signals2 库中的插槽可以从任意的函数对象创建，因此没有固定的类型。
+不过通常要求通过不可模板化的接口传递插槽。对于每个特定的信号类型，
+都可以通过 <code>slot_type</code> 传递插槽，而与信号的签名式兼容的任意函数
对象，
+都可以传给 <code>slot_type</code> 参数。例如：</para>
<programlisting><xi:include href="passing_slots_defs_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"/></programlisting>
<programlisting>
@@ -743,19 +886,24 @@
<para>The <code>doOnClick</code> method is now functionally equivalent
to the <code>connect</code> method of the <code>onClick</code>
signal, but the details of the <code>doOnClick</code> method can be
-hidden in an implementation detail file.</para>
+hidden in an implementation detail file.<sbr/>
+<code>doOnClick</code> 方法现在功能上等效于 <code>onClick</code> 信号的
<code>connect</code> 方法，
+但是 <code>doOnClick</code> 方法的细节可以隐藏于细节实现文件中。 </para>
</section>
</section>
<section id="signals2.tutorial.document-view">
- <title>Example: Document-View</title>
+ <title>Example: Document-View 例子：文档-视图</title>
<para>Signals can be used to implement flexible Document-View
architectures. The document will contain a signal to which each of
the views can connect. The following <code>Document</code> class
defines a simple text document that supports mulitple views. Note
that it stores a single signal to which all of the views will be
- connected.</para>
+ connected.<sbr/>
+ 信号可用于实现灵活的文档-视图架构。文档包含一个信号，而每个视图连接该信
号。
+ 下面的 <code>Document</code> 类定义了一个简单的支持多视图的文本文档。
+ 注意它保存了一个单一的信号，所有视图都连接到该信号。</para>
<programlisting><xi:include href="document_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude";
parse="xml"/></programlisting>
@@ -763,7 +911,8 @@
<para>
Next, we can begin to define views. The
following <code>TextView</code> class provides a simple view of the
- document text.
+ document text.<sbr/>
+ 接下来，我们可以开始定义视图。 以下 <code>TextView</code> 类是对文档文
本的一个简单视图。
</para>
<programlisting><xi:include href="text_view_def_code_snippet.xml"
@@ -771,7 +920,8 @@
<para>Alternatively, we can provide a view of the document
translated into hex values using the <code>HexView</code>
- view:</para>
+ view:<sbr/>
+ 此外，我们可以提供文档翻译成16进制后的视图，如 <code>HexView</code> 视
图：</para>
<programlisting><xi:include href="hex_view_def_code_snippet.xml"
xmlns:xi="http://www.w3.org/2001/XInclude";
parse="xml"/></programlisting>
@@ -779,7 +929,8 @@
<para>
To tie the example together, here is a
simple <code>main</code> function that sets up two views and then
- modifies the document:
+ modifies the document:<sbr/>
+ 为了把例子串起来， 有个简单的 <code>main</code> 函数，它建立了两个视
图，然后更改文档：
</para>
<programlisting><xi:include href="document_view_main_code_snippet.xml"
@@ -788,12 +939,14 @@
<para>The complete example source, contributed by Keith MacDonald,
is available in the <link
linkend="signals2.examples.document-view">examples</link> section.
We also provide variations on the program which employ automatic
connection management
- to disconnect views on their destruction.
+ to disconnect views on their destruction.<sbr/>
+ 完整的例程源码，由 Keith MacDonald 提供，在 <link
linkend="signals2.examples.document-view">例程</link>一节中。
+ 同时我们提供了该程序的更改版，它们使用了自动连接管理，能在视图析构时断
开视图。
</para>
</section>
<section id="signals2.tutorial.extended-slot-type">
- <title>Giving a Slot Access to its Connection (Advanced)</title>
+ <title>Giving a Slot Access to its Connection (Advanced) 让插槽可以操作
其连接（高级）</title>
<para>
You may encounter situations where you wish to disconnect or block a
slot's
connection from within the slot itself. For example, suppose you
have a group
@@ -803,7 +956,11 @@
given task completes and the slot is run, the slot no longer needs
to be
connected to the completed task.
Therefore, you may wish to clean up old connections by having the
slot
- disconnect its invoking connection when it runs.
+ disconnect its invoking connection when it runs.<sbr/>
+ 可能有这样的情形：你希望在插槽中断开或阻塞插槽本身的连接。例如，有一
组异步任务，
+ 当每个任务完成时会发出信号。你希望用一个插槽连接所有的任务，来接收它
们完成时的结果。
+ 一旦某个任务完成并且插槽被运行，该插槽就不必再连接到这个已经完成的任
务。
+ 因此，你可能希望让插槽运行时断开其连接，以清理旧连接。
</para>
<para>
For a slot to disconnect (or block) its invoking connection, it must
have
@@ -814,7 +971,12 @@
method, and therefore is not available until after the slot is
already connected to the signal. This can be particularly
troublesome
in a multi-threaded environment where the signal may be invoked
- concurrently by a different thread while the slot is being connected.
+ concurrently by a different thread while the slot is being
connected.<sbr/>
+ 为了让插槽断开（或阻塞）其连接，它必须能够操作
<classname>connection</classname> 对象，
+ 即调用的信号-插槽连接对象。难点是，<classname>connection</classname>
对象是由
+ <methodname alt="signalN::connect">signal::connect</methodname> 方法
返回的，
+ 因此只有在插槽连接信号之后才能用。在多线程环境下，这尤其麻烦，当插槽
正在被连接时，
+ 信号可能被其他线程并发调用。
</para>
<para>
Therefore, the signal classes provide
@@ -825,18 +987,24 @@
<methodname
alt="signalN::connect_extended">signal::connect_extended</methodname>
uses slots of the type given by the
<classname
alt="signalN::extended_slot_type">signal::extended_slot_type</classname>
- typedef.
+ typedef.<sbr/>
+ 因此，信号类提供了 <methodname
alt="signalN::connect_extended">signal::connect_extended</methodname> 方法，
+ 它允许连接信号的插槽接受一个额外参数。该额外参数是个
<classname>connection</classname> 对象，
+ 它指向当前调用插槽的信号-插槽连接。<methodname
alt="signalN::connect_extended">signal::connect_extended</methodname>
+ 使用的插槽类型由 <classname
alt="signalN::extended_slot_type">signal::extended_slot_type</classname> 定
义。
</para>
<para>
The examples section includes an
<link
linkend="signals2.examples.tutorial.extended_slot">extended_slot</link>
program which demonstrates the syntax for using
- <methodname
alt="signalN::connect_extended">signal::connect_extended</methodname>.
+ <methodname
alt="signalN::connect_extended">signal::connect_extended</methodname>.<sbr/>
+ 例程一节中有个 <link
linkend="signals2.examples.tutorial.extended_slot">extended_slot</link> 程
序，
+ 它演示了 <methodname
alt="signalN::connect_extended">signal::connect_extended</methodname> 的用
法。
</para>
</section>
<section id="signals2.tutorial.signal-mutex-template-parameter">
- <title>Changing the <code>Mutex</code> Type of a Signal
(Advanced).</title>
+ <title>Changing the <code>Mutex</code> Type of a Signal (Advanced). 改
变信号的互斥体类型（高级）</title>
<para>
For most cases the default type of
<classname>boost::signals2::mutex</classname> for
a <classname>signal</classname>'s <code>Mutex</code> template type
parameter should
@@ -844,7 +1012,11 @@
and fulfill the <code>Lockable</code> concept defined by the
Boost.Thread library.
That is, it must have <code>lock()</code> and <code>unlock()</code>
methods
(the <code>Lockable</code> concept also includes a
<code>try_lock()</code> method
- but this library does not require try locking).
+ but this library does not require try locking).<sbr/>
+ <classname>signal</classname> 的模板类型参数 <code>Mutex</code> 默认
为 <classname>boost::signals2::mutex</classname>，
+ 多数情况下，这应该能行。如果你希望使用其他的互斥体类型，那么它必须可
缺省构造，并且满足由 Boost.Thread 库所定义的
+ <code>Lockable</code> 概念。即，它必须具有 <code>lock()</code> 和
<code>unlock()</code> 方法（<code>Lockable</code>
+ 概念同时包含了 <code>try_lock()</code> 方法，但本库没用到）。
</para>
<para>
The Boost.Signals2 library provides one alternate mutex class for
use with <classname>signal</classname>:
@@ -852,7 +1024,11 @@
use in single-threaded programs, where locking a real mutex would be
useless
overhead. Other mutex types you could use with
<classname>signal</classname> include
<classname>boost::mutex</classname> and the <code>std::mutex</code>
from
- C++0x.
+ C++0x.<sbr/>
+ Boost.Signals2 库提供了另外一个可用于 <classname>signal</classname>
的互斥类：
+ <classname>boost::signals2::dummy_mutex</classname>。这是个用于单线程
的假互斥体，因为在单线程中，
+ 用真实的互斥体加锁是无谓的开销。其它可用于
<classname>signal</classname> 的互斥体类型有：
+ <classname>boost::mutex</classname> 和 C++0x 的
<code>std::mutex</code>。
</para>
<para>
Changing a signal's <code>Mutex</code> template type parameter can
be tedious, due to
@@ -861,7 +1037,12 @@
since it enables named template type parameters for the
<classname>signal</classname>
class. For example, to declare a signal which takes an
<code>int</code> as
an argument and uses a
<classname>boost::signals2::dummy_mutex</classname>
- for its <code>Mutex</code> types, you could write:
+ for its <code>Mutex</code> types, you could write:<sbr/>
+ 更改信号的 <code>Mutex</code> 模板类型参数很烦，因为在它之前有许多模
板参数。
+ 这时，<classname>signal_type</classname> 元函数（metafunction）就特别
有用，
+ 它开启了 <classname>signal</classname> 类的命名模板类型参数。例如，声
明一个信号，
+ 接收一个 <code>int</code> 参数，并使用
<classname>boost::signals2::dummy_mutex</classname>
+ 作为其 <code>Mutex</code> 类型，你可以这样写：
</para>
<programlisting>namespace bs2 = boost::signals2;
using bs2::keywords;
@@ -871,8 +1052,9 @@
</section>
<section>
- <title>Linking against the Signals2 library</title>
- <para>Unlike the original Boost.Signals library, Boost.Signals2 is
currently header-only.
+ <title>Linking against the Signals2 library 链接 Signals2 库</title>
+ <para>Unlike the original Boost.Signals library, Boost.Signals2 is
currently header-only.<sbr/>
+ 与原 Boost.Signals 库不同，Boost.Signals2 现在是纯头文件的。
</para>
</section>
Other related posts:
- » [boost-doc-zh] r370 committed - 翻译 ref, signals, signals2 库的xml/qbk文件 - boost-doc-zh