[boost-doc-zh commit] r278 - 完成 "从 Boost.Signals 向 Boost.Signals2 移植".

  • From: codesite-noreply@xxxxxxxxxx
  • To: boost-doc-zh-notify@xxxxxxxxxxxxx
  • Date: Mon, 06 Jul 2009 06:37:12 +0000

Author: jinq0123@xxxxxxx
Date: Sun Jul  5 23:02:41 2009
New Revision: 278

Modified:
   trunk/doc/html/signals2/porting.html

Log:
完成 "从 Boost.Signals 向 Boost.Signals2 移植".

Modified: trunk/doc/html/signals2/porting.html
==============================================================================
--- trunk/doc/html/signals2/porting.html        (original)
+++ trunk/doc/html/signals2/porting.html        Sun Jul  5 23:02:41 2009
@@ -1,11 +1,11 @@
 <html>
 <head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>Porting from Boost.Signals to Boost.Signals2</title>
 <link rel="stylesheet" href="../boostbook.css" type="text/css">
 <meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
-<link rel="up" href="../signals2.html" title="Chapter 17. Boost.Signals2">
+<link rel="up" href="../signals2.html" title="Chapter 17. Boost.Signals2">
 <link rel="prev" href="rationale.html" title="Design Rationale">
 <link rel="next" href="tests.html" title="Testsuite">
 </head>
@@ -25,10 +25,21 @@
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="signals2.porting"></a>Porting from Boost.Signals to Boost.Signals2</h2></div></div></div>
+
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="signals2.porting"></a>从 Boost.Signals 向 Boost.Signals2 移植 </h2></div></div></div>
+
<p>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.
   </p>
+
+<p>
+    与原 Boost.Signals 库相比,Boost.Signals2 API 所作的更改总结如下。
+ 我们还提供了一些说明,说明当现有 Boost.Signals 代码移植到 Boost.Signals2 时,
+    如何处理每一个变化。
+  </p>
+
 <div class="itemizedlist"><ul type="disc">
 <li>
<p>The namespace <code class="computeroutput">boost::signals</code> has been replaced by <code class="computeroutput">boost::signals2</code>
@@ -37,6 +48,18 @@
unlike the original Boost.Signals which has some classes in the <code class="computeroutput">boost</code> namespace in addition to its own <code class="computeroutput">boost::signals</code> namespace.
       </p>
+
+<p>名字空间 <code class="computeroutput">boost::signals</code>
+        已被 <code class="computeroutput">boost::signals2</code> 取代,
+        以避免与原 Boost.Signals 实现以及 Qt 的"signals"宏冲突。
+        所有 Boost.Signals2 的类都在
+        <code class="computeroutput">boost::signals2</code> 名字空间中,
+        不像原 Boost.Signals 除了其本身的
+        <code class="computeroutput">boost::signals</code>
+        名字空间,有某些类在
+        <code class="computeroutput">boost</code> 名字空间。
+      </p>
+
 <p>
         The Boost.Signals2 header files are contained in the
<code class="computeroutput">boost/signals2/</code> subdirectory instead of the <code class="computeroutput">boost/signals</code>
@@ -46,6 +69,23 @@
keeps a few headers in the parent <code class="computeroutput">boost/</code> directory in addition to its own <code class="computeroutput">boost/signals/</code> subdirectory.
       </p>
+
+<p>
+        Boost.Signals2 头文件位于
+        <code class="computeroutput">boost/signals2/</code>
+        子目录,而不是原 Boost.Signals 所使用的
+        <code class="computeroutput">boost/signals</code> 子目录。
+
+        此外,除了便捷头文件
+        <code class="computeroutput">boost/signals2.hpp</code>,
+        所有头文件都在 <code class="computeroutput">boost/signals2/</code>
+        子目录,不像原 Boost.Signals 除了其本身的
+        <code class="computeroutput">boost/signals/</code>
+        子目录,另外在父目录
+        <code class="computeroutput">boost/</code>
+        中也有几个头文件。
+      </p>
+
 <p>
For example, the <code class="computeroutput">signal</code> class is now in the <code class="computeroutput">boost::signals2</code> namespace instead of the
@@ -53,6 +93,16 @@
and it's header file is now at <code class="computeroutput">boost/signals2/signal.hpp</code> instead of
         <code class="computeroutput">boost/signal.hpp</code>.
       </p>
+
+<p>
+        例如,<code class="computeroutput">signal</code>
+ 类目前在 <code class="computeroutput">boost::signals2</code> 名字空 间,
+        而不是 <code class="computeroutput">boost</code> 名字空间,
+        它的头文件目前是
+        <code class="computeroutput">boost/signals2/signal.hpp</code>
+        而不是 <code class="computeroutput">boost/signal.hpp</code>。
+      </p>
+
 <p>
While porting, only trivial changes to <code class="computeroutput">#include</code> directives and namespace qualifications should be required to deal with these changes.
@@ -60,6 +110,17 @@
allow it to coexist in the same program with the original Boost.Signals library,
         and porting can be performed piecemeal.
       </p>
+
+<p>
+        移植时,为处理这些更改,应该只需对
+        <code class="computeroutput">#include</code>
+        指示和名字空间限定作些微不足道的更改。
+
+        此外,Boost.Signals2 新的名字空间和头文件位置
+        使它能够与原 Boost.Signals 库共存于同一程序,
+        这样移植就可以逐渐进行。
+      </p>
+
 </li>
 <li>
 <p>
@@ -70,6 +131,21 @@
However, the old (thread-unsafe) Boost.Signals scheme of automatic connection management is still supported via the <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">boost::signals2::trackable</a></code> class.
       </p>
+
+<p>
+        自动连接管理现在是通过利用
+ <code class="computeroutput">shared_ptr</code>/<code class="computeroutput">weak_ptr</code> + 和 <code class="computeroutput"><a class="link" href="../boost/signals2/slotN.html#id1187184-bb">slot::track</a></code>()
+        达到的,见
+ <a class="link" href="tutorial.html#signals2.tutorial.connection-management" title="Automatic Connection Management (Intermediate)">教程</a>
+        所述。
+
+        然而,通过
+ <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">boost::signals2::trackable</a></code>
+        类,旧的(线程不安全的)Boost.Signals
+        的自动连接管理方案仍被支持。
+      </p>
+
 <p>
If you do not intend to make your program multi-threaded, the easiest porting path is to simply replace your uses of <code class="computeroutput"><a class="link" href="../boost/signals/trackable.html" title="Class trackable">boost::signals::trackable</a></code> as a base class with
@@ -78,6 +154,22 @@
<code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">trackable</a></code> objects
         as used by the original Boost.Signals library.
       </p>
+
+<p>
+        如果您不打算让您的程序多线程化,
+        最方便的移植路径是,简单地把作为基类使用的
+ <code class="computeroutput"><a class="link" href="../boost/signals/trackable.html" title="Class trackable">boost::signals::trackable</a></code>
+        替换为
+ <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">boost::signals2::trackable</a></code>。
+
+        与原 Boost.Signals 库一样,
+        Boost.Signals2 使用同样的
+ <code class="computeroutput"><a class="link" href="../boost/visit_each.html" title="Function template visit_each">boost::visit_each</a></code>
+        机制来发现
+ <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">trackable</a></code>
+        对象。
+      </p>
+
 </li>
 <li>
<p>Support for postconstructors (and predestructors) on objects managed by <code class="computeroutput">shared_ptr</code>
@@ -89,6 +181,25 @@
The use of <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code> is described in the <a class="link" href="tutorial.html#signals2.tutorial.deconstruct" title="Postconstructors and Predestructors (Advanced)">tutorial</a>.
       </p>
+
+<p>
+ 对于由 <code class="computeroutput">shared_ptr</code> 所管理的对 象,
+        增加了对 postconstructor(和 predestructor)的支持,以及
+ <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code>
+        工厂函数。
+
+        这样做的动机在于
+        <code class="computeroutput">shared_ptr</code>
+        对新的连接跟踪方案的重要性,
+        并且不能在对象的造构函数中获得它的
+        <code class="computeroutput">shared_ptr</code>。
+
+ <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code>
+        的使用在
+ <a class="link" href="tutorial.html#signals2.tutorial.deconstruct" title="Postconstructors and Predestructors (Advanced)">教程</a>
+        中描述。
+      </p>
+
 <p>
The use of <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code> is in no way required,
         it is only provided in the hope
@@ -106,6 +217,34 @@
         making the class' constructors private and declaring
<code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct_access.html" title="Class deconstruct_access">deconstruct_access</a></code> a friend.
       </p>
+
+<p>
+ <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code>
+        的使用绝不是必需的,提供它只是希望它有用。
+
+        如果您移植的代码中,
+        一个类在其构造函数中创建连接到其自身的成员函数,
+        并且你还希望使用新的自动连接管理方案,
+        这时您就可以使用它。
+
+        然后,您可以将创建连接从构造函数移到
+        <code class="computeroutput">adl_postconstruct</code>
+        函数,其中有个引用,指向拥有该对象的
+        <code class="computeroutput">shared_ptr</code>,
+        它可以传递给
+ <code class="computeroutput"><a class="link" href="../boost/signals2/slotN.html#id1187184-bb">slot::track</a></code>。
+
+ <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code>
+        函数将被用于创建类的对象,并运行其相关的
+        <code class="computeroutput">adl_postconstruct</code>
+        函数。
+
+        您可以使类的构造函数私有,并声明
+ <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct_access.html" title="Class deconstruct_access">deconstruct_access</a></code>
+        为友元,来强制使用
+ <code class="computeroutput"><a class="link" href="../boost/signals2/deconstruct.html" title="Function deconstruct">deconstruct</a></code>。
+      </p>
+
 </li>
 <li>
 <p>
@@ -113,6 +252,14 @@
is useable as a function object, and has some additional features to support the
         new Boost.Signals2 automatic connection management scheme.
       </p>
+
+<p>
+ <code class="computeroutput"><a class="link" href="../boost/slot.html" title="Class template slot">slot</a></code>
+        类需要一个新的 <code class="computeroutput">Signature</code>
+        模板参数,该参数用作一个函数对象,
+        并具有一些附加功能以支持新的 Boost.Signals2 自动连接管理方案。
+      </p>
+
 <p>
The changes to the slot class should generally not cause any porting difficulties, especially if you are using the <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">boost::signals2::trackable</a></code>
@@ -121,12 +268,32 @@
         employ some of the new slot features, as described in the
<a class="link" href="tutorial.html#signals2.tutorial.connection-management" title="Automatic Connection Management (Intermediate)">tutorial</a>.
       </p>
+
+<p>
+        对插槽类的更改一般应不会造成任何移植困难,
+        尤其是如果您使用的是上述的兼容类
+ <code class="computeroutput"><a class="link" href="../boost/signals2/trackable.html" title="Class trackable">boost::signals2::trackable</a></code>。
+
+        如果您是要将您的代码转换为使用新的自动连接管理方案,
+        您将需要用到一些新的插槽功能,请见
+ <a class="link" href="tutorial.html#signals2.tutorial.connection-management" title="Automatic Connection Management (Intermediate)">教程</a>
+        所述。
+      </p>
+
 </li>
 <li>
 <p>
The <code class="computeroutput"><a class="link" href="../boost/signals2/optional_last_value.html" title="Class template optional_last_value">optional_last_value</a></code> class has replaced <code class="computeroutput"><a class="link" href="../boost/last_value.html" title="Class template last_value">last_value</a></code>
         as the default combiner for signals.
       </p>
+
+<p>
+ <code class="computeroutput"><a class="link" href="../boost/signals2/optional_last_value.html" title="Class template optional_last_value">optional_last_value</a></code>
+        类已取代
+ <code class="computeroutput"><a class="link" href="../boost/last_value.html" title="Class template last_value">last_value</a></code>,
+        成为了信号的默认合并器。
+      </p>
+
 <p>
The <code class="computeroutput"><a class="link" href="../boost/last_value.html" title="Class template last_value">last_value</a></code> combiner is still provided, although its
         behavior is slightly changed in that it
@@ -134,6 +301,16 @@
always requiring at least one slot to be connected (except for its void specialization
         which never required any slots to be connected).
       </p>
+
+<p>
+ <code class="computeroutput"><a class="link" href="../boost/last_value.html" title="Class template last_value">last_value</a></code>
+        合并器仍然存在,
+        但其行为略有改变,
+        当信号调用时无插槽连接会抛异常,
+        而不是总是要求至少有一个插槽连接
+        (除了 void 特化,它从不要求任何插槽连接)。
+      </p>
+
 <p>
If you are porting signals which have a <code class="computeroutput">void</code> return type in their signature and they use the default combiner, there are no changes required. If you are
@@ -144,10 +321,36 @@
way to deal with this is to use <code class="computeroutput">boost::optional::operator*()</code> to access the value wrapped inside the returned <code class="computeroutput">boost::optional</code>.
       </p>
+
+<p>
+ 如果您移植的信号返回类型是 <code class="computeroutput">void</code>,
+        并且使用默认的合并器,那就不需要任何更改。
+
+        如果您使用的是返回类型非空的默认合并器,
+        并且关心信号调用的返回值,
+        您就必须考虑到
+ <code class="computeroutput"><a class="link" href="../boost/signals2/optional_last_value.html" title="Class template optional_last_value">optional_last_value</a></code>
+        返回的是 <code class="computeroutput">boost::optional</code>,
+        而不是一个简单的值。
+
+        处理该问题最简单的一种方法,就是使用
+        <code class="computeroutput">boost::optional::operator*()</code>
+        来访问返回的 <code class="computeroutput">boost::optional</code>
+        中所封装的值。
+      </p>
+
 <p>
Alternatively, you could do a port by specifying the <code class="computeroutput">Combiner</code> template parameter for your <code class="computeroutput">signals2::signal</code> to be <code class="computeroutput"><a class="link" href="../boost/last_value.html" title="Class template last_value">last_value</a></code>.
       </p>
+
+<p>
+        或者,您也可以这样移植:指定
+        <code class="computeroutput">signals2::signal</code>
+        的 <code class="computeroutput">Combiner</code> 模板参数为
+ <code class="computeroutput"><a class="link" href="../boost/last_value.html" title="Class template last_value">last_value</a></code>。
+      </p>
+
 </li>
 <li>
 <p>
@@ -160,6 +363,24 @@
new <code class="computeroutput">ExtendedSlotFunction</code> template parameter for specifying the underlying slot function
         type for the new extended slots.
       </p>
+
+<p>
+ <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">signal</a></code>
+        类添加了一个
+ <code class="computeroutput"><a class="link" href="../boost/signals2/signalN.html#boost.signals2.signalN.extended_slot_type">signal::extended_slot_type</a></code>
+        类型定义,和新的
+ <code class="computeroutput"><a class="link" href="../boost/signals2/signalN.html#id1208227-bb">signal::connect_extended</a></code>()
+        方法。
+
+        这使得连接的插槽可以接受一个额外的
+ <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">connection</a></code>
+        参数,使插槽被调用时可以线程安全地访问其信号/插槽连接。
+
+        还有一个新的
+        <code class="computeroutput">ExtendedSlotFunction</code>
+        模板参数,来为新的扩展插槽指定底层的插槽函数类型。
+      </p>
+
 <p>
These additions should have no effect on porting unless you are also converting your program from a single threaded program into a multi-threaded one. In that case,
@@ -171,12 +392,36 @@
         More information on how and why to use extended slots is available
in the <a class="link" href="tutorial.html#signals2.tutorial.extended-slot-type" title="Giving a Slot Access to its Connection (Advanced)">tutorial</a>.
       </p>
+
+<p>
+        这些添加应该不会影响移植,
+        除非您同时在把程序从单线程转换为多线程的。
+
+        在这种情况下,如果您有插槽需要访问其
+ <code class="computeroutput"><a class="link" href="../boost/signals2/connection.html" title="Class connection">connection</a></code>
+        (例如,阻止或断开其连接,即插槽与调用插槽的信号之间的连接),
+        您可能希望用
+ <code class="computeroutput"><a class="link" href="../boost/signals2/signalN.html#id1208227-bb">signal::connect_extended</a></code>()
+        来连接插槽。
+
+        这也要求插槽增加一个额外的连接参数。
+ <a class="link" href="tutorial.html#signals2.tutorial.extended-slot-type" title="Giving a Slot Access to its Connection (Advanced)">教程</a>
+        中有如何以及为什么使用扩展插槽的详细信息。
+      </p>
+
 </li>
 <li>
 <p>
The <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">signal</a></code> class has a new <code class="computeroutput">Mutex</code> template parameter for specifying
         the mutex type used internally by the signal and its connections.
       </p>
+
+<p>
+ <code class="computeroutput"><a class="link" href="../boost/signal.html" title="Class template signal">signal</a></code>
+        类有个新的 <code class="computeroutput">Mutex</code>
+        模板参数,用来指定信号及其连接内部使用的互斥体类型。
+      </p>
+
 <p>
The <code class="computeroutput">Mutex</code> template parameter can be left to its default value of <code class="computeroutput"><a class="link" href="../boost/signals2/mutex.html" title="Class mutex">boost::signals2::mutex</a></code> and should have little effect on porting.
@@ -186,12 +431,37 @@
See the <a class="link" href="tutorial.html#signals2.tutorial.signal-mutex-template-parameter" title="Changing the Mutex Type of a Signal (Advanced).">tutorial</a> for more information on the <code class="computeroutput">Mutex</code> parameter.
       </p>
+
+<p>
+        <code class="computeroutput">Mutex</code>
+        模板参数可保持缺省值
+ <code class="computeroutput"><a class="link" href="../boost/signals2/mutex.html" title="Class mutex">boost::signals2::mutex</a></code>,
+        应该不会影响移植。
+
+        但是,如果你有一个单线程程序,
+        担心因不必要的互斥锁而招致性能开销,
+        你不妨为你的信号使用不同的互斥体,如
+ <code class="computeroutput"><a class="link" href="../boost/signals2/dummy_mutex.html" title="Class dummy_mutex">dummy_mutex</a></code>。
+
+        关于 <code class="computeroutput">Mutex</code> 参数的更多信息请见
+ <a class="link" href="tutorial.html#signals2.tutorial.signal-mutex-template-parameter" title="Changing the Mutex Type of a Signal (Advanced).">教程</a>。
+      </p>
+
 </li>
 <li>
<p>The <code class="computeroutput">signal::combiner()</code> method, which formerly returned a reference to the signal's combiner has been replaced by <code class="computeroutput"><a class="link" href="../boost/signalN.html#id1242709-bb">signal::combiner</a></code> (which now returns the combiner by value) and <code class="computeroutput"><a class="link" href="../boost/signals2/signalN.html#id2375152-bb">signal::set_combiner</a></code>.
       </p>
+
+<p><code class="computeroutput">signal::combiner()</code>方法,
+        原来返回一个指向信号合并器的引用,已被
+ <code class="computeroutput"><a class="link" href="../boost/signalN.html#id1242709-bb">signal::combiner</a></code>
+        (现在按值返回合并器)和
+ <code class="computeroutput"><a class="link" href="../boost/signals2/signalN.html#id2375152-bb">signal::set_combiner</a></code>
+        取代。
+      </p>
+
 <p>
During porting it should be straightforward to replace uses of the old reference-returning
         <code class="computeroutput">signal::combiner()</code>
@@ -201,15 +471,46 @@
         to determine if your program logic has been broken by the changed
         return type.
       </p>
+
+<p>
+        移植过程中,
+ 将旧的返回引用的 <code class="computeroutput">signal::combiner()</code>
+        函数替换为新的"按值"方式的
+ <code class="computeroutput"><a class="link" href="../boost/signalN.html#id1242709-bb">signal::combiner</a></code>
+        和
+ <code class="computeroutput"><a class="link" href="../boost/signals2/signalN.html#id2375152-bb">signal::set_combiner</a></code>
+        函数,应该是简单的。
+
+        但是,您需要检查代码中每个
+        <code class="computeroutput">combiner</code>
+        方法调用,以确定您的程序逻辑没有因更改返回类型而破坏。
+      </p>
+
 </li>
 <li>
<p>Connections no longer have <code class="computeroutput">block()</code> and <code class="computeroutput">unblock()</code> methods. Blocking of connections is now accomplished by creating <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code> objects,
         which provide RAII-style blocking.
       </p>
+
+<p>连接不再有
+        <code class="computeroutput">block()</code>
+        和 <code class="computeroutput">unblock()</code>
+        方法。
+
+        连接的阻塞现在通过创建
+ <code class="computeroutput"><a class="link" href="../boost/signals2/shared_connection_block.html" title="Class shared_connection_block">shared_connection_block</a></code>
+        对象完成,它提供了 RAII 方式的阻塞。
+      </p>
+
 <p>
         If you have existing Boost.Signals code that blocks, for example:
       </p>
+
+<p>
+        如果您现有的 Boost.Signals 代码有阻塞,例如:
+      </p>
+
 <pre class="programlisting">
 namespace bs = boost::signals;

@@ -223,6 +524,11 @@
 <p>
             then the version ported to Boost.Signals2 would look like:
           </p>
+
+<p>
+            那么移植到 Boost.Signals2 的版本将如下所示:
+          </p>
+
 <pre class="programlisting">
 namespace bs2 = boost::signals2;

@@ -239,7 +545,12 @@
 </div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision"; width="100%"><tr> <td align="left"><p><small>Last revised: June 12, 2007 at 14:01:23 -0400</small></p></td> -<td align="right"><div class="copyright-footer">Copyright 2001-2004 Douglas Gregor<br>Copyright 2007-2009 Frank Mori Hess<p>Distributed under the Boost +<td align="right"><div class="copyright-footer">Copyright (c) 2001-2004 Douglas Gregor<br>Copyright (c) 2007-2009 Frank Mori Hess
+
+    <p>翻译:<a href="http://blog.csdn.net/jq0123";>金庆</a></p>
+    <p>译文更新:2009.7.6</p>
+
+    <p>Distributed under the Boost
     Software License, Version 1.0. (See accompanying file
<code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt"; target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
 </div></td>

Other related posts:

  • » [boost-doc-zh commit] r278 - 完成 "从 Boost.Signals 向 Boost.Signals2 移植". - codesite-noreply