179 |
--------------------------------------------------------------------------------
/zh/p10.md:
--------------------------------------------------------------------------------
1 | ### 版本5.0
2 |
3 | 现在我们将要向诗歌下载客户端添加一些新的处理逻辑，包括在第九部分提到要添加的功能。不过，首先我要说明一点：我并不知道如何实现Byronification引擎。那超出了我的编程能力范围。取而代之的，我想实现一个简单的功能，即Cummingsifier。其只是将诗歌内容转换成小写字母：
4 | ```python
5 | def cummingsify(poem)
6 | return poem.lower()
7 | ```
8 | 这个方法如此之简单以至于它永远不会出错。版本5.0的实现代码在[twisted-client-5/get-poetry.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-5/get-poetry.py#L1)文件中。我们使用了修改后的 cummingsify，其会随机地选择以下行为：
9 |
10 | 1. 返回诗歌的小写版本
11 | 2. 抛出一个GibberishError异常
12 | 3. 抛出一个ValueError
13 |
14 | 这样，我们便模拟出来一个会因为各种意料不到的问题而执行失败的复杂算法。其它部分的仅有的改变在方法poetry_main中：
15 | ```python
16 | def poetry_main():
17 | addresses = parse_args()
18 | from twisted.internet import reactor
19 | poems = []
20 | errors = []
21 | def try_to_cummingsify(poem):
22 | try:
23 | return cummingsify(poem)
24 | except GibberishError:
25 | raise
26 | except:
27 | print 'Cummingsify failed!'
28 | return poem
29 | def got_poem(poem):
30 | print poem
31 | poems.append(poem)
32 | def poem_failed(err):
33 | print >>sys.stderr, 'The poem download failed.'
34 | errors.append(err)
35 | def poem_done(_):
36 | if len(poems) + len(errors) == len(addresses):
37 | reactor.stop()
38 | for address in addresses:
39 | host, port = address
40 | d = get_poetry(host, port)
41 | d.addCallback(try_to_cummingsify)
42 | d.addCallbacks(got_poem, poem_failed)
43 | d.addBoth(poem_done)
44 | reactor.run()
45 | ```
46 | 因此，当从服务器上下载一首诗歌时，可能会出现如下情况：
47 |
48 | 1. 打印诗歌的小写版本
49 | 2. 打印"Cummingsify failed"并附上原始形式的诗歌
50 | 3. 打印"The poem download failed"。
51 |
52 | 为了实现下面内容的效果，你可以打开多个服务器或打开一个服务器多次，直到你观察到所有不同的结果，当然也尝试一下去连接一个没有服务器值守的端口。
53 |
54 | 图19是我们给deferred添加回调后形成的callback/errback链：
55 |
56 |
57 | 图19 deferred中的回调链
58 |
59 | 注意到，"pass-throug"errback通过addCallback添加到链中。它会将任何其接收到的Failure传递给下一个errback（即poem_failed函数）。因此poem_failed函数可以处理来自get_poetry与try_to_commingsify两者的failure。下面让我们来分析下deferred可能会出现的激活情况，图20说明了我们能够下载到诗歌并且try_to_commingsify成功执行的路线图：
60 |
61 |
62 | 图20 成功下载到诗歌并且成功变换其格式
63 |
64 | 在这种情况中，没有回调执行失败，因此控制权一直在callback中流动。注意到poem_done收到的结果是None，这是因为它并没有返回任何值。如果我们想让后续的回调都能触及到诗歌内容，只要显式地让got_poem返回诗歌即可。
65 |
66 | 图21说明了我们在成功下载到诗歌后，但在try_to_cummingsify中抛出了GibberishError：
67 |
68 |
69 | 图21 成功下载到诗歌但出现了GibberishError
70 |
71 | 由于try_to_cummingsify回调抛出了GibberishError，所以控制权转移到了errback链，即poem_fail回调被调用并传入的捕获的异常作为其参数。
72 |
73 | 由于poem_failed并没有抛出获异常或返回一个Failure，因此在它执行完后，控制权又回到了callback链中。如果我们想让poem_fail完全处理好传进来的错误，那么返回一个None是再好不过的做法了。相反，如果我们只想让poem_failed采取一部分行动，但继续传递这个错误，那么我们需要改写poem_failed，即将参数err作为返回值返回。如此一来，控制权交给了下一个errback回调。
74 |
75 | 注意到，迄今为止，got_poem与poem_failed都不可能出现执行失败的情况，因此errback链上的poem_done是不可能被激活的。但在任何情况下这样做都是安全的，这体现了"防御式"编程的思想。比如在got_poem或poem_failed出现了bugs，那么这样做就不会让这些bugs的影响进入Twisted的核心代码区。鉴于上面的描述，可以看出addBoth类似于try/except中的finally语句。
76 |
77 | 下面我们再来看看第三种可能情况，即成功下载到诗歌但try_to_cummingsify抛出了VauleError，如图22：
78 |
79 |
80 | 图22 成功下载到诗歌当cummingsify执行失败
81 |
82 | 除了got_poem得到是原始式样的诗歌而不是小写版的外，与图20描述的情况完全相同。当然，控制权还是在try_to_cummingsif中进行了转移，即使用了try/except捕获了ValueError并返回了原始式样的诗歌。而这一切deferred并不知晓。
83 |
84 | 最后，我们来看看当试图连接一个无服务器值守的端口会出现什么情况，如图23所示：
85 |
86 |
87 | 图23 连接服务器失败
88 |
89 | 由于poem_failed返回了一个None，因此控权又回到了callback链中。
90 |
91 | ### 版本5.1
92 |
93 | 在版本5.0中我们使用普通的try/except来捕获try_to_cummingsify中的异常，而没有让deferred来捕获这个异常。这其实并没有什么错误，但下面我们将采取一种新的方式来处理异常。
94 |
95 | 设想一下，我们让deferred来捕获 GibberishError 与ValueError 异常，并将其传递到errback链中进行处理。如果要保留原有的行为，那么需要下面的errback来判断错误类型是否为Valuerror，如果是，那么返回原始式样的诗歌，这样一来，控制权再次回到callback链中并将原始式样的诗歌打印出来。
96 |
97 | 但有一个问题：errback并不会得到原始诗歌内容 。它只会得到由cummingsify抛出的vauleError异常。为了让errback处理这个错误，我们需要重新设计它来接收到原始式样的诗歌。
98 |
99 | 一种方法是改变cummingsify以让异常信息中包含原始式样的诗歌。这也正是我们在5.1版本中做的，其代码实现在[twisted-client-5/get-poetry-1.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-5/get-poetry-1.py)中。我们改写ValueError异常为CannotCummingsify异常，其能将诗歌作为其第一个参数来传递。
100 |
101 | 如果cummingsify是外部模块中一个真实存在的函数，那么其最好是通过另一个函数来捕获非GibberishError并抛出一个CannotCummingsify异常。这样，我们的poetry_main就成为：
102 | ```python
103 | def poetry_main():
104 | addresses = parse_args()
105 | from twisted.internet import reactor
106 | poems = []
107 | errors = []
108 | def cummingsify_failed(err):
109 | if err.check(CannotCummingsify):
110 | print 'Cummingsify failed!'
111 | return err.value.args[0]
112 | return err
113 | def got_poem(poem):
114 | print poem
115 | poems.append(poem)
116 | def poem_failed(err):
117 | print >>sys.stderr, 'The poem download failed.'
118 | errors.append(err)
119 | def poem_done(_):
120 | if len(poems) + len(errors) == len(addresses):
121 | reactor.stop()
122 | for address in addresses:
123 | host, port = address
124 | d = get_poetry(host, port)
125 | d.addCallback(cummingsify)
126 | d.addErrback(cummingsify_failed)
127 | d.addCallbacks(got_poem, poem_failed)
128 | d.addBoth(poem_done)
129 | ```
130 | 而新的deferred结构如图24所示：
131 |
132 |
133 | 图24 版本5.1的deferrd调用链结构
134 |
135 | 来看看cummingsify_failed的errback回调：
136 | ```python
137 | def cummingsify_failed(err):
138 | if err.check(CannotCummingsify):
139 | print 'Cummingsify failed!'
140 | return err.value.args[0]
141 | return err
142 | ```
143 | 我们使用了Failure中的check方法来确认嵌入在Failure中的异常是否是CannotCummingsify的实例。如果是，我们返回异常的第一个参数（即原始式样诗歌）。因此，这样一来返回值就不是一个Failure了，控制权也就又回到callback链中了。否则（即异常不是CannotCummingsify的实例），我们返回一个Failure，即将错误传递到下一个errback中。
144 |
145 | 图25说明了当我们捕获一个CannotCummingsify时的调用过程：
146 |
147 |
148 | 图25 捕获一个CannotCummingsify异常
149 |
150 | 因此，当我们使用deferrd时，可以选择使用try/except来捕获异常，也可以让deferred来将异常传递到errback回调链中进行处理。
151 |
152 | ### 总结
153 |
154 | 在这个部分，我们增强了客户端的Deferred的功能，实现了异常与结果在callback/errback链中"路由"。（你可以将各个回调看作成路由器，然后根据传入参数的情况来决定其返回值进入下一个stage的哪条链，或者说控制权进入下一个stage的哪个类型的回调）。虽然示例程序是虚构出来的，但它揭示了控制权在deferred的回调链中交错传递具体方向依赖于返回值的类型。
155 |
156 | 那我们是不是已经对deferred无所不知了？不，我们还会在下面的部分继续讲解deferred的更多的功能。但在第十一部分，我们先不讲这部分内容，而是实现我们的Twisted版本的诗歌下载服务器。
157 |
158 | ### 参考
159 |
160 | 本部分原作参见: dave @
161 |
162 | 本部分翻译内容参见杨晓伟的博客
163 |
--------------------------------------------------------------------------------
/zh/p11.md:
--------------------------------------------------------------------------------
1 | ### 诗歌下载服务器
2 |
3 | 到目前为止，我们已经学习了大量关于诗歌下载客户端的Twisted的知识，接下来，我们使用Twisted重新实现我们的服务器端。得益于Twisted的抽象机制，接下来你会发现我们前面已经几乎学习到了所需的全部知识。其实现源码在[twisted-server-1/fastpoetry.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-1/fastpoetry.py#L1)中。之所以称其为fastpoetry是因为其传输诗歌并没有任何延迟。注意到，其代码量比客户端代码少多了。
4 |
5 | 让我们一部分一部分地来看服务端的实现，首先是poetryProtocol：
6 | ```python
7 | class PoetryProtocol(Protocol):
8 | def connectionMade(self):
9 | self.transport.write(self.factory.poem)
10 | self.transport.loseConnection()
11 | ```
12 | 如同客户端的实现，服务器端使用Protocol来管理连接（在这里，连接是由客户端发起的）。这里的Protocol实现了我们的诗歌下载逻辑的服务器端。由于我们协议逻辑处理的是单向的，服务器端的Protocol只负责发送数据。如果你访问服务器端，协议请求服务器在连接建立后立即发送诗歌，因此我实现了connectionMade方法，其会在Protocol创建一个连接后被激活执行。
13 |
14 | 这个方法告诉Transport做两件事：将整首诗歌发送出去然后关闭连接。当然，这两个动作都是同步操作。因此调用write函数也可以说成“一定要将整首诗歌发送到客户端”，调用loseConnection意味着“一旦将要求下载的诗歌发送完毕就关掉这个连接”。
15 |
16 | 也许你看到了，Protocol是从Factory中获得诗歌内容的：
17 | ```python
18 | class PoetryFactory(ServerFactory):
19 | protocol = PoetryProtocol
20 | def __init__(self, poem):
21 | self.poem = poem
22 | ```
23 | 这么简单！除了创建PoetryProtocol, 工厂仅有的工作是存储要发送的诗歌。
24 |
25 | 注意到我们继承了ServerFactory而不是ClientFactory。这是因为服务器是要被动地监听连接状态而不是像客户端一样去主动的创建。我们何以如此肯定呢？因为我们使用了listenTCP方法，其描述文档声明factory参数必须是ServerFactory类型的。
26 |
27 | 我们在main函数中调用了listenTCP函数：
28 | ```python
29 | def main():
30 | options, poetry_file = parse_args()
31 | poem = open(poetry_file).read()
32 | factory = PoetryFactory(poem)
33 | from twisted.internet import reactor
34 | port = reactor.listenTCP(options.port or 0, factory,nterface=options.iface)
35 | print 'Serving %s on %s.' % (poetry_file, port.getHost())
36 | reactor.run()
37 | ```
38 | 其做了三件事：
39 |
40 | 1. 读取我们将要发送的诗歌
41 | 2. 创建PoetryFactory并传入这首诗歌
42 | 3. 使用listenTCP来让Twisted监听指定的端口，并使用我们提供的factory来为每个连接创建一个protocol
43 |
44 | 剩下的工作就是reactor来运转事件循环了。你可以使用前面任何一个客户端来测试这个服务器。
45 |
46 | ### 讨论
47 |
48 | 回忆下第五部分中的图8与图9.这两张图说明了Twisted建立一个连接后如何创建一个协议并初始化它的。其实对于Twisted在其监听的端口处监听到一个连接之后的整个处理机制也是如此。这也是为什么connectTCP与listenTCP都需要一个factory参数的原因。
49 |
50 | 我们在图9中没有展示的是，connectionMade也会在Protocol初始化的时候被调用。无论在哪儿都一样（Dave是想说，connectionMade都会在Protocol初始化时被调用），只是我们在客户端处没有使用这个方法。并且我们在客户端的portocal中实现的方法也没有在服务器中用到。因此，如果我们有这个需要，可以创建一个共享的PoetryProtocol供客户端与服务器端同时使用。这种方式在Twisted经常见到。例如，[NetstringReceiver protocol](http://twistedmatrix.com/trac/browser/tags/releases/twisted-8.2.0/twisted/protocols/basic.py#L31)即能从连接中读也能向连接中写[netstrings](http://en.wikipedia.org/wiki/Netstrings)。
51 |
52 | 我们略去了从低层实现服务器端的工作，但我们可以来思考一下这里做了些什么。首先，调用listenTCP来告诉Twisted创建一个 [listening socket](http://en.wikipedia.org/wiki/Berkeley_sockets#listen.28.29) 并将其添加到事件循环中。在 listening socket 有事件发生并不意味有数据要读，而是说明有客户端在等待连接自己。
53 |
54 | Twisted会自动接受连接请求，并创建一个新的客户端连接来连接客户端与服务器（中间桥梁）。这个新的连接也要加入事件循环中，并且Twisted会为其创建了一个Transport和一个专门为这个连接服务的PoetryProtocol。因此，Protocol实例总是连接到client socket，而不是listening socket。
55 |
56 | 我们可以在图26中形象地看到这一结果：
57 |
58 |
59 | 图26 服务器端的网络连接
60 |
61 | 在图中，有三个客户端连接到服务器。每个Transport代表一个client socket，加上listening socket总共是四个被select循环监听的文件描述符（file descriptor).当一个客户端断开与其相关的transport的连接时，对应的PoetryProtocol也会被解引用并当作垃圾被回收。而PoetryFactory只要我们还在监听新的连接就会一直不停地工作（即PoetryFactory不会随着一个连接的断开导致的PoetryProtocol的销毁而销毁）。
62 |
63 | 如果我们提供的诗歌很短的话，那么这些client socket与其相关的各种对象的生命期也就很短。但也有可能会是一台相当繁忙的服务器以至于同时有千百个客户端同时请求较长的诗歌。那没关系，因为Twisted并没有连接建立的限制。当然，当下载量持续的增加，在某个结点处，你会发现已经到达了OS的上限。对于那些高下载量的服务器，仔细的检测与测试是每天都必须要做的工作。
64 |
65 | 并且Twisted在监听端口的数量上亦无限制。实际上，一个单一的Twisted线程可以监听数个端口并为其提供不同的服务（通过使用不同的factory作为listenTCP的参数即可）。如果经过精心的设计，甚至可以推迟到部署阶段来决定"是使用一个Twisted进程来提供多个服务还是使用多个Twisted进程来实现?"。
66 |
67 | 我们这个版本的服务器有些功能是没有的。首先，它无法产生任何日志来帮助我们调试和分析网络出现的问题。其次，服务器也不是做为一个守护进程来运行的，按下`ctrl+c`或者退出登陆都会使其中止执行。后面章节我们会解决这两个问题，但是第十二部分我们先来完成另一个改进版的服务器。
68 |
69 | ### 参考
70 |
71 | 本部分原作参见: dave @
72 |
73 | 本部分翻译内容参见杨晓伟的博客
74 |
--------------------------------------------------------------------------------
/zh/p12.md:
--------------------------------------------------------------------------------
1 | ### 新的服务器实现
2 |
3 | 这里我们要新写一个Twisted版的服务器。然后，再来讨论一些Deferred的新功能。
4 |
5 | 在第九、十部分，我们提出了诗歌转换引擎这个概念。由于实现太过简单，因此我们用随机选择来模拟了可能会出现的转换失败的情景。但如果转换引擎位于服务器端，那么当服务器宕机就会出现真实的转换失败的情景了。
6 |
7 | 因此，在本节我们要实现一个诗歌样式转换服务器，然后在下一节，我们会重写诗歌下载客户端使用这一服务来学习Deferred的新功能。
8 |
9 | ### 设计协议
10 |
11 | 到目前为止，服务器端与客户端之间的交互都是单向的。但样式转换服务需要两者进行双向交互-客户端将原始式样的诗歌发送给服务器，然后服务器转换格式并将其返回给对应的客户端。因此，我们需要使用或自己实现一个协议来实现这种交互。
12 |
13 | 我们设计服务器端可以提供若干种转换服务，让客户端来进行选择。因此客户端需要向服务器端发送两部分信息：转换方式与诗歌原始内容。服务器只是将转换格式之后的诗歌发送给客户端。这里使用到了简单的[远程调用](http://en.wikipedia.org/wiki/Remote_procedure_call)。
14 |
15 | Twisted支持若干种能解决这个问题的协议：XML-RPC, Perspective Broker, AMP。
16 |
17 | 但介绍使用其中任何一种都需要大量的时间，因此我们使用自己实现的协议。我们约定客户端发送内容格式如下：
18 |
19 | > **转换方式.诗歌内容**
20 |
21 | 我们将其以[netstring](http://en.wikipedia.org/wiki/Netstrings)格式编码，当然服务器回发的信息也是以netstring格式编码。由于netstring使用了length-encoding，因此客户端能够识别出服务器没有将完整诗歌回发的情况。如果你尝试一下会发现，之前的协议无法检测到中途中断传输的情况。
22 |
23 | ### 代码
24 |
25 | 新的服务器实现代码在[twisted-server-1/transformedpoetry.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-1/transformedpoetry.py#L1)中。首先，我们定义了一个TransformService类：
26 | ```python
27 | class TransformService(object):
28 | def cummingsify(self, poem):
29 | return poem.lower()
30 | ```
31 | 这里我们仅仅实现了一种转换方法(与转换方式同名)，我们可以通过添加方法支持更多转换方式。有一个重要的地方需要注意：格式转换服务与具体协议的实现是完全分离的。将协议逻辑与服务逻辑分开是Twisted编程中常见的模式。这样做可以通过多种协议实现同一种服务，以增加代码的重用性。
32 |
33 | 下面看看factory的实现代码：
34 | ```python
35 | class TransformFactory(ServerFactory):
36 | protocol = TransformProtocol
37 | def __init__(self, service):
38 | self.service = service
39 | def transform(self, xform_name, poem):
40 | thunk = getattr(self, 'xform_%s' % (xform_name,), None)
41 | if thunk is None: # no such transform
42 | return None
43 | try:
44 | return thunk(poem)
45 | except:
46 | return None # transform failed
47 | def xform_cummingsify(self, poem):
48 | return self.service.cummingsify(poem)
49 | ```
50 | factory提供了一个transform的函数，protocol就是用它来处理客户端连接发送的诗歌格式转换请求的。
51 |
52 | 如果发现不存在客户端请求的转换方式或转换失败，那么返回None。和TransformService一样，factory与具体的协议逻辑实现也是相互独立的。
53 |
54 | 有一个地方需要引起注意：我们通过xfomr_前缀式方法来获取服务方法。这种方法在Twisted中很常见，尽管前缀经常发生变化，并且他们经常是依赖独立于factory的一个对象（如此处的 TransformService）。考虑到客户端可以发送任意的transform方法名，这是一种防止客户端蓄意使用恶性代码来让服务器端执行的方法。这种方法也提供了实现由服务提供具体协议代理的机制。
55 |
56 | 下面是协议实现代码：
57 | ```python
58 | class TransformProtocol(NetstringReceiver):
59 | def stringReceived(self, request):
60 | if '.' not in request: # bad request
61 | self.transport.loseConnection()
62 | return
63 | xform_name, poem = request.split('.', 1)
64 | self.xformRequestReceived(xform_name, poem)
65 | def xformRequestReceived(self, xform_name, poem):
66 | new_poem = self.factory.transform(xform_name, poem)
67 | if new_poem is not None:
68 | self.sendString(new_poem)
69 | self.transport.loseConnection()
70 | ```
71 | 在这个协议的实现中，我们通过继承NetstringReceiver来利用了Twisted对netstrings的实现。基类很好的处理了编码与解码功能，我们需要做的就是实现stringReceived方法。换句话说，stringReceived接收的参数是客户端编码之后的诗歌，而无需我们再去添加额外的编码信息。而且基类同样管理着缓冲区，即当一首诗歌完整接收完再进行解码。
72 |
73 | 如果一切进展正常的话，我们会使用NetstringReceiver的 sendString方法来将格式转换成功后的诗歌发送给客户端。
74 |
75 | 注意我们是如何通过定义xformRequestReceived方法将收到的信息一步步推向更高的抽象层而实现了Twisted的模式。
76 |
77 | ### 一个简单的客户端
78 |
79 | 我们会在下一个部分来实现相应的客户端，这里使用一个简单的脚本来实现客户端，代码位于[twisted-server-1/transform-test](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-1/transform-test)中。如果你运行服务器端于11000端口：
80 | ```
81 | python twisted-server-1/transformedpoetry.py --port 11000
82 | ```
83 | 相应的运行脚本为：
84 | ```
85 | ./twisted-server-1/transform-test 11000
86 | ```
87 | 那么你会看到如下输出（经过netstring编码）：
88 | ```
89 | 15:here is my poem,
90 | ```
91 |
92 | ### 讨论
93 |
94 | 在这个部分介绍了如下几个方面内容：
95 |
96 | 1. 双向通信
97 | 2. 基于Twisted已有的协议实现新协议
98 | 3. 将协议实现与服务功能实现独立分开
99 |
100 | 双向通信的基本机制是很简单的。我们使用前面服务器端与客户端使用的相同的技术来写与读数据，唯一不同的是我们这次两者都使用了（读与写）。当然，一个复杂的协议需要复杂的代码来处理接收到的数据流与格式化输出的信息。这也是为什么使用已经存在的协议的原因。
101 |
102 | 如果你开始觉得写简单的协议已经很上手了，那么最好就开始看看Twisted对不同协议的实现。尽管写一些简单的协议有助理解Twisted的编程风格，但在一个真实的程序中，最好是复用那些已经实现并证明性能良好的协议。
103 |
104 | 最后一点是将协议解析逻辑与服务实现逻辑分开，这是Twisted编程中非常重要的一个模式。我们这个服务器程序只是一个演示，你可以想象一下真实的网络服务是相当复杂的。通过将服务与协议逻辑分开，你可以通过复用已有的服务代码来运行于其它的协议实现上。
105 |
106 | 图27展示了一个格式转换服务器通过两种协议提供格式转换服务（当然，我们的服务器只提供了一种协议）：
107 |
108 |
109 | 图27 提供两种协议支持的格式转换服务器
110 |
111 | 虽然在图27中使用了两种协议，但他们也许只是几个协议属性不同而已，factory共享同一个服务，这样就实现了代码的复用。
112 |
113 | ### 参考
114 |
115 | 本部分原作参见: dave @
116 |
117 | 本部分翻译内容参见杨晓伟的博客
118 |
--------------------------------------------------------------------------------
/zh/p13.md:
--------------------------------------------------------------------------------
1 | ### 介绍
2 |
3 | 回忆下第10部分中的客户端5.1版。客户端使用一个Deferred来管理所有的回调链，其中包括一个格式转换引擎的调用。在那个版本中，这个引擎的实现是同步的。
4 |
5 | 现在我们想实现一个新的客户端，使用我们在第十二部分实现的服务器提供的格式转换服务。但这里有一个问题需要说清楚：由于格式转换服务是通过网络获取的，因此我们需要使用异步I/O。这也就意味着我们获取格式转换服务的API必须是异步实现的。换句话说，try_to_cummingsify回调将会在新客户端中返回一个 deferred。
6 |
7 | 如果在一个deferred的回调链中的一个函数又返回了一个 deferred会发生什么现象呢？我们规定前一个deferred为外层deferred，而后者则为内层deferred。假设回调N在外层deferred中返回一个内层的deferred。意味着这个回调宣称“我是一个异步函数，结果不会立即出现！”。由于外层的deferred需要调用回调链中下一个callback或errback并将回调N的结果传下去，因此，其必须等待直到内层deferred被激活。当然了，外层的deferred不可能处于阻塞状态，因为控制权此时已经转交给了reactor并且阻塞了。
8 |
9 | 那么外层的deferred如何知晓何时恢复执行呢？很简单，在内层deferred上添加callback或errback即可（即激活内层的deferred）。因此，当内层deferrd被激活时，外层的deferred恢复其回调链的执行。当内层deferred回调执行成功，那么外层deferred会调用第N+1个callback回调。相反，如果内层deferred执行失败，那么外层deferred会调用第N+1个errback回调。
10 |
11 | 图28形象地解释说明了这一过程：
12 |
13 |
14 | 图28 内层与外层deferred的交互
15 |
16 | 在这个图示中，外层的deferred有四个callback/errback对。当外围的deferred被激活后，其第一个callback回调返回了一个deferred（即内层deferred）。从这里开始，外层的deferred停止激活其回调链并且将控制权交还给了reactor（当然是在给内层deferred添加callback/errback之后）。过了一段时间之后，内层deferred被激活，然后执行它的回调链并执行完毕后恢复外层deferred的回调执行过程。注意到，外层deferred是无法激活内层deferred的。这是不可能的，因为外层的deferred根本就无法获知内层的deferred何时能把结果准备好及结果内容是什么。相反，外层的deferred只可能等待（当然是异步方式）内部deferred的激活。
17 |
18 | 注意到外层deferred的产生内层deferred的回调的连线是黑色的而不是红色或蓝色，这是因为我们在内层deferred激活之前是无法获知此回调返回的结果是执行成功还执行失败。只有在内层deferred激活时，我们才能决定下一个回调是callback还是errback。
19 |
20 | 图29从reactor的角度来说明了外层与内层deferred的执行序列：
21 |
22 |
23 | 图29 控制权的转换
24 |
25 | 这也许是Deferred类最为复杂的功能，但无需担心你可能会花费大量时间来理解它。我们将在示例[twisted-deferred/defer-10.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-deferred/defer-10.py)中说明如何使用它。这个例子中，我们创建了两个外层deferred，一个使用了简单的回调，另一个其中的一个回调返回了一个内部deferred。通过阅读这段代码，我们可以发现外层deferred是在内层deferred激活后才开始继续执行回调链的。
26 |
27 | ### 客户端版本6.0
28 |
29 | 我们将使用新学的deferred嵌套来重写我们的客户端来使用由服务器提供的样式转换服务。其实现代码在[twisted-client-6/get-poetry.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-6/get-poetry.py)中。与前几个版本一样，协议与工厂都没有改变。但我们添加了进行格式转换服务请求的协议与工厂实现。下面是协议实现代码：
30 | ```python
31 | class TransformClientProtocol(NetstringReceiver):
32 | def connectionMade(self):
33 | self.sendRequest(self.factory.xform_name, self.factory.poem)
34 | def sendRequest(self, xform_name, poem):
35 | self.sendString(xform_name + '.' + poem)
36 | def stringReceived(self, s):
37 | self.transport.loseConnection()
38 | self.poemReceived(s)
39 | def poemReceived(self, poem):
40 | self.factory.handlePoem(poem)
41 | ```
42 | 使用NetstringReceiver作为基类可以很简单地实现我们的协议。只要连接一旦建立我们就发出格式转换服务的请求。当我们得到格式转换之后的诗歌后交给工厂进行处理，下面是工厂代码：
43 | ```python
44 | class TransformClientFactory(ClientFactory):
45 | protocol = TransformClientProtocol
46 | def __init__(self, xform_name, poem):
47 | self.xform_name = xform_name
48 | self.poem = poem
49 | self.deferred = defer.Deferred()
50 | def handlePoem(self, poem):
51 | d, self.deferred = self.deferred, None
52 | d.callback(poem)
53 | def clientConnectionLost(self, _, reason):
54 | if self.deferred is not None:
55 | d, self.deferred = self.deferred, None
56 | d.errback(reason)
57 | clientConnectionFailed = clientConnectionLost
58 | ```
59 | 值得注意的是，工厂是如何处理这两种类型错误：连接失败和诗歌未全部接收就中断连接。clientConncetionLost可能会在我们已经接收完诗歌后激活执行（即连接断开了），但在这种情况下，self.deferred已经是个None值，这得益于handePoem中对deferredr 处理。
60 |
61 | 这个工厂创建了一个deferred并且最后激活了它，这在Twisted编程中是一个好的习惯，即
62 |
63 | > **通常情况下，一个对象创建了一个deferred，那么它应当负责激活它。**
64 |
65 | 除了格式转换工厂外，还有一个Proxy类包装了具体创建一个TCP连接到格式转换服务器：
66 | ```python
67 | class TransformProxy(object):
68 | """
69 | I proxy requests to a transformation service.
70 | """
71 | def __init__(self, host, port):
72 | self.host = host
73 | self.port = port
74 | def xform(self, xform_name, poem):
75 | factory = TransformClientFactory(xform_name, poem)
76 | from twisted.internet import reactor
77 | reactor.connectTCP(self.host, self.port, factory)
78 | return factory.deferred
79 | ```
80 | 这个类提供了一个xform接口，以让其它程序请求格式转换服务。这样一来其它代码只需要提出请求并得到一个deferred，而无需考虑什么端口与IP地址之类的问题。
81 |
82 | 剩下的代码除了try_to_cummingsify外都没有改变：
83 | ```python
84 | def try_to_cummingsify(poem):
85 | d = proxy.xform('cummingsify', poem)
86 | def fail(err):
87 | print >>sys.stderr, 'Cummingsify failed!'
88 | return poem
89 | return d.addErrback(fail)
90 | ```
91 | 这个作为外层deferred的回调返回了一个内层的deferred，main函数除了修改创建一个Proxy对象这个地方，其他地方都不需要修改。由于try_to_cummingsify已经是deferred回调链中的一部分，因此其早已使用了异步方式， 这里无需更改。
92 |
93 | 你可能注意到return d.addErrback(fail)这句，其等价于
94 | ```python
95 | d.addErrback(fail)
96 | return d
97 | ```
98 |
99 | ### 测试客户端
100 |
101 | 新版客户端的启动和老版的稍微有点不同，如果有1个带诗歌转换服务的服务器运行10001端口，2个诗歌下载服务器分别运行在10002和10003端口， 你可以这样启动客户端：
102 | ```
103 | python twisted-client-6/get-poetry.py 10001 10002 10003
104 | ```
105 | 它会从诗歌下载服务器下载2首诗歌，然后通过诗歌转换服务器转换它们。你可以这样启动诗歌转换服务器：
106 | ```
107 | python twisted-server-1/transformedpoetry.py --port 10001
108 | ```
109 | 启动2个诗歌下载服务器：
110 | ```
111 | python twisted-server-1/fastpoetry.py --port 10002 poetry/fascination.txt
112 | python twisted-server-1/fastpoetry.py --port 10003 poetry/science.txt
113 | ```
114 | 现在就可以像上面一样运行诗歌客户端了。下面你可以尝试这样的场景， 让诗歌转换服务器崩掉， 然后用同样的命令再次运行诗歌客户端。
115 |
116 | ### 结束语
117 |
118 | 这一部分我们学习了关于deferred如何透明地在完成了内部(deferred)回调链后继续处理的过程。并由此，我们可以无需考虑内部实现细节并放心地在外部deferred上添加回调。
119 |
120 | 在第十四部分，我们将讲解deferred的另外一个特性。
121 |
122 | ### 参考
123 |
124 | 本部分原作参见: dave @
125 |
126 | 本部分翻译内容参见杨晓伟的博客
127 |
--------------------------------------------------------------------------------
/zh/p14.md:
--------------------------------------------------------------------------------
1 | ### 介绍
2 |
3 | 这部分我们要介绍Deferred的另外一个功能。便于讨论，我们设定如下情景：假设由于众多的内部网请求一个外部诗歌下载服务器，但由于这个外部下载服务器性能太差或请求负荷太重。因此，我们不想将所有的内部请求全部发送到外部服务器。
4 |
5 | 我们的处理办法是，在中间添加一个缓存代理。当一个请求来到后，缓存服务器会从缓存中返回备份（如果有缓存）或者直接从外部服务器获得。部署图如图30所示：
6 |
7 |
8 | 图30 缓存代理服务器
9 |
10 | 考虑到客户端端发送请求来时，缓存代理可能会将本地缓冲的诗歌取出返回，也有可能需要异步等待外部诗歌下载服务器的回复。如此一来，就会出现这样的情景：客户端发送来的请求，缓存代理处理请求可能是同步也可能是异步。
11 |
12 | 要解决这个需要，就用到了Deferred的另一个特性：可以在返回Deferred前就激活。之所以可以这样做，是因为你可以在一个已经激活的deferred上添加回调处理函数。一个非常值得注意的是：已经被激活的deferred可以立即激活新添加的回调处理函数。图31表示一个已经激活的deferred：
13 |
14 |
15 | 图31 已经激活的deferred
16 |
17 | 如果在此时，我们再为其另一对callback/errback，那么会立即激活执行新的回调。如图32
18 |
19 |
20 | 图32 同一个deferred在添加新的回调之后
21 |
22 | 后面的callback回调被执行，是因为前面的callback执行成功。如果前面执行失败，那么接下来执行的将是新添加的errback回调。
23 |
24 | 我们可以通过 [twisted-deferred/defer-11.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-deferred/defer-11.py) 示例来检测我们这里说到的特性。其中第二组例子，演示了deferred中的pause与unpause函数的功能，即可以暂停一个已经激活的deferred对其回调链上回调的激活。并可以用unpause来解除暂停设置。这两个函数同样完成了在回调中继续产生deferred期间的控制。
25 | 我们可以通过 [twisted-deferred/defer-11.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-deferred/defer-11.py) 示例来检测我们这里说到的特性。其中第二组例子，演示了deferred中的pause与unpause函数的功能，pause可以暂停一个已经激活的deferred对其回调链上回调的激活，unpause可以解除暂停。这个机制类似于“当Deferred回调链上的回调函数又返回Deferred时，Deferred暂停自己”。
26 |
27 | ### 代理 1.0版本
28 |
29 | 让我们来看看第一个版本的缓存代理的实现[twisted-server-1/poetry-proxy.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-1/poetry-proxy.py)。由于该服务器既作为服务器向客户端请求提供本地缓存的诗歌，同时也要作为向外部诗歌下载服务器提出下载请求的客户端，因此其有两套协议/工厂，一套实现服务器角色，另一套实现客户端角色。
30 |
31 | 首先我们先来看看ProxyService的实现部分：
32 | ```python
33 | class ProxyService(object):
34 | poem = None # the cached poem
35 | def __init__(self, host, port):
36 | self.host = host
37 | self.port = port
38 | def get_poem(self):
39 | if self.poem is not None:
40 | print 'Using cached poem.'
41 | return self.poem
42 | print 'Fetching poem from server.'
43 | factory = PoetryClientFactory()
44 | factory.deferred.addCallback(self.set_poem)
45 | from twisted.internet import reactor
46 | reactor.connectTCP(self.host, self.port, factory)
47 | return factory.deferred
48 | def set_poem(self, poem):
49 | self.poem = poem
50 | return poem
51 | ```
52 | 主要的函数是get_poem。如果缓存中没有请求的诗歌，那么就会建立连接从外部服务器中异步取得而返回一个deferred，并将取得的诗歌放到缓冲区中。相反，若缓冲区中存在请求的诗歌，则直接返回诗歌。
53 |
54 | 我们如何来处理这样一个返回值不确定的函数呢，让我们来看看实现服务器角色的协议/工厂：
55 | ```python
56 | class PoetryProxyProtocol(Protocol):
57 | def connectionMade(self):
58 | d = maybeDeferred(self.factory.service.get_poem)
59 | d.addCallback(self.transport.write)
60 | d.addBoth(lambda r: self.transport.loseConnection())
61 |
62 | class PoetryProxyFactory(ServerFactory):
63 | protocol = PoetryProxyProtocol
64 | def __init__(self, service):
65 | self.service = service
66 | ```
67 | 这里使用了maybeDeferred函数解决了这个问题。此函数的功能就是如果作为其参数返回值为defer，那么其不作任何处理，原样将defer返回。但如何返回值不是defer而是一个值（正如我们的缓存代理将本地缓冲的诗歌返回一样），那么这个maybeDeferred会将该值重新打包成一个已经激活的deferred返回，注意是已经激活的deferred。当然，如果返回的是一个异常，其也会将其打包成一个已经激活的deferred，只不过就不是通过callback而是errback激活的。
68 |
69 | ### 运行代理服务器
70 |
71 | 启动诗歌下载服务器：
72 | ```
73 | python twisted-server-1/fastpoetry.py --port 10001 poetry/fascination.txt
74 | ```
75 | 启动代理服务器：
76 | ```
77 | python twisted-server-1/poetry-proxy.py --port 10000 10001
78 | ```
79 | 代理服务器监听10000端口，连接100001端口下载诗歌。
80 |
81 | 开一个客户端：
82 | ```
83 | python twisted-client-4/get-poetry.py 10000
84 | ```
85 | 我们使用早期不带诗歌翻译功能的客户端。你可以看到客户端窗口中显示了诗歌内容，代理服务器窗口显示“从下载服务器获取诗歌”。你可以再次启动客户端，代理服务器会从缓存中取得诗歌返回，客户端显示的内容和刚才一样。
86 |
87 | ### 代理 2.0版本
88 |
89 | 前面我们已经提到，有另一种替代方法来实现这一机制。这在 [twisted-server-2/poetry-proxy.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-2/poetry-proxy.py) 中很好的说明了。即我们可以返回一个已经激活的defer，放在这儿就是如果缓存代理中有请求的诗歌，那么就通过返回一个激活的deferred：
90 | ```python
91 | def get_poem(self):
92 | if self.poem is not None:
93 | print 'Using cached poem.'
94 | # return an already-fired deferred
95 | return succeed(self.poem)
96 | print 'Fetching poem from server.'
97 | factory = PoetryClientFactory()
98 | factory.deferred.addCallback(self.set_poem)
99 | from twisted.internet import reactor
100 | reactor.connectTCP(self.host, self.port, factory)
101 | return factory.deferred
102 | ```
103 | 如果我们去看[defer.succeed](http://twistedmatrix.com/trac/browser/trunk/twisted/internet/defer.py)的源码会发现，其只是在返回一个deferred之前，将其激活。同样，如果想要返回一个以失败的方式激活的deferred，可以调用函数[defer.fail](http://twistedmatrix.com/trac/browser/trunk/twisted/internet/defer.py)
104 |
105 | 在这个版本中，由于get_poem返回的是deferred而不像前一个版本存在不确定性因素。因此协议实现就无需使用maybeDeferred(当然也可以使用)：
106 | ```python
107 | class PoetryProxyProtocol(Protocol):
108 | def connectionMade(self):
109 | d = self.factory.service.get_poem()
110 | d.addCallback(self.transport.write)
111 | d.addBoth(lambda r: self.transport.loseConnection())
112 | ```
113 | 除了这两个地方，其他地方都是相同的，你可以使用上面的方法运行测试，结果是一样的。
114 |
115 | ### 总结
116 |
117 | 这个部分我们学习到了deferred可以在返回之前被激活，这样我们就可以将其用于同步环境中。并且我们已经知道了有两种方法来实现：
118 |
119 | 1. 当一个函数有时返回Deferred，有时返回一个普通的值，可以使用maybeDeferred函数
120 | 2. 使用succeed/fail来返回已经激活的Deferred， 包装“半同步”方法。
121 |
122 | 两者返回的都是deferred, 选择使用哪一种主要看你自己。前面事实已经证明，我们的函数并不是一直都是异步。如何选择并没有一个事实上的标准。
123 |
124 | Deferred可以在激活后添加新的回调也间接说明了我们在第九部分[twisted-deferred/defer-unhandled.py](http://github.com/jdavisp3/twisted-intro/blob/master/twisted-deferred/defer-unhandled.py)(提到的，deferred中会在最后一个回调中遇到未处理异常，并在此deferred被垃圾回收（即其已经没有任何外界引用）时才将该异常的情况打印出来。即deferred回在其销毁前一直持有异常，等待可能还会添加进来的回调来处理。
125 |
126 | 我们已经将deferred中的大部分功能都介绍完了，当然Twisted开发人员可能不会增强deferred的功能。我们下一部分将讲讲Twisted的其它内容。
127 |
128 | ### 参考
129 |
130 | 本部分原作参见: dave @
131 |
132 | 本部分翻译内容参见杨晓伟的博客
133 |
--------------------------------------------------------------------------------
/zh/p15.md:
--------------------------------------------------------------------------------
1 | ### 简介
2 |
3 | 在我们探索Twisted的过程中写了很多代码, 但目前我们却忽略了一些重要的东西 —— 测试. 你也许会疑问怎样用像 [unittest](http://docs.python.org/library/unittest.html#module-unittest) 这样Python自带的同步框架测试异步代码. 答案是你不能. 正如我们已经发现的,同步代码和异步代码是不能混合的, 至少不容易.
4 |
5 | 幸运地是, Twisted包含自己的测试框架, 叫 [trial](http://twistedmatrix.com/documents/current/core/howto/testing.html), 它支持测试异步代码(当然你也可以用它测试同步代码).
6 |
7 | 我们假设你已经熟悉了 [unittest](http://docs.python.org/library/unittest.html#module-unittest)和相似的测试框架的原理, 它允许你通过定义类创建测试. 这个类通常是继承一个一个特殊的父类(通常叫"`TestCase`"), 类中的方法以"`test`"开头并被视作一个测试. 框架负责发现所有的测试, 一个接一个地运行它们, 并伴有可选项 `setUp` 和 `tearDown` 步骤, 然后报告测试结果.
8 |
9 | ### 例子
10 |
11 | 你可以在 [tests/test_poetry.py](https://github.com/jdavisp3/twisted-intro/blob/master/tests/test_poetry.py#L1) 中找到一些关于测试的例子.为了确保我们所有的例子是自包含的(以便你不用担心`PYTHONPAYH`设置),我们将所有需要的代码拷贝到测试模块中.当然正常情况,你只需导入需要测试的模块.
12 |
13 | 通过使用客户端从测试服务器抓取一首诗, 这个例子既测试了诗歌客户端又测试了服务器. 为了提供一个可供测试的诗歌服务器, 我们在测试案例中实现 [setUp](https://github.com/jdavisp3/twisted-intro/blob/master/tests/test_poetry.py#L70)方法:
14 | ```python
15 | class PoetryTestCase(TestCase):
16 |
17 | def setUp(self):
18 | factory = PoetryServerFactory(TEST_POEM)
19 | from twisted.internet import reactor
20 | self.port = reactor.listenTCP(0, factory, interface="127.0.0.1")
21 | self.portnum = self.port.getHost().port
22 | ```
23 | 这个 `setUp` 方法用一首测试诗建立诗歌服务器,然后监听一个随机开放端口.我们保存了端口号,以便实际测试需要时可以利用.当然测试结束时我们会用 [tearDown](https://github.com/jdavisp3/twisted-intro/blob/master/tests/test_poetry.py#L76) 清除测试服务器:
24 | ```python
25 | def tearDown(self):
26 | port, self.port = self.port, None
27 | return port.stopListening()
28 | ```
29 | [test_client](https://github.com/jdavisp3/twisted-intro/blob/master/tests/test_poetry.py#L80)把我们带到了第一个测试, 用 `get_poetry` 从测试服务器获取诗歌并且验证这就是我们所期望的诗歌:
30 | ```python
31 | def test_client(self):
32 | """The correct poem is returned by get_poetry."""
33 | d = get_poetry('127.0.0.1', self.portnum)
34 | def got_poem(poem):
35 | self.assertEquals(poem, TEST_POEM)
36 | d.addCallback(got_poem)
37 | return d
38 | ```
39 | 注意我们的测试函数返回一个 `deferred`.在 `trial` 中,每个测试方法都以回调的方式运行.这意味着 `reactor` 正在运行并且我们可以以测试的一部分执行异步操作.我们仅仅需要让框架知道测试是异步的,这可以通过采用常规的Twisted方式 —— 返回 `deferred` 来实现.
40 |
41 | `trial` 框架在调用 `tearDown` 方法之前将等待直到 `deferred` 激发,并且当 `deferred` 失败时将使测试失败(如,最后一个callback/errback对失败).如果我们的 `deferred` 太长时间才被激活调用(默认2分钟), 它同样会使测试失败.这意味着如果测试完成,我们知道 `deferred` 激发了, 那我们的回调就会激发并且运行 `assertEquals` 测试方法.
42 |
43 | 我们的第二个测试, [test_failure](https://github.com/jdavisp3/twisted-intro/blob/master/tests/test_poetry.py#L91), 证实 `get_poetry` 如果不能连接到服务器会以适当的方式失败:
44 | ```python
45 | def test_failure(self):
46 | """The correct failure is returned by get_poetry when
47 | connecting to a port with no server."""
48 | d = get_poetry('127.0.0.1', -1)
49 | return self.assertFailure(d, ConnectionRefusedError)
50 | ```
51 | 这里我们打算连接到一个无效端口,之后使用trial提供的 `assertFailure` 方法.这个方法类似于熟悉的 `assertRaises` 方法，但是`assertFailure`是针对异步代码的.它返回一个 `deferred`,如果这个 `deferred` 失败则返回成功,否则返回失败.
52 |
53 | 你可以用trial脚本自己运行这些测试,如下:
54 | ```
55 | trial tests/test_poetry.py
56 | ```
57 | 你将看到每个测试案例的输出, OK表示测试通过了.
58 |
59 | ### 讨论
60 |
61 | 由于当谈到基本API时,trial与unittest十分相似,所以开始写测试十分容易.如果你的测试使用异步代码,仅仅返回 `deferred` 就可以了,trial将负责其余的事情.你也可以从 `setUp` 或 `tearDown` 方法返回一个 `deferred`,如果它们也需要异步.
62 |
63 | 任何来自测试的日志消息将被收集到当前文件夹下的一个文件中,即"`_trial_temp`", trial会自动创建它. 除了打印到屏幕的错误,日志是调试失败测试的实用入口.
64 |
65 | 图33显示了一个正在进行中的假想测试：
66 |
67 |
68 | 图33 进行中的trial测试
69 |
70 | 如果你之前使用过类似的框架,这是一个熟悉的模型,除了所有测试相关的方法可能返回 `deferreds`.
71 |
72 | trial框架是一个关于如何"异步运作"的很好例子,包括级联在整个程序中的变化.为了使一个测试(或任何函数,方法)是异步的,它必须:
73 |
74 | 1. 非阻塞,并且通常
75 | 2. 返回一个 `deferred`.
76 |
77 | 但这意味着无论什么调用,那个函数必须愿意接收一个 `deferred`,并且非阻塞(如此又好像返回了一个 `deferred`).如此这般一层又一层.这样就呼唤出现trial一样的框架,可以处理返回 `deferreds` 的异步测试.
78 |
79 | ### 总结
80 |
81 | 这就是关于单元测试的内容.如果你想了解更多关于如何为Twisted代码写单元测试的例子,你只需要看看Twisted代码本身.Twisted框架自带了一套非常庞大的单元测试,而且每个新的发布又会加入很多.由于这些测试在被接受入代码库之前,经过严格的代码评论以及Twisted专家们的仔细审查,故而它们是告诉你如何以正确方式测试Twisted代码的极好例子.
82 |
83 | 在第十六节中,我们将使用Twisted工具将诗歌服务器转化为一个真正的守护进程.
84 |
85 | ### 参考练习
86 |
87 | 1. 改变测试之一使其失败,然后再次运行 `trial` 看看输出结果.
88 | 2. 阅读 [trial 在线文档](http://twistedmatrix.com/documents/current/core/howto/testing.html)
89 | 3. 为我们这个系列中所创建的其他诗歌服务写测试.
90 | 4. 探索Twisted中的 [一些测试](http://twistedmatrix.com/trac/browser/trunk/twisted/test)
91 |
92 | ### 参考
93 |
94 | 本部分原作参见: dave @
95 |
96 | 本部分翻译内容参见luocheng @
97 |
--------------------------------------------------------------------------------
/zh/p16.md:
--------------------------------------------------------------------------------
1 | ### 简介
2 |
3 | 目前我们所写的服务器仅仅运行在终端窗口，结果通过 `print` 语句输出到屏幕.这对于开发来说已经足够，但对于产品级的部署还远远不够. 健壮的产品级服务器应该：
4 |
5 | 1. 运行一个 [daemon](http://en.wikipedia.org/wiki/Daemon_%28computer_software%29) 进程,这个进程不与任何终端或用户会话相关.因为没有人愿意当某用户登出时服务自动关闭.
6 | 2. 将调试和错误信息发送到一系列滚转日志文件, 或者 [syslog](http://en.wikipedia.org/wiki/Syslog) 服务.
7 | 3. 放弃过高的权限,比如,在运行前切换到较低权限.
8 | 4. 保存它的 [pid](http://en.wikipedia.org/wiki/Process_ID) 文件以便管理员方便地向 daemon [发送信号](http://en.wikipedia.org/wiki/Kill%28%29).
9 |
10 | 我们可以利用Twisted提供的 `twistd` 脚本获得所有以上功能. 但是首先需要稍稍修改我们的代码.
11 |
12 | ### IService
13 |
14 | [IService](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L87) 接口定义了一个可以启动或停止的命名服务. 这个服务究竟做了些什么? 答案是任何你喜欢的事情——这个接口只需要自提供的一些通用属性和方法,无须用户定义特定的函数.
15 |
16 | 这边有两个需要的属性: `name` 和 `running`.其中 `name` 属性是一个字符串,如 "`fastpoetry`",或者 `None` 如果你不想给这个服务起名字. `running` 属性是 **Boolean** 变量,如果服务成功启动,值为 `True`.
17 |
18 | 下面我们只涉及 `IService` 的某些方法, 跳过那些很显而易见的或者在简单的Twisted程序中用不到的高级方法. [startService](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L130) 和 [stopService](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L135) 是 `IService` 的两个关键方法：
19 | ```python
20 | def startService():
21 | """
22 | Start the service.
23 | """
24 |
25 | def stopService():
26 | """
27 | Stop the service.
28 |
29 | @rtype: L{Deferred}
30 | @return: a L{Deferred} which is triggered when the service has
31 | finished shutting down. If shutting down is immediate, a
32 | value can be returned (usually, C{None}).
33 | """
34 | ```
35 | 同样,这些方法做什么取决于服务的需求,比如 `startService` 可能会:
36 |
37 | + 加载配置数据,或
38 | + 初始化数据库,或
39 | + 开始监听某端口,或
40 | + 什么也不做.
41 |
42 | `stopService` 可能会:
43 |
44 | + 储存状态,或
45 | + 关闭打开的数据库连接,或
46 | + 停止监听某端口,或
47 | + 什么也不做.
48 |
49 | 当我们写自定义服务时, 要恰当地实现这些方法.对于一些通用的行为,比如监听某端口,Twisted提供了现成的服务可以使用.
50 |
51 | 注意 `stopService` 可以选择地返回 `deferred`,要求当服务完全关闭时被激发.这允许我们的服务在结束之后与整个程序终止之前完成清理工作.如果你需要服务立即关闭,可以仅仅返回 `None` 而不是 `deferred`.
52 |
53 | 服务可以被组织成集合以便一起启动和停止.下面来看看这里最后一个 `IService` 方法: [setServiceParent](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L107),它添加一个服务到集合:
54 | ```python
55 | def setServiceParent(parent):
56 | """
57 | Set the parent of the service.
58 | @type parent: L{IServiceCollection}
59 | @raise RuntimeError: Raised if the service already has a parent
60 | or if the service has a name and the parent already has a child
61 | by that name.
62 | """
63 | ```
64 | 任何服务都可以有双亲,这意味着服务可以被组织为层级结构.这把我们引向了今天讨论的另一个接口.
65 |
66 | ### IServiceCollection
67 |
68 | [IServiceCollection](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L203) 接口定义了一个对象，它可包含若干个 `IService` 对象.一个服务集合仅仅是一个普通的类容器,具有以下方法:
69 |
70 | + 通过名字查找某服务([getServiceNamed](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L212))
71 | + 遍历集合中的服务([__iter__](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L222))
72 | + 添加一个服务到集合([addService](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L227))
73 | + 从集合中移除一个服务([removeService](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L236))
74 |
75 | ### Application
76 |
77 | 一个Twisted `Application` 不是通过一个单独的接口定义的.相反, `Application` 对象需要实现 `IService` 和 `IServiceCollection` 接口以及一些我们未曾涉及的接口.
78 |
79 | `Application` 是一个代表你整个Twisted应用的最顶层的服务. 在你 `daemon` 中的所有其他服务将是这个 `Application` 对象的儿子(甚至孙子,等等.).
80 |
81 | 其实需要你自己实现 `Application` 的机会很小,Twisted已经提供了一个当下常用的实现.
82 |
83 | ### Twisted Logging
84 |
85 | Twisted在其模块 [twistd.python.log](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/python/log.py) 中包含了其自身的日志架构.由于写日志的基本 **API** 非常简单, 我们仅仅介绍一个小例子： [basic-twisted/log.py](https://github.com/jdavisp3/twisted-intro/blob/master/basic-twisted/log.py),如果你感兴趣更多细节可以浏览Twisted模块.
86 |
87 | 我们也不详细介绍安装日志处理程序的 **API**,因为 `twistd` 脚本会帮我们做.
88 |
89 | ### FastPoetry 2.0
90 |
91 | 好吧,让我们看看代码.我们已经将快诗服务器升级为使用 `twistd`. 源码在 [twisted-server-3/fastpoetry.py](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-3/fastpoetry.py#L1). 首先我们有了 [诗歌协议](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-3/fastpoetry.py#L9):
92 | ```python
93 | class PoetryProtocol(Protocol):
94 |
95 | def connectionMade(self):
96 | poem = self.factory.service.poem
97 | log.msg('sending %d bytes of poetry to %s'
98 | % (len(poem), self.transport.getPeer()))
99 | self.transport.write(poem)
100 | self.transport.loseConnection()
101 | ```
102 | 注意没有使用 `print` 语句,而是使用 `twisted.python.log.msg` 函数去记录每个新连接.
103 |
104 | 这里是 [工厂类](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-3/fastpoetry.py#L19):
105 | ```python
106 | class PoetryFactory(ServerFactory):
107 |
108 | protocol = PoetryProtocol
109 |
110 | def __init__(self, service):
111 | self.service = service
112 | ```
113 | 正如你看到的，诗不再储存在工厂中，而是储存在一个被工厂引用的服务对象上。注意这边协议是如何通过工厂从服务获得诗歌.最后,看一下 [服务类](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-3/fastpoetry.py#L27):
114 | ```python
115 | class PoetryService(service.Service):
116 |
117 | def __init__(self, poetry_file):
118 | self.poetry_file = poetry_file
119 |
120 | def startService(self):
121 | service.Service.startService(self)
122 | self.poem = open(self.poetry_file).read()
123 | log.msg('loaded a poem from: %s' % (self.poetry_file,))
124 | ```
125 | 就像许多其他接口类一样,Twisted提供了一个基类供自定义实现,同时具有方便的默认行为.
126 |
127 | 我们使用 [twisted.application.service.Service](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/application/service.py#L154) 类实现 `PoetryService`.
128 |
129 | 这个基类提供了所有必要方法的默认实现,所以我们只需要实现个性化的行为.在上面的例子中,我们只重载了 `startService` 方法来加载诗歌文件.注:我们仍然调用了相应的基类方法(它为我们设置 `running` 属性).
130 |
131 | 另外值得一提的是： `PoetryService` 对象不知道关于 `PoetryProtocol` 的任何细节.这里服务的任务仅仅是加载诗歌以及为其他需要诗歌的对象提供接口.也就是说, `PoetryService` 只关心提供诗歌的更高层的细节,而不是关心诸如通过 **TCP** 连接发送诗歌这样的更底层的细节.所以同样的服务可以被另外的协议使用,如 **UDP** 或 **XML-RPC**.虽然对于简单的服务好处不大,但你可以想象其在更实际服务实现中的优势.
132 |
133 | 如果这是一个典型的Twisted程序,到目前我们看到的代码都不该出现在这个文件里.它们应该在一些模块当中(也许是 `fastpoetry` 和 `fastpoetry.service`).但是,遵循我们的惯例会使这些例子自包含,也就是在一个脚本中包含了所有东西.
134 |
135 | ### Twisted tac files
136 |
137 | 这个脚本的其余部分包含通常作为完整内容的 `Twisted tac` 文件. `tac` 文件是一个 `Twisted Application Configuration` 文件,它告诉 `twistd` 怎样去构建一个应用.作为一个配置文件,它负责选择设置(如端口,诗歌文件位置等)来以一种特定的方式运行这个应用.换句话说, `tac` 代表我们服务的一个特定部署(在这个端口服务这首诗),而不是启动任何诗歌服务的一般脚本.
138 |
139 | 如果我们在同一个域运行多个诗歌服务,我们将为每一个服务准备一个 `tac` 文件(因此你可以明白为什么 `tac` 文件通常不包含任何一般目的的代码).在我们的例子中, `tac` 文件被配置为使 [poetry/ecstasy.txt](https://github.com/jdavisp3/twisted-intro/blob/master/poetry/ecstasy.txt) 运行在回环接口的10000号端口:
140 | ```python
141 | # configuration parameters
142 | port = 10000
143 | iface = 'localhost'
144 | poetry_file = 'poetry/ecstasy.txt'
145 | ```
146 | 注意 `twistd` 并不知道这些特定变量,我们仅仅将这些配置值统一的放在这里.事实上, `twistd` 只关心整个文件中的一个变量,我们即将看到.下面我们开始建立我们的应用:
147 | ```python
148 | # this will hold the services that combine to form the poetry server
149 | top_service = service.MultiService()
150 | ```
151 | 我们的诗歌服务器将包含两个服务, 上文定义的 `PoetryService`,和一个Twisted的内置服务,它将建立服务我们诗歌的监听套接字.由于这两个服务明显的相关,我们用 `MultiService`(一个实现 `IServiceCollection` 和 `IService` 的类) 将它们组织在一起.
152 |
153 | 作为一个服务集合, `MultiService` 把我们的诗歌服务组织在一起.同时作为一个服务, `MultiService` 启动时将启动它的子服务,关闭时将关闭它的子服务.让我们向服务集合 [添加](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-3/fastpoetry.py#L48) 第一个诗歌服务:
154 | ```python
155 | # the poetry service holds the poem. it will load the poem when it is
156 | # started
157 | poetry_service = PoetryService(poetry_file)
158 | poetry_service.setServiceParent(top_service)
159 | ```
160 | 这是非常简单的内容.我们仅创建了 `PoetryService`,然后用 `setServiceParent` 方法将其添加到服务集合.下面我们添加 **TCP** 监听器:
161 | ```python
162 | # the tcp service connects the factory to a listening socket. it will
163 | # create the listening socket when it is started
164 | factory = PoetryFactory(poetry_service)
165 | tcp_service = internet.TCPServer(port, factory, interface=iface)
166 | tcp_service.setServiceParent(top_service)
167 | ```
168 | Twisted为创建连接到任意工厂的 **TCP** 监听套接字提供了 `TCPServer` 服务(这里是 `PoetryFactory`),我们没有直接调用 `reactor.listenTCP` 因为 `tac` 文件的工作是使我们的应用准备好开始,而不是实际启动它. 这里 `TCPServer` 将在被 `twistd` 启动后创建套接字.
169 |
170 | 你可能注意到我们没有为任何服务起名字.为服务起名不是必需的,而仅是一个可选项,如果你希望在运行时查找服务.因为我们不需要这个功能,所以这里没有为服务命名.
171 |
172 | 既然我们已经将两个服务绑定到服务集合.现只需创建我们的应用,并且将它添加到集合:
173 | ```python
174 | # this variable has to be named 'application'
175 | application = service.Application("fastpoetry")
176 |
177 | # this hooks the collection we made to the application
178 | top_service.setServiceParent(application)
179 | ```
180 | 在这个脚本中 `twistd` 所关心的唯一变量就是 `application`. `twistd` 正是通过它找到那个需要启动的应用(所以这个变量必须被命名为 `applicaton`).当应用被启动时,我们添加到它的所有服务都会被启动.
181 |
182 | 图34显示了我们刚刚建立的应用的结构:
183 |
184 |
185 | 图34 fastpoetry 应用的结构图
186 |
187 | ### Running the Server
188 |
189 | 让我们的新服务器运转起来.作为 `tac` 文件,我们需要用 `twistd` 启动它.当然,它仅仅是一个普通的Python文件.所以我们首先用 `python` 命令启动,再看看会发生什么:
190 | ```
191 | python twisted-server-3/fastpoetry.py
192 | ```
193 | 如果你这样做,会发现什么也没有发生！正如前文所述, `tac` 文件的工作是使我们的应用准备好运行,而不是实际运行它.作为 `tac` 文件这个特殊目的的提醒,人们将它的扩展名规定为 `.tac` 而不是 `.py`.但是 `twistd` 脚本实际并不区分扩展名.
194 |
195 | 让我们用 `twistd` 脚本来实际运行这个服务器:
196 | ```
197 | twistd --nodaemon --python twisted-server-3/fastpoetry.py
198 | ```
199 | 运行以上命令后会看到如下输出:
200 | ```
201 | 2010-06-23 20:57:14-0700 [-] Log opened.
202 | 2010-06-23 20:57:14-0700 [-] twistd 10.0.0 (/usr/bin/python 2.6.5) starting up.
203 | 2010-06-23 20:57:14-0700 [-] reactor class: twisted.internet.selectreactor.SelectReactor.
204 | 2010-06-23 20:57:14-0700 [-] __builtin__.PoetryFactory starting on 10000
205 | 2010-06-23 20:57:14-0700 [-] Starting factory <__builtin__.PoetryFactory instance at 0x14ae8c0>
206 | 2010-06-23 20:57:14-0700 [-] loaded a poem from: poetry/ecstasy.txt
207 | ```
208 | 需要注意的几点:
209 |
210 | 1. 你可以看到Twisted日志系统的输出, 包括 `PoetryFactory` 调用 `log.msg`.但是我们在 `tac` 文件中没有安装 `logger`, 所以 `twistd` 会帮我们安装.
211 | 2. 你可以看到我们的两个主要服务 `PoetryService` 和 `TCPServer` 启动了.
212 | 3. shell提示符不会返回. 这表明我们的服务器没有以守护进程方式运行. 默认地, `twistd` 会以守护进程方式运行服务器(这正是 `twistd` 存在的原因), 但是如果你包含"`--nodaemon`" 选项,那么 `twistd` 将以一个常规shell进程的方式运行你的服务器,同时会将日志输出导向到标准输出. 这对于调试 `tac` 文件非常有用.
213 |
214 | 下面测试取诗服务器, 通过我们的诗歌代理或者 `netcat` 命令:
215 | ```
216 | netcat localhost 10000
217 | ```
218 | 这将从服务器抓取诗歌,并且你可以看到一行如下的日志:
219 | ```
220 | 2010-06-27 22:17:39-0700 [__builtin__.PoetryFactory] sending 3003 bytes
221 | of poetry to IPv4Address(TCP, '127.0.0.1', 58208)
222 | ```
223 | 这个日志来自 `PoetryProtocol.connectionMade` 方法调用 `log.msg`.当你向服务器发送更多请求时, 你将看到更多的日志条目.
224 |
225 | 现在可以用 `Ctrl-C` 来终止这个服务器. 你可以看到如下输出:
226 | ```
227 | 2010-06-29 21:32:59-0700 [-] Received SIGINT, shutting down.
228 | 2010-06-29 21:32:59-0700 [-] (Port 10000 Closed)
229 | 2010-06-29 21:32:59-0700 [-] Stopping factory <__builtin__.PoetryFactory instance at 0x28d38c0>
230 | 2010-06-29 21:32:59-0700 [-] Main loop terminated.
231 | 2010-06-29 21:32:59-0700 [-] Server Shut Down.
232 | ```
233 | 正如你看到的, Twisted并没有简单地崩溃, 而是优雅地关闭并将日志信息告诉你.
234 |
235 | 好啦, 现在再次启动服务器:
236 | ```
237 | twistd --nodaemon --python twisted-server-3/fastpoetry.py
238 | ```
239 | 现在打开另一个shell并切换到 `twisted-intro` 目录. 其中有一个叫 `twistd.pid` 的文件. 它是被 `twistd` 创建的, 包含我们这个运行服务器进程号. 试一下下面的方法来关闭服务器:
240 | ```
241 | kill `cat twistd.pid`
242 | ```
243 | 注意当服务器关闭后, `twistd.pid` 文件消失了, 它被 `twistd` 清理了.
244 |
245 | ### A Real Daemon
246 |
247 | 现在让我们以守护进程的方式启动服务器, 这是 `twistd` 的默认方式:
248 | ```
249 | twistd --python twisted-server-3/fastpoetry.py
250 | ```
251 | 这次我们立即看到shell提示符返回. 当你列出目录中的文件时,会发现除了 `twistd.pid` 文件,又出现了 `twistd.log` 文件,它记录了之前显示在shell窗口的日志信息.
252 |
253 | 当启动一个守护进程时, `twistd` 安装一个日志管理器将条目写入一个文件而不是标准输出. 默认的日志文件是 `twistd.log`, 它出现在你运行 `twistd` 的目录中,但是你可以通过"`--logfile`"来改变它的位置. `twistd` 安装的的日志管理器将滚动输出日志信息, 确保其不超过 `1M`.
254 |
255 | 你可以通过列出操作系统上的所有进程来查看正在运行的服务器. 你不妨通过取另一首诗来测试这个服务器. 你可以看到记录每个诗歌请求的新条目出现在日志文件中.
256 |
257 | 由于这个服务器不再与shell相连(或者除了 [init](http://en.wikipedia.org/wiki/Init) 的任何其他进程), 你不能通过 `Ctrl-C` 关闭它. 作为一个真的守护进程, 即使你登出它也继续运行.但是你可以通过 `twistd.pid` 文件终止这个进程:
258 | ```
259 | kill `cat twistd.pid`
260 | ```
261 | 随后, 关闭消息出现在日志文件中, `twistd.pid` 文件被移除, 服务器停止.
262 |
263 | 检查一下其他的 `twistd` 启动选项是个不错的主意. 例如,你可以告诉 `twistd` 在启动进程守护前切换到另一个用户或组账户(是一种当你的服务器不需要安全防范措施取消权限的典型方法). 我们就不进一步探讨那些额外的选项了,你可以通过 `twistd` 的 `--help` 自己研究它们.
264 |
265 | ### Twisted 插件系统
266 |
267 | 现在我们已经通过 `twistd` 启动真正的守护进程服务器. 这非常完美,而且事实上我们的配置文件是纯Python源码文件,这一点为我们设置带来巨大便利. 但是我们有时用不到这样的便利性.对于诗歌服务器,我们通常只关心一小部分选项:
268 |
269 | 1. 需要服务的诗歌
270 | 2. 服务端口
271 | 3. 监听接口
272 |
273 | 为了几个简单的变量建立一个 `tac` 文件显得有点小题大做. 如果我们能够通过 `twistd` 选项指定这些值将非常方便. Twisted的插件系统允许我们可以这样做.
274 |
275 | Twisted插件通过定义 `Application` 提供了一种方法, 可以实现个性化的命令行选项, 进而 `twistd` 动态的发现和运行. Twisted本身具有一套插件,你可以通过运行不带参数的 `twistd` 命令来查看它们. 现在就试一试, 在 `twisted-intro` 目录外. 在帮助部分后面,你可以看到如下输出:
276 | ```
277 | ...
278 | ftp An FTP server.
279 | telnet A simple, telnet-based remote debugging service.
280 | socks A SOCKSv4 proxy service.
281 | ...
282 | ```
283 | 每一行显示了一个Twisted内置的插件, 你可以用 `twistd` 运行它们.
284 |
285 | 每个插件同样有它们自己的选项,你可以通过 `--help` 来发现它们. 让我们看看 `ftp` 插件有什么选项:
286 | ```
287 | twistd ftp --help
288 | ```
289 | 注意我们需要将 `--help` 放在 `ftp` 后面而不是 `twistd` 后面, 因为我们想得到 `ftp` 的可选项.
290 |
291 | 我们可以像运行诗歌服务器一样运行 `ftp` 服务器. 但由于它是一个插件,我们可以仅仅通过它的名字运行:
292 | ```
293 | twistd --nodaemon ftp --port 10001
294 | ```
295 | 以上命令以非守护进程的方式在端口 `10001` 上运行 `ftp` 插件. 注意 `twistd` 的 `nodaemon` 选项出现在插件名字的前面,插件特定选项 `port` 出现在插件名字的后面. 正如我们的诗歌服务器一样,你可以用 `Ctrl-C` 停止它.
296 |
297 | OK, 让我们把诗歌服务器转化为Twisted的插件. 首先我们需要介绍一些新概念.
298 |
299 | ### IPlugin
300 |
301 | 任何Twisted插件都需要实现 [twisted.plugin.IPlugin](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.0.0/twisted/plugin.py#L38) 接口. 如果你浏览这个接口的声明, 你会发现它没有指定任何方法. 实现 `IPlugin` 接口仅仅相当于一个插件在说："你好,我是插件！"以便 `twistd` 找到它. 当然,出于实用考虑,它需要实现一些其他接口,我们很快会介绍.
302 |
303 | 但是你怎样知道一个对象实现了一个空接口? `zope.interface` 包含了一个叫做 `implements` 的函数,它可以用来声明一个特定类实现了一个特定的接口. 我们将在插件版的诗歌服务器中看到这种使用.
304 |
305 | ### IServiceMaker
306 |
307 | 除了 `IPlugin`,我们的插件还实现 `IServiceMaker` 接口. 一个实现了 `IServiceMaker` 接口的对象知道如何创建 `IService`,它将成为运行程序的核心. `IServiceMaker` 指定了三个属性和一个方法:
308 |
309 | 1. `tapname`: 代表插件名字的字符串. "`tap`"代表"Twisted Application Plugin". 注:老版本的Twisted还使用"`tapfiles`"文件,不过这个功能现在已经取消了.
310 | 2. `description`: 插件的描述, `twistd` 将以它作为帮助信息输出.
311 | 3. `options`: 一个代表这个插件接受的命令行选项的对象.
312 | 4. `makeService`: 一个创建 `IService` 对象的方法,需提供一些特定的命令行选项.
313 |
314 | 我们将在下一个版本的诗歌服务器中看到怎样将上述内容组织在一起.
315 |
316 | ### Fast Poetry 3.0
317 |
318 | 现在我们已经为插件版本的"`Fast Poetry`"做好准备,它位于 [twisted/plugins/fastpoetry_plugin.py](https://github.com/jdavisp3/twisted-intro/blob/master/twisted/plugins/fastpoetry_plugin.py#L1).
319 |
320 | 你可能注意到与其他例子不同, 我们命名了一个不同的目录. 这是因为 `twistd` 需要插件文件位于 `twisted/plugins` 目录中, 同时在你的Python搜索路径上. 这个目录不必是一个包(也就是, 不必包含任何 `__init__.py` 文件), 而且在路径上可以有多个 `twisted/plugins` 目录, `twistd` 都会找到它们. 这个插件的实际文件名是什么也没有关系, 但是一个好的方案是根据应用所代表的含义来命名, 就像我们在这里做的.
321 |
322 | 我们的插件开头部分同样包括诗歌协议,工厂,以及像 `tac` 文件中所实现的服务.如前所述,这些代码通常应该单独的存在于一个模块中,但出于我们例子自包含的目的,还是将它们放在插件文件中.
323 |
324 | 下面将 [声明](https://github.com/jdavisp3/twisted-intro/blob/master/twisted/plugins/fastpoetry_plugin.py#L45) 这个插件的命令行选项:
325 | ```python
326 | class Options(usage.Options):
327 |
328 | optParameters = [
329 | ['port', 'p', 10000, 'The port number to listen on.'],
330 | ['poem', None, None, 'The file containing the poem.'],
331 | ['iface', None, 'localhost', 'The interface to listen on.'],
332 | ]
333 | ```
334 | 以上代码指定可以放在 `twistd` 命令后面使用的插件特定选项的名字.
335 |
336 | 这里就不必进一步解释上述选项的含义了,其含义很显然. 下面我们来看一下插件的主要部分 [服务制造类](https://github.com/jdavisp3/twisted-intro/blob/master/twisted/plugins/fastpoetry_plugin.py#L56):
337 | ```python
338 | class PoetryServiceMaker(object):
339 |
340 | implements(service.IServiceMaker, IPlugin)
341 |
342 | tapname = "fastpoetry"
343 | description = "A fast poetry service."
344 | options = Options
345 |
346 | def makeService(self, options):
347 | top_service = service.MultiService()
348 |
349 | poetry_service = PoetryService(options['poem'])
350 | poetry_service.setServiceParent(top_service)
351 |
352 | factory = PoetryFactory(poetry_service)
353 | tcp_service = internet.TCPServer(int(options['port']), factory,
354 | interface=options['iface'])
355 |
356 | tcp_service.setServiceParent(top_service)
357 |
358 | return top_service
359 | ```
360 | 这里你可以看到如何使用 `zope.interface.implements` 函数来声明我们的类同时实现 `IServiceMaker` 和 `IPlugin` 接口.
361 |
362 | 你应该从之前的 `tac` 文件辨认出 `makeService` 中的代码, 但是这次我们不需要自己建立一个 `Application` 对象, 我们仅仅创建并返回最顶层服务,这样我们的程序就可以运行, `twistd` 来处理其余的事情. 注意我们是如何使用 `options` 参数来提取插件传递给 `twistd` 的特定命令行选项.
363 |
364 | 定义了上述类, 还有 [一步](https://github.com/jdavisp3/twisted-intro/blob/master/twisted/plugins/fastpoetry_plugin.py#L81) :
365 | ```python
366 | service_maker = PoetryServiceMaker()
367 | ```
368 | `twistd` 脚本会发现我们插件的实例并使用它构建最顶层服务. 与 `tac` 文件不同的是, 选择什么变量名没有关系, 关键是我们的对象实现了 `IPlugin` 和 `IServiceMaker` 接口.
369 |
370 | 既然已经创建了插件, 让我们运行它. 确保你位于 `twisted-intro` 目录中, 或者 `twisted-intro` 位于Python的搜索目录中. 下面单独运行 `twistd`,你会看到"`fastpoetry`"是列出的插件之一,后面显示插件文件中定义的描述文字.
371 |
372 | 你同样会注意到 `twisted/plugins` 目录中出现了一个 `dropin.cache` 的新文件. 这个文件由 `twistd` 创建, 用来加速后续扫描插件的.
373 |
374 | 现在让我们获取一些关于插件的帮助信息:
375 | ```
376 | twistd fastpoetry --help
377 | ```
378 | 你可以看到关于 `fastpoetry` 插件选项的帮助性文字. 最后,运行这个插件:
379 | ```
380 | twistd fastpoetry --port 10000 --poem poetry/ecstasy.txt
381 | ```
382 | 这将以守护进程方式启动 `fastpoetry` 服务器. 与前面例子一样, 你会在当期文件夹看到 `twistd.pid` 和 `twistd.log` 文件. 测试完我们的服务器, 用一下命令关闭:
383 | ```
384 | kill `cat twistd.pid`
385 | ```
386 | 这就是如何制作Twisted插件的方法.
387 |
388 | ### 总结
389 |
390 | 在这个部分, 我们学习了将Twisted服务器转换到支持长时间运行的守护进程模式. 我们还涉及了Twisted日志系统以及如何使用 `twistd` 以守护进程模式启动一个Twisted应用程序, 即或者通过 `tac` 配置文件或者Twisted插件. 在第十七部分 我们将转向异步编程的更基本的主题和另外一种结构化Twisted回调函数的方法.
391 |
392 | ### 参考练习
393 |
394 | 1. 修正 `tac` 文件以在另外一个端口服务另外一首诗. 使用另外一个 `MultiService` 对象以保持每首诗的服务是分离的.
395 | 2. 创建一个新的 `tac` 文件来启动一个诗歌代理服务器.
396 | 3. 修正插件文件使其可接受第二个可选诗歌文件和服务端口.
397 | 4. 为诗歌代理服务器创建一个新的插件.
398 |
399 | ### 参考
400 |
401 | 本部分原作参见: dave @
402 |
403 | 本部分翻译内容参见luocheng @
404 |
--------------------------------------------------------------------------------
/zh/p17.md:
--------------------------------------------------------------------------------
1 | ### 简介
2 |
3 | 这部分我们将回到"回调"这个主题.我们将介绍另外一种写回调函数的方法,即在Twisted中使用 [generators](http://docs.python.org/tutorial/classes.html#generators). 我们将演示如何使用这种方法并且与使用"纯" `Deferreds` 进行对比. 最后, 我们将使用这种技术重写诗歌客户端. 但首先我们来回顾一下 `generators` 的工作原理,以便弄清楚它为何是创建回调的候选方法.
4 |
5 | ### 简要回顾生成器
6 |
7 | 你可能知道, 一个Python生成器是一个"可重启的函数",它是在函数体中用 `yield` 语句创建的. 这样做可以使这个函数变成一个"生成器函数",它返回一个"[iterator](http://docs.python.org/tutorial/classes.html#iterators)"可以用来以一系列步骤运行这个函数. 每次迭代循环都会重启这个函数,继续执行到下一个 `yield` 语句.
8 |
9 | 生成器(和迭代器)通常被用来代表以惰性方式创建的值序列. 看一下以下文件中的代码 [inline-callbacks/gen-1.py](https://github.com/jdavisp3/twisted-intro/blob/master/inline-callbacks/gen-1.py#L1):
10 | ```python
11 | def my_generator():
12 | print 'starting up'
13 | yield 1
14 | print "workin'"
15 | yield 2
16 | print "still workin'"
17 | yield 3
18 | print 'done'
19 |
20 | for n in my_generator():
21 | print n
22 | ```
23 | 这里我们用生成器创建了1,2,3序列. 如果你运行这些代码,会看到在生成器上做迭代时,生成器中的 `print` 与循环语句中的 `print` 语句交错出现.
24 |
25 | 以下自定义迭代器代码使上面的说法更加明显([inline-callbacks/gen-2.py](https://github.com/jdavisp3/twisted-intro/blob/master/inline-callbacks/gen-2.py#L1)):
26 | ```python
27 | def my_generator():
28 | print 'starting up'
29 | yield 1
30 | print "workin'"
31 | yield 2
32 | print "still workin'"
33 | yield 3
34 | print 'done'
35 |
36 | gen = my_generator()
37 |
38 | while True:
39 | try:
40 | n = gen.next()
41 | except StopIteration:
42 | break
43 | else:
44 | print n
45 | ```
46 | 把它视作一个序列,生成器仅仅是获取连续值的一个对象.但我们也可以以生成器本身的角度看问题:
47 |
48 | 1. 生成器函数在被循环调用之前并没有执行(使用 `next` 方法).
49 | 2. 一旦生成器开始运行,它将一直执行直到返回"循环"(使用 `yield`)
50 | 3. 当循环中运行其他代码时(如 `print` 语句),生成器则没有运行.
51 | 4. 当生成器运行时, 则循环没有运行(等待生成器返回前它被"阻滞"了).
52 | 5. 一旦生成器将控制交还到循环,再启动可能需要等待任意时间(其间任意量的代码可能被执行).
53 |
54 | 这与异步系统中的回调工作方式非常类似. 我们可以把 `while` 循环视作 `reactor`, 把生成器视作一系列由 `yield` 语句分隔的回调函数. 有趣的是, 所有的回调分享相同的局部变量名空间, 而且名空间在不同回调中保持一致.
55 |
56 | 进一步,你可以一次激活多个生成器(参考例子 [inline-callbacks/gen-3.py](https://github.com/jdavisp3/twisted-intro/blob/master/inline-callbacks/gen-3.py#L1)),使得它们的"回调"互相交错,就像在Twisted系统中独立运行的异步程序.
57 |
58 | 然而,这种方法还是有一些欠缺.回调不仅仅被 `reactor` 调用, 它还能接受信息.作为 `deferred` 链的一部分,回调要么接收Python值形式的一个结果,要么接收 `Failure` 形式的一个错误.
59 |
60 | 从Python2.5开始,生成器功能被扩展了.当你再次启动生成器时,可以给它发送信息,如 [inline-callbacks/gen-4.py](https://github.com/jdavisp3/twisted-intro/blob/master/inline-callbacks/gen-4.py#L1) 所示:
61 | ```python
62 | class Malfunction(Exception):
63 | pass
64 |
65 | def my_generator():
66 | print 'starting up'
67 |
68 | val = yield 1
69 | print 'got:', val
70 |
71 | val = yield 2
72 | print 'got:', val
73 |
74 | try:
75 | yield 3
76 | except Malfunction:
77 | print 'malfunction!'
78 |
79 | yield 4
80 |
81 | print 'done'
82 |
83 | gen = my_generator()
84 |
85 | print gen.next() # start the generator
86 | print gen.send(10) # send the value 10
87 | print gen.send(20) # send the value 20
88 | print gen.throw(Malfunction()) # raise an exception inside the generator
89 |
90 | try:
91 | gen.next()
92 | except StopIteration:
93 | pass
94 | ```
95 | 在Python2.5以后的版本中, `yield` 语句是一个计算值的表达式.重新启动生成器的代码可以使用 `send` 方法代替 `next` 决定它的值(如果使用 `next` 则值为 `None`), 而且你还可以在迭代器内部使用 `throw` 方法抛出任何异常. 是不是很酷?
96 |
97 | ### 内联回调
98 |
99 | 根据我们刚刚回顾的可以向生成器发送值或抛出异常的特性,可以设想它是像 `deferred` 中的一系列回调,即可以接收结果或错误. 每个回调被 `yield` 分隔,每一个 `yield` 表达式的值是下一个回调的结果(或者 `yield` 抛出异常表示错误).图35显示相应概念:
100 |
101 |
102 | 图35 作为回调序列的生成器
103 |
104 | 现在一系列回调以 `deferred` 方式被链接在一起,每个回调从它前面的回调接收结果.生成器很容易做到这一点——当再次启动生成器时,仅仅使用 `send` 发送上一次调用生成器的结果( `yield` 产生的值).但这看起来有点笨,既然生成器从开始就计算这个值,为什么还需要把它发送回来? 生成器可以将这个值储存在一个变量中供下一次使用. 因此这到底是为什么呢?
105 |
106 | 回忆一下我们在第十三节中所学, `deferred` 中的回调还可以返回 `deferred` 本身. 在这种情况下, 外层的 `deferred` 先暂停等待内层的 `deferred` 激发,接下来外层 `deferred` 链使用内层 `deferred` 的返回结果(或错误)激发后续的回调(或错误回调).
107 |
108 | 所以设想我们的生成器生成一个 `deferred` 对象而不是一个普通的Python值. 这时生成器会自动"暂停";生成器总是在每个 `yield` 语句后暂停直到被显式地重启.因而我们可以延迟它的重启直到 `deferred` 被激发, 届时我们会使用 `send` 方法发送值(如果 `deferred` 成功)或者抛出异常(如果 `deferred` 失败).这就使我们的生成器成为一个真正的异步回调序列,这正是 [twisted.internet.defer](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.1.0/twisted/internet/defer.py) 中 [inlineCallbacks](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.1.0/twisted/internet/defer.py#L973) 函数背后的概念.
109 |
110 |
111 | ### 进一步讨论内联回调
112 |
113 | 考虑以下例程, 位于 [inline-callbacks/inline-callbacks-1.py](https://github.com/jdavisp3/twisted-intro/blob/master/inline-callbacks/inline-callbacks-1.py#L1):
114 | ```python
115 | from twisted.internet.defer import inlineCallbacks, Deferred
116 |
117 | @inlineCallbacks
118 | def my_callbacks():
119 | from twisted.internet import reactor
120 |
121 | print 'first callback'
122 | result = yield 1 # yielded values that aren't deferred come right back
123 |
124 | print 'second callback got', result
125 | d = Deferred()
126 | reactor.callLater(5, d.callback, 2)
127 | result = yield d # yielded deferreds will pause the generator
128 |
129 | print 'third callback got', result # the result of the deferred
130 |
131 | d = Deferred()
132 | reactor.callLater(5, d.errback, Exception(3))
133 |
134 | try:
135 | yield d
136 | except Exception, e:
137 | result = e
138 |
139 | print 'fourth callback got', repr(result) # the exception from the deferred
140 |
141 | reactor.stop()
142 |
143 | from twisted.internet import reactor
144 | reactor.callWhenRunning(my_callbacks)
145 | reactor.run()
146 | ```
147 | 运行这个例子可以看到生成器运行到最后并终止了 `reactor`, 这个例子展示了 `inlineCallbacks` 函数的很多方面.
148 |
149 | 首先, `inlineCallbacks` 是一个修饰器,它总是修饰生成器函数,如那些使用 `yield` 语句的函数. `inlineCallbacks` 唯一的目的是将一个生成器按照上述策略转化为一系列异步回调.
150 |
151 | 第二,当我们调用一个用 `inlineCallbacks` 修饰的函数时,不需要自己调用 `send` 或 `throw` 方法.修饰符会帮助我们处理细节,并确保生成器运行到结束(假设它不抛出异常).
152 |
153 | 第三,如果我们从生成器生成一个非延迟值,它将以 `yield` 生成的值立即重启.
154 |
155 | 最后,如果我们从生成器生成一个 `deferred`,它不会重启除非此 `deferred` 被激发.如果 `deferred` 成功返回,则 `yield` 的结果就是 `deferred` 的结果.如果 `deferred` 失败了,则 `yield` 会抛出异常. 注意这个异常仅仅是一个普通的 `Exception` 对象,而不是 `Failure`,我们可以在 `yield` 外面用 `try/except` 块捕获它们.
156 |
157 | 在上面的例子中,我们仅用 `callLater` 在一小段时间之后去激发 `deferred`.虽然这是一种将非阻塞延迟放入回调链的实用方法,但通常我们会生成一个 `deferred`,它是被生成器中其他的异步操作(如 `get_poetry`)返回的.
158 |
159 | OK,现在我们知道了 `inlineCallbacks` 修饰的函数是如何运行的,但当你实际调用时会返回什么值呢?正如你认为的,将得到 `deferred`.由于不能确切地知道生成器何时停止(它可能生成一个或多个 `deferred`),装饰函数本身是异步的,所以 `deferred` 是一个合适的返回值.注意这个 返回的`deferred` 并不是生成器中 `yield` 生成的 `deferred`.相反,它在生成器完全结束(或抛出异常)后才被激发.
160 |
161 | 如果生成器抛出一个异常,那么返回的 `deferred` 将激发它的错误回调链,把异常包含在一个 `Failure` 中. 但是如果我们希望生成器返回一个正常值,必须使用 `defer.returnValue` 函数. 像普通 `return` 语句一样,它也会终止生成器(实际会抛出一个特殊异常).例子 [inline-callbacks/inline-callbacks-2.py](https://github.com/jdavisp3/twisted-intro/blob/master/inline-callbacks/inline-callbacks-2.py#L1) 说明了这两种可能.
162 |
163 | ### 客户端7.0
164 |
165 | 让我们在新版本的诗歌客户端中加入 `inlineCallbacks`,你可以在 [twisted-client-7/get-poetry.py](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-7/get-poetry.py#L1) 中查看源代码.也许你需要与客户端6.0—— [twisted-client-6/get-poetry.py](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-6/get-poetry.py#L151) 进行对比,它们的不同位于 [poetry_main](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-7/get-poetry.py#L151):
166 | ```python
167 | def poetry_main():
168 | addresses = parse_args()
169 |
170 | xform_addr = addresses.pop(0)
171 |
172 | proxy = TransformProxy(*xform_addr)
173 |
174 | from twisted.internet import reactor
175 |
176 | results = []
177 |
178 | @defer.inlineCallbacks
179 | def get_transformed_poem(host, port):
180 | try:
181 | poem = yield get_poetry(host, port)
182 | except Exception, e:
183 | print >>sys.stderr, 'The poem download failed:', e
184 | raise
185 |
186 | try:
187 | poem = yield proxy.xform('cummingsify', poem)
188 | except Exception:
189 | print >>sys.stderr, 'Cummingsify failed!'
190 |
191 | defer.returnValue(poem)
192 |
193 | def got_poem(poem):
194 | print poem
195 |
196 | def poem_done(_):
197 | results.append(_)
198 | if len(results) == len(addresses):
199 | reactor.stop()
200 |
201 | for address in addresses:
202 | host, port = address
203 | d = get_transformed_poem(host, port)
204 | d.addCallbacks(got_poem)
205 | d.addBoth(poem_done)
206 |
207 | reactor.run()
208 | ```
209 | 在这个新版本里, `inlineCallbacks` 生成函数 `get_transformed_poem` 负责取回诗歌并且进行转换(通过转换服务).由于这两个操作都是异步的,我们每次生成一个 `deferred` 并且隐式地等待结果.与客户端6.0一样,如果变换失败则返回原始诗歌.我们可以使用 `try/except` 语句捕获生成器中的异步错误.
210 |
211 | 我们以先前的方式测试新版客户端. 首先启动一个变换服务:
212 | ```
213 | python twisted-server-1/transformedpoetry.py --port 10001
214 | ```
215 | 然后启动两个诗歌服务器:
216 | ```
217 | python twisted-server-1/fastpoetry.py --port 10002 poetry/fascination.txt
218 | python twisted-server-1/fastpoetry.py --port 10003 poetry/science.txt
219 | ```
220 | 现在可以运行新的客户端:
221 | ```
222 | python twisted-client-7/get-poetry.py 10001 10002 10003
223 | ```
224 | 试试关闭一个或多个服务器,看一看客户端如何捕获错误.
225 |
226 | ### 讨论
227 |
228 | 就像 `Deferred` 对象, `inlineCallbacks` 函数给我们一种组织异步回调的新方式.使用 `deferred`, `inllineCallbacks` 并不会改变游戏规则.我们的回调仍然一次调用一个回调,它们仍然被 `reactor` 调用.我们可以通过打印内联回调的回溯堆栈信息来证实这一点,参见脚本 [inline-callbacks/inline-callbacks-tb.py](https://github.com/jdavisp3/twisted-intro/blob/master/inline-callbacks/inline-callbacks-tb.py#L1).运行此代码你将首先获得一个关于 `reactor.run()` 的回溯,然后是许多帮助函数信息,最后是我们的回调.
229 |
230 | 图29解释了当 `deferred` 中一个回调返回另一个 `deferred` 时会发生什么,我们调整它来展示当一个 `inlineCallbacks` 生成器生成一个 `deferred` 时会发生什么,参考图36:
231 |
232 |
233 | 图36 inlineCallbacks 函数中的控制流
234 |
235 | 同样的图对两种情况都适用,因为它们表示的想法都是一样的 —— 一个异步操作正在等待另一个操作.
236 |
237 | 由于 `inlineCallbacks` 和 `deferred` 解决许多相同的问题,在它们之间如何选择呢?下面列出一些 `inlineCallbacks` 的潜在优势.
238 |
239 | + 由于回调共享同一个命名空间,因此没有必要传递额外状态.
240 | + 回调的顺序很容易看到,因为它总是从上到下执行.
241 | + 节省了每个回调函数的声明和隐式控制流,通常可以减少输入工作量.
242 | + 可以使用熟悉的 `try/except` 语句处理错误.
243 |
244 | 当然也存在一些缺陷:
245 |
246 | + 生成器中的回调不能被单独调用,这使代码重用比较困难.而构造 `deferred` 的代码则能够以任意顺序自由地添加任何回调.
247 | + 生成器的紧致性可能混淆一个事实,其实异步回调非常晦涩.尽管生成器看起来像一个普通的函数序列,但是它的行为却非常不一样. `inlineCallbacks` 函数不是一种避免学习异步编程模型的方式.
248 |
249 | 就像任何技术,实践将积累出必要的经验,帮你做出明智选择.
250 |
251 | ### 总结
252 |
253 | 在这个部分,我们学习了 `inlineCallbacks` 装饰器以及它怎样使我们能够以Python生成器的形式表达一系列异步回调.
254 |
255 | 在第十八节中,我们将学习一种管理 **一组** "并行"异步操作的技术.
256 |
257 | ### 参考练习
258 |
259 | 1. 为什么 `inlineCallbacks` 函数是复数(形式)?
260 | 2. 研究 [inlineCallbacks](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.1.0/twisted/internet/defer.py#973) 的实现以及它们帮助函数 [_inlineCallbacks](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.1.0/twisted/internet/defer.py#L874). 并思考短语"魔鬼在细节处".
261 | 3. 有N个 `yield` 语句的生成器中包含多少个回调,假设其中没有循环或者 `if` 语句?
262 | 4. 诗歌客户端7.0可能同时运行三个生成器.概念上,它们之间有多少种不同的交错方式?考虑诗歌客户端和 `inlineCallbacks` 的实现,你认为实际有多少种可能?
263 | 5. 把客户端7.0中的 `got_poem` 放入到生成器中.
264 | 6. 把 `poem_done` 回调放入生成器.小心!确保处理所有失败情况以便无论怎样 `reactor` 都会关闭.与使用 `deferred` 关闭 `reactor` 对比代码有何不同?
265 | 7. 一个在 `while` 循环中使用 `yield` 语句的生成器代表一个概念上的无限序列.那么同样的装饰有 `inlineCallbacks` 的生成器又代表什么呢?
266 |
267 | ### 参考
268 |
269 | 本部分原作参见: dave @
270 |
271 | 本部分翻译内容参见luocheng @
272 |
--------------------------------------------------------------------------------
/zh/p18.md:
--------------------------------------------------------------------------------
1 | ### 简介
2 |
3 | 在上一个部分,我们学习了使用生成器构造顺序异步回调的新方法， 加上 `deferreds`,我们现在有两种将异步操作链接在一起的方法.
4 |
5 | 但是有时我们需要"并行"的运行一组异步操作.由于Twisted是单线程的,它实际并不会并发运行,但我们希望使用异步I/O在一组任务上尽可能快的工作.以我们的诗歌客户端为例,它从多个服务器同时下载诗歌,而不是一个接一个的方式.这就是使用Twisted下载诗歌的全部细节.
6 |
7 | 因此所有诗歌客户端需要解决这样一个问题:怎样得知你启动的所有异步操作都已经完成?目前我们通过将结果汇总到一个列表(如客户端 7.0中的 [结果](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-7/get-poetry.py#L160) 列表)并检查这个列表的长度来解决这个问题.除了收集成功的结果,我们还必须小心地对待失败,否则一个失败将使程序以为还有工作需要做而进入死循环.
8 |
9 | 正如你所料,Twisted包含一个抽象层可以用来解决这个问题,我们来看一看.
10 |
11 | ### DeferredList
12 |
13 | `DeferredList` 类使我们可以将一个 `defered` 对象列表视为一个 `defered` 对象.通过这种方法我们启动一族异步操作并且在它们全部完成后获得通知(无论它们成功或者失败).让我们看一些例子.
14 |
15 | 在 [deferred-list/deferred-list-1.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-list/deferred-list-1.py#L1) 中,可以找到如下代码:
16 | ```python
17 | from twisted.internet import defer
18 |
19 | def got_results(res):
20 | print 'We got:', res
21 |
22 | print 'Empty List.'
23 | d = defer.DeferredList([])
24 | print 'Adding Callback.'
25 | d.addCallback(got_results)
26 | ```
27 | 如果运行它,将得到如下输出:
28 | ```
29 | Empty List.
30 | Adding Callback.
31 | We got: []
32 | ```
33 | 注意以下几点:
34 |
35 | + `DeferredList` 由一个Python列表初始化创建而成.在这种情况下,列表是空的,但我们很快将看到列表的元素必须是 `Deferred` 对象.
36 | + `DeferredList` 本身是一个 `deferred` (它继承 `Deferred`).这意味着你可以像对待普通 `deferred` 一样向其添加回调和错误回调.
37 | + 在以上例子中,回调被添加时立即激发,所以 `DeferredList` 也必须立即激发.我们一会儿再讨论.
38 | + `deferred` 列表的结果本身也是一个列表(空).
39 |
40 | 下面看一下 [deferred-list/deferred-list-2.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-list/deferred-list-2.py#L1):
41 | ```python
42 | from twisted.internet import defer
43 |
44 | def got_results(res):
45 | print 'We got:', res
46 |
47 | print 'One Deferred.'
48 | d1 = defer.Deferred()
49 | d = defer.DeferredList([d1])
50 | print 'Adding Callback.'
51 | d.addCallback(got_results)
52 | print 'Firing d1.'
53 | d1.callback('d1 result')
54 | ```
55 | 现在我们创建了包含一个 `deferred` 元素的 `DeferredList` 列表,得到如下输出:
56 | ```
57 | One Deferred.
58 | Adding Callback.
59 | Firing d1.
60 | We got: [(True, 'd1 result')]
61 | ```
62 | 注意以下几点:
63 |
64 | + 这次 `DeferredList` 没有激发它的回调,直到我们激发列表中的 `deferred`.
65 | + 结果同样是一个列表,但这次包含一个元素.
66 | + 这个元素是一个元组,它的第二个值是列表中 `deferred` 的结果.
67 |
68 | 让我们向列表添加两个 `deferreds` ([deferred-list/deferred-list-3.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-list/deferred-list-1.py#L3)):
69 | ```python
70 | from twisted.internet import defer
71 |
72 | def got_results(res):
73 | print 'We got:', res
74 |
75 | print 'Two Deferreds.'
76 | d1 = defer.Deferred()
77 | d2 = defer.Deferred()
78 | d = defer.DeferredList([d1, d2])
79 | print 'Adding Callback.'
80 | d.addCallback(got_results)
81 | print 'Firing d1.'
82 | d1.callback('d1 result')
83 | print 'Firing d2.'
84 | d2.callback('d2 result')
85 | ```
86 | 得到如下输出:
87 | ```
88 | Two Deferreds.
89 | Adding Callback.
90 | Firing d1.
91 | Firing d2.
92 | We got: [(True, 'd1 result'), (True, 'd2 result')]
93 | ```
94 | 现在 `DeferredList` 的结果非常清晰,至少以我们的使用方式,它是一个列表,元素个数与传入构造器的 `deferred` 列表元素个数相同. 而且结果列表的元素包含原始的 `deferreds` 结果信息,至少当这些 `deferred` 成功返回.这意味着 `DeferredList` 本身并不激发直到所有的原始列表中的 `deferreds` 都被激发. 而且以一个空列表创建的 `DeferredList` 会立即激发,因为它不需要等待任何 `deferreds`.
95 |
96 | 那么最终结果列表中的元素顺序如何? 考虑以下代码( [deferred-list/deferred-list-4.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-list/deferred-list-4.py#L1)):
97 | ```python
98 | from twisted.internet import defer
99 |
100 | def got_results(res):
101 | print 'We got:', res
102 |
103 | print 'Two Deferreds.'
104 | d1 = defer.Deferred()
105 | d2 = defer.Deferred()
106 | d = defer.DeferredList([d1, d2])
107 | print 'Adding Callback.'
108 | d.addCallback(got_results)
109 | print 'Firing d2.'
110 | d2.callback('d2 result')
111 | print 'Firing d1.'
112 | d1.callback('d1 result')
113 | ```
114 | 这里我们先激发 `d2` 然后再激发 `d1`,注意构造参数中的 `deferred` 列表里 `d1`, `d2` 仍是原先的顺序.输出结果如下:
115 | ```
116 | Two Deferreds.
117 | Adding Callback.
118 | Firing d2.
119 | Firing d1.
120 | We got: [(True, 'd1 result'), (True, 'd2 result')]
121 | ```
122 | 输出列表中结果的顺序与原始 `deferred` 列表顺序相对应,而不是 `deferred` 碰巧被激发的顺序.这一点非常好,因为我们可以很容易地将每个结果与生成它的相应的操作联系在一起(如哪首诗来自哪个服务器).
123 |
124 | 好了,那如果列表中一个或多个 `deferreds` 失败了怎么办呢? 上面结果中的 `True` 有什么用? 再看一个例子([deferred-list/deferred-list-5.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-list/deferred-list-5.py#L1)):
125 | ```python
126 | from twisted.internet import defer
127 |
128 | def got_results(res):
129 | print 'We got:', res
130 |
131 | d1 = defer.Deferred()
132 | d2 = defer.Deferred()
133 | d = defer.DeferredList([d1, d2], consumeErrors=True)
134 | d.addCallback(got_results)
135 | print 'Firing d1.'
136 | d1.callback('d1 result')
137 | print 'Firing d2 with errback.'
138 | d2.errback(Exception('d2 failure'))
139 | ```
140 | 现在我们以正常结果激发 `d1`,以错误激发 `d2`.先暂时忽略 `consumeErrors` 选项,稍候介绍.这里是输出结果:
141 | ```
142 | Firing d1.
143 | Firing d2 with errback.
144 | We got: [(True, 'd1 result'), (False, >)]
145 | ```
146 | 这次对应 `d2` 的元组在第二个位置出现了一个 `Failure`,并且第一个位置是 `False`.至此 `DeferredList` 的工作原理非常清晰(但继续浏览以下讨论):
147 |
148 | + `DeferredList` 是以一个 `deferred` 对象列表创建的.
149 | + `DeferredList` 本身是一个 `deferred`,它返回的结果是一个列表,长度与 `deferred` 列表相同.
150 | + 当原始列表中所有 `deferred` 被激发后, `DeferredList` 将会被激发.
151 | + 结果列表中的每个元素以相同顺序对应原始列表中相应的 `deferred`.如果某个 `deferred` 成功返回,相应元素是(`True`,result),如果失败则为(`False`,failure).
152 | + `DeferredList` 不会失败,因为无论每个 `deferred` 的返回结果是什么都会被集总到结果列表中(同样,请看下面讨论).
153 |
154 | 现在让我们讨论一下被传入 `DeferredList` 的 `consumeErrors` 选项,如果我们运行以上相同代码而不传入此选项([deferred-list/deferred-list-6.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-list/deferred-list-6.py#L1)),则得到以下输出:
155 | ```
156 | Firing d1.
157 | Firing d2 with errback.
158 | We got: [(True, 'd1 result'), (False, >twisted.python.failure.Failure >type 'exceptions.Exception'<<)]
159 | Unhandled error in Deferred:
160 | Traceback (most recent call last):
161 | Failure: exceptions.Exception: d2 failure
162 | ```
163 | 如果你还记得,"Unhandled error in Deferred"消息是在 `deferred` 垃圾回收时被生成的,而且它表示最后一个回调失败了.这个消息告诉我们并没有完全捕获潜在的异步错误.在我们例子中,它是从哪里来的呢? 很明显不是来自 `DeferredList`,因为它已经成功返回了.所以它一定是来自 `d2`.
164 |
165 | `DeferredList` 需要知道它所监视的 `deferred` 何时激发. `DeferredList` 以通常的方式向每个 `deferred` 添加一个回调和错误回调. 默认地,这个回调(或错误)返回原始结果(或错误)在将它们放入最终结果列表之后.由于错误回调返回原始 `failure` 后将触发下一个错误回调, `d2` 在它被激发后仍然保持失败状态.
166 |
167 | 但是如果我们将 `consumeErrors=True` 传递给 `DeferredList`, 它将向每个 `deferred` 添加返回 `None` 的错误回调, 即"消耗"掉这个错误并且取消警告信息. 我们同样可以向 `d2` 添加自己的错误回调来处理错误,如 [deferred-list/deferred-list-7.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-list/deferred-list-7.py#L1).
168 |
169 | ### 客户端 8.0
170 |
171 | 获取诗歌客户端8.0发布啦！客户端使用 `DeferredList` 去发现所有诗歌何时完成(或失败).新版客户端位于 [twisted-client-8/get-poetry.py](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-8/get-poetry.py#L1). 同样,唯一的变化在于 [poetry_main](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-8/get-poetry.py#L151), 我们来看一下重要的变化:
172 | ```python
173 | ...
174 | ds = []
175 |
176 | for (host, port) in addresses:
177 | d = get_transformed_poem(host, port)
178 | d.addCallbacks(got_poem)
179 | ds.append(d)
180 |
181 | dlist = defer.DeferredList(ds, consumeErrors=True)
182 | dlist.addCallback(lambda res : reactor.stop())
183 | ```
184 | 你可以与 [客户端 7.0](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-7/get-poetry.py#L180) 中的相应部分比较.
185 |
186 | 在客户端 8.0中,我们不需要 `poem_done` 回调和 `results` 列表.相反,我们把每个从 `get_transformed_poem` 返回的 `deferred` 放入 `ds` 列表,之后创建一个 `DeferredList`.由于 `DeferredList` 不会在所有诗歌完成或失败之前激发,我们仅仅向 `DeferredList` 添加一个回调以便关闭 `reactor`. 在我们这个情况中,没有使用 `DeferredList` 返回的结果,我们仅仅需要知道所有事情何时结束.仅此而已!
187 |
188 | ### 讨论
189 |
190 | 可视化 `DeferredList` 的工作方式:
191 |
192 |
193 | 图33 DeferredList 的结果
194 |
195 | 非常简单,真的. 还有一些关于 `DeferredList` 的选项我们没有涉及,以及那些改变我们以上所描述行为的选项.我们在参考练习中把这些留给读者自己探索.
196 |
197 | 在第十九节中我们将进一步介绍 `Deferred` 类, 包括 Twisted 10.1.0 提出的最新特性.
198 |
199 | ### 参考练习
200 |
201 | 1. 阅读 `DeferredList` 的源代码.
202 | 2. 修改 `deferred-list` 中的例子去实现可选的构造器参数 `fireOnOneCallback` 和 `fireOnOneErrback`. 实现你将用其中一个(或两个都使用)的情景.
203 | 3. 你可以使用 `DeferredLists` 列表创建一个 `DeferredList` 吗? 如果是这样,结果将是什么?
204 | 4. 修改客户端8.0在所有诗歌完成下载前不打印任意信息. 这次你将使用 `DeferredList` 的结果.
205 | 5. 定义 `DeferredDict` 的句法并且实现它.
206 |
207 | ### 参考
208 |
209 | 本部分原作参见: dave @
210 |
211 | 本部分翻译内容参见luocheng @
212 |
--------------------------------------------------------------------------------
/zh/p19.md:
--------------------------------------------------------------------------------
1 | ### 简介
2 |
3 | Twisted是一个正在进展的项目,它的开发者会定期添加新的特性并且扩展旧的特性.
4 |
5 | 随着Twisted 10.1.0发布,开发者向 `Deferred` 类添加了一个新的特性—— `cancellation` ——这正是我们今天要研究的.
6 |
7 | 异步编程将请求和响应解耦了,如此又带来一个新的可能性:在请求结果和返回结果之间,你可能决定不再需要这个结果了.考虑一下 第十四节 中的诗歌代理服务器.下面展示代理如何工作的,至少对于诗歌的第一次请求:
8 |
9 | 1. 一个对诗歌的请求来了.
10 | 2. 这个代理联系实际服务器以得到这首诗
11 | 3. 一旦这首诗完成,将其发送给原发出请求的客户端
12 |
13 | 看起来非常完美,但是如果客户端在获得诗歌之前断开了链接怎么办?也许它们先前请求 [Paradise Lost](http://www.online-literature.com/milton/paradiselost/)的全部内容,随后它们决定实际想要的是 [Kojo](http://www.toyomasu.com/haiku/#kojo)的俳句.我们的代理还在傻傻的处理前面的下载请求,而且那个缓慢的下载服务器还要等好一会.最好的策略便是关闭连接,让下载服务器回去顺觉.
14 |
15 | 回忆一下 图15 展示了同步程序控制流的概念.在那张图中我们可以看到函数调用自上而下,异常也是自下而上.如果我们希望取消一个同步调用(这仅是假设),控制流的传递方向与函数调用的方向一致,都是从高层传向底层,如图38所示:
16 |
17 |
18 | 图38 同步程序流,含假想取消操作
19 |
20 | 当然,在同步程序中这是不可能的,因为高层的代码在底层操作结束前没有恢复运行,自然也就没有什么可取消的.但是在异步程序中,高层代码在底层代码完成前具有控制权,至少具有在底层代码完成之前取消它的请求的可能性.
21 |
22 | 在Twisted程序中,底层请求被包含在一个 `Deferred` 对象中,你可以将其想象为一个外部异步操作的"句柄". `deferred` 中正常的信息流是向下的,从底层代码到高层代码,与同步程序中返回的信息流方向一致.从Twisted 10.1.0开始,高层代码可以反向发送信息 —— 它可以告诉底层代码它不再需要其结果了.如图39:
23 |
24 |
25 | 图39 deferred 中的信息流,包含取消
26 |
27 | ### 取消 Deferreds
28 |
29 | 让我们看一些例程,来了解下取消 `deferreds` 的实际工作原理.注意为了运行这些列子以及本部分中的其他代码,你需要安装Twisted 10.1.0或更高 [版本](http://twistedmatrix.com/trac/wiki/Downloads) 考虑 [deferred-cancel/defer-cancel-1.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-1.py#L1)
30 | ```python
31 | from twisted.internet import defer
32 |
33 | def callback(res):
34 | print 'callback got:', res
35 |
36 | d = defer.Deferred()
37 | d.addCallback(callback)
38 | d.cancel()
39 | print 'done'
40 | ```
41 | 伴随着新的取消特性, `Deferred` 类添加了一个名为 `cancel` 的新方法.上面代码创建了一个新的 `deferred`,添加了一个回调,然后取消了这个 `deferred` 而没有激发它.输出如下:
42 | ```
43 | done
44 | Unhandled error in Deferred:
45 | Traceback (most recent call last):
46 | Failure: twisted.internet.defer.CancelledError:
47 | ```
48 | OK,取消一个 `deferred` 看起来像使错误回调链运行,常规的回调根本没有被调用.同样注意到这个错误是: `twisted.internet.defer.CancelledError`,一个意味着 `deferred` 被取消的个性化异常(但请继续阅读).让我们添加一个错误回调,如 [deferred-cancel/defer-cancel-2.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-2.py#L1>`_
49 | ```python
50 | from twisted.internet import defer
51 |
52 | def callback(res):
53 | print 'callback got:', res
54 |
55 | def errback(err):
56 | print 'errback got:', err
57 |
58 | d = defer.Deferred()
59 | d.addCallbacks(callback, errback)
60 | d.cancel()
61 | print 'done'
62 | ```
63 | 得到以下输出:
64 | ```
65 | errback got: [Failure instance: Traceback (failure with no frames):
66 | : ]
67 | done
68 | ```
69 | 所以我们可以'捕获'从 `cancel` 产生的错误回调,就像其他 `deferred` 错误一样.
70 |
71 | OK,让我们试试激发 `deferred` 然后取消它,如 [deferred-cancel/defer-cancel-3.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-3.py#L1)
72 | ```python
73 | from twisted.internet import defer
74 |
75 | def callback(res):
76 | print 'callback got:', res
77 |
78 | def errback(err):
79 | print 'errback got:', err
80 |
81 | d = defer.Deferred()
82 | d.addCallbacks(callback, errback)
83 | d.callback('result')
84 | d.cancel()
85 | print 'done'
86 | ```
87 | 这里我们用常规 `callback` 方法激发 `deferred`,之后取消它.输出结果如下:
88 | ```
89 | callback got: result
90 | done
91 | ```
92 | 我们的回调被调用(正如我们所预期的)之后程序正常结束,就像 `cancel` 根本没有被调用.所以取消一个已经被激发的 `deferred` 没有任何效果(但请继续阅读!).
93 |
94 | 如果我们在取消 `deferred` 之后激发它会怎样?参看 [deferred-cancel/defer-cancel-4.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-4.py#L1)
95 | ```python
96 | from twisted.internet import defer
97 |
98 | def callback(res):
99 | print 'callback got:', res
100 |
101 | def errback(err):
102 | print 'errback got:', err
103 |
104 | d = defer.Deferred()
105 | d.addCallbacks(callback, errback)
106 | d.cancel()
107 | d.callback('result')
108 | print 'done'
109 | ```
110 | 这种情况的输出如下:
111 | ```
112 | errback got: [Failure instance: Traceback (failure with no frames):
113 | : ]
114 | done
115 | ```
116 | 有意思！与第二个例子的输出一样,当时没有激发 `deferred`.所以如果 `deferred` 被取消了,再激发它没有效果.但是为什么 `d.callback('result')` 没有产生错误,考虑到不能激发 `deferred` 大于一次,错误回调链为何没有运行?
117 |
118 | 再次考虑 图39，用结果或失败激发一个 `deferred` 是底层代码的工作,然而取消 `deferred` 是高层代码的行为.激发 `deferred` 意味着"这是你的结果",然而取消 `deferred` 意味着"我不再想要这个结果了".同时记住 `cancel` 是一个新特性,所以大部分现有的Twisted代码并没有处理取消的操作.但是Twisted的开发者使我们取消 `deferred` 的想法变得有可能,甚至包括那些在Twisted 10.1.0之前写的代码.
119 |
120 | 为了实现以上想法, `cancel` 方法实际上做两件事:
121 |
122 | 1. 告诉 `Deferred` 对象你不想要那个结果,如果它还没有返回(如, `deferred` 没有被激发),忽略后续任何回调或错误回调的调用.
123 | 2. 同时,可选地,告诉正在产生结果的底层代码需要采取何种步骤来取消操作.
124 |
125 | 由于旧版本的Twisted代码会上前去激发任何已经被取消的 `deferred`, 步骤1 确保我们的程序不会垮掉如果我们取消一个旧有库中的 `deferred`.
126 |
127 | 这意味着我们可以随心所欲地取消一个 `deferred`,同时可以确定不会得到结果如果它还没有到来(甚至那些 **将要** 到来的).但是取消 `deferred` 可能并没有取消异步操作.终止一个异步操作需要一个上下文的具体行动.你可能需要关闭网络连接,回滚数据库事务,结束子进程,等等.由于 `deferred` 仅仅是一般目的的回调组织者,它怎么知道具体要做什么当你取消它时?或者,换种说法,它怎样将 `cancel` 请求传递给首先已经创建和返回了 `deferred` 的底层代码? 和我一起说:
128 | ```
129 | I know, with a callback!
130 | ```
131 |
132 | ### 本质上取消 Deferreds
133 |
134 | 好吧,首先看一下 [deferred-cancel/defer-cancel-5.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-5.py#L1)
135 | ```python
136 | from twisted.internet import defer
137 |
138 | def canceller(d):
139 | print "I need to cancel this deferred:", d
140 |
141 | def callback(res):
142 | print 'callback got:', res
143 |
144 | def errback(err):
145 | print 'errback got:', err
146 |
147 | d = defer.Deferred(canceller) # created by lower-level code
148 | d.addCallbacks(callback, errback) # added by higher-level code
149 | d.cancel()
150 | print 'done'
151 | ```
152 | 这个例子基本上跟第二个例子相同,除了有第三个回调(`canceller`).这个回调是我们在创建 `Deferred` 的时候传递给它的,不是之后添加的.这个回调负责执行终止异步操作时所需的上下文相关的具体操作(当然,仅当 `deferred` 被实际取消). `canceller` 回调是返回 `deferred` 的底层代码的必要部分,不是接收 `deferred` 的高层代码为其自己添加的回调和错误回调.
153 |
154 | 运行这个例子将产生如下输出:
155 | ```
156 | I need to cancel this deferred:
157 | errback got: [Failure instance: Traceback (failure with no frames):
158 | : ]
159 | done
160 | ```
161 | 正如你所看到, 不需要返回结果的 `deferred` 被传递给 `canceller` 回调.在这里我们可以做任何需要做的事情以便彻底终止异步操作.注意 `canceller` 在错误回调链激发前被调用.其实我们可以在取消回调中选择使用任何结果或错误自己激发 `deferred` (这样就会抢占掉（preempting ） `CancelledError` 失败).这两种情况在 [deferred-cancel/defer-cancel-6.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-6.py#L1) 和 [deferred-cancel/defer-cancel-7.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-7.py#L1)中进行了说明.
162 |
163 | 在激发 `reactor` 之前先做一个简单的测试.我们将使用 `canceller` 回调创建一个 `deferred`,正常的激发它,之后取消它.你可以在 [deferred-cancel/defer-cancel-8.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-8.py#L1)中看到代码.通过检查那个脚本的输出,你将看到取消一个被激发的 `deferred` 不会调用 `canceller` 回调.这正是我们所要的,因为没什么可取消的.
164 |
165 | 我们目前看到的例子都没有实际的异步操作. 让我们构造一个调用异步操作的简单程序,之后我们将指出如何使那个操作可取消.参见代码 [deferred-cancel/defer-cancel-9.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-9.py#L1)
166 | ```python
167 | from twisted.internet.defer import Deferred
168 |
169 | def send_poem(d):
170 | print 'Sending poem'
171 | d.callback('Once upon a midnight dreary')
172 |
173 | def get_poem():
174 | """Return a poem 5 seconds later."""
175 | from twisted.internet import reactor
176 | d = Deferred()
177 | reactor.callLater(5, send_poem, d)
178 | return d
179 |
180 | def got_poem(poem):
181 | print 'I got a poem:', poem
182 |
183 | def poem_error(err):
184 | print 'get_poem failed:', err
185 |
186 | def main():
187 | from twisted.internet import reactor
188 | reactor.callLater(10, reactor.stop) # stop the reactor in 10 seconds
189 | d = get_poem()
190 | d.addCallbacks(got_poem, poem_error)
191 | reactor.run()
192 | main()
193 | ```
194 | 这个例子中包含了一个 `get_poem` 函数,它使用 `reactor` 的 `callLater` 方法在被调用5秒钟后异步地返回一首诗.主函数调用 `get_poem`,添加一个回调/错误回调对,之后启动 `reactor`.我们(同样使用 `callLater`)安排 `reactor` 在10秒钟之后停止.通常我们向 `deferred` 添加一个回调来实现,但你很快就会知道我们为何这样做.
195 |
196 | 运行程序(适当延迟后)产生如下输出:
197 | ```
198 | Sending poem
199 | I got a poem: Once upon a midnight dreary
200 | ```
201 | 10秒钟后程序终止.现在来试试在诗歌被发送前取消 `deferred`.只需加入以下代码在2秒钟后取消(在5秒钟延迟发送诗歌之前):
202 | ```
203 | reactor.callLater(2, d.cancel) # cancel after 2 seconds
204 | ```
205 | 完整的例子参见 [deferred-cancel/defer-cancel-10.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-10.py#L1)这将产生如下输出:
206 | ```
207 | get_poem failed: [Failure instance: Traceback (failure with no frames):
208 | : ]
209 | Sending poem
210 | ```
211 | 这个例子清晰地展示了取消一个 `deferred` 并没有取消它背后的异步请求.2秒钟后我们看到了错误回调输出,打印出如我们所料的 `CancelledError` 错误.但是5秒钟后我们看到了 `send_poem` 的输出(但是这个 `deferred` 上的回调并没有激发).
212 |
213 | 这时我们与 [deferred-cancel/defer-cancel-4.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-4.py#L1)的情况一样."取消" `deferred` 仅仅是使最终结果被忽略,但实际上并没有终止这个操作.正如我们上面所学,为了得到一个真正可取消的 `deferred`,必须在它被创建时添加一个 `cancel` 回调.
214 |
215 | 那么这个新的回调需要做什么呢? 参考一下关于 `callLater` 方法的 [文档](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.1.0/twisted/internet/interfaces.py#L556) 它的返回值是另一个实现了 `IDelayedCall` 的对象,用 `cancel` 方法我们可以阻止延迟的调用被执行.
216 |
217 | 这非常简单,更新后的代码参见 [deferred-cancel/defer-cancel-11.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-11.py#L1)所有相关变化都在 `get_poem` 函数中:
218 | ```python
219 | def get_poem():
220 | """Return a poem 5 seconds later."""
221 |
222 | def canceler(d):
223 | # They don't want the poem anymore, so cancel the delayed call
224 | delayed_call.cancel()
225 |
226 | # At this point we have three choices:
227 | # 1. Do nothing, and the deferred will fire the errback
228 | # chain with CancelledError.
229 | # 2. Fire the errback chain with a different error.
230 | # 3. Fire the callback chain with an alternative result.
231 |
232 | d = Deferred(canceler)
233 |
234 | from twisted.internet import reactor
235 | delayed_call = reactor.callLater(5, send_poem, d)
236 |
237 | return d
238 | ```
239 | 在这个新版本中,我们保存 `callLater` 的返回值以便能够在 `cancel` 回调中使用. `cancel` 回调的唯一工作是调用 `delayed_call.cancel()`. 但是正如之前讨论的,我们可以选择激发自定义的 `deferred`. 最新版本的程序产生如下输出:
240 | ```
241 | get_poem failed: [Failure instance: Traceback (failure with no frames):
242 | : ]
243 | ```
244 | 正如你看到的, `deferred` 被取消了并且异步操作被真正地终止了(我们看不到 `send_poem` 的输出了).
245 |
246 | ### 诗歌代理 3.0
247 |
248 | 正如在简介中所讨论,诗歌代理服务器是实现取消的很好的候选者,因为这可以让我们取消诗歌下载如果事实证明没有人想要它(如客户端已经在我们发送诗歌前关闭了连接).版本 3.0的代理位于 [twisted-server-4/poetry-proxy.py](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-4/poetry-proxy.py#L1)实现了 `deferred` 取消. 变化首先位于 [PoetryProxyProtocol](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-4/poetry-proxy.py#L52)
249 | ```python
250 | class PoetryProxyProtocol(Protocol):
251 |
252 | def connectionMade(self):
253 | self.deferred = self.factory.service.get_poem()
254 | self.deferred.addCallback(self.transport.write)
255 | self.deferred.addBoth(lambda r: self.transport.loseConnection())
256 |
257 | def connectionLost(self, reason):
258 | if self.deferred is not None:
259 | deferred, self.deferred = self.deferred, None
260 | deferred.cancel() # cancel the deferred if it hasn't fired
261 | ```
262 | 你可以与 [旧版本](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-2/poetry-proxy.py#L52)对比一下.两个主要的变化是:
263 |
264 | 1. 保存我们从 `get_poem` 得到的 `deferred`,以便之后在需要时取消它.
265 | 2. 当连接关闭时取消 `deferred`.注意当我们实际得到诗歌之后(链接最终肯定要关闭)，这个操作同样会取消 `deferred`,但正如前例所发现的,取消一个被激发的 `deferred` 不会有任何效果.
266 |
267 | 现在我们需要确保取消 `deferred` 将实际终止诗歌的下载. 所以我们需要改变 [ProxyService](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-4/poetry-proxy.py#L105)
268 | ```python
269 | class ProxyService(object):
270 |
271 | poem = None # the cached poem
272 |
273 | def __init__(self, host, port):
274 | self.host = host
275 | self.port = port
276 |
277 | def get_poem(self):
278 | if self.poem is not None:
279 | print 'Using cached poem.'
280 | # return an already-fired deferred
281 | return succeed(self.poem)
282 |
283 | def canceler(d):
284 | print 'Canceling poem download.'
285 | factory.deferred = None
286 | connector.disconnect()
287 |
288 | print 'Fetching poem from server.'
289 | deferred = Deferred(canceler)
290 | deferred.addCallback(self.set_poem)
291 | factory = PoetryClientFactory(deferred)
292 | from twisted.internet import reactor
293 | connector = reactor.connectTCP(self.host, self.port, factory)
294 | return factory.deferred
295 |
296 | def set_poem(self, poem):
297 | self.poem = poem
298 | return poem
299 | ```
300 | 同样,可以与 [旧版本](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-server-2/poetry-proxy.py#100)对比一下. 这个类具有一些新的变化:
301 |
302 | 1. 我们保存 `reactor.connetTCP` 的返回值,一个 [IConnector](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.1.0/twisted/internet/interfaces.py#L24)对象.我们可以使用这个对象上的 `disconnect` 方法关闭连接.
303 | 2. 我们创建带 `canceler` 回调的 `deferred`.那个回调是一个闭包,它使用 `connector` 关闭连接. 但首先须设置 `factory.deferred` 属性为 `None`. 否则,工厂会以 "连接关闭"错误回调激发 `deferred` 而不是以 `CancelledError` 激发. 由于 `deferred` 已经被取消了, 以 `CancelledError` 激发更加合适.
304 |
305 | 你同样会注意到我们是在 `ProxyService` 中创建 `deferred` 而不是 `PoetryClientFactory`. 由于 `canceler` 回调需要获取 `IConnector` 对象, `ProxyService` 成为最方便创建 `deferred` 的地方.
306 |
307 | 同时,就像我们之前的例子, `canceler` 回调作为一个闭包实现.闭包看起来在取消回调的实现上非常有用.
308 |
309 | 让我们试试新的代理.首先启动一个慢速服务器.它需要很慢以便我们有时间取消:
310 | ```
311 | python blocking-server/slowpoetry.py --port 10001 poetry/fascination.txt
312 | ```
313 | 现在可以启动代理(记住你需要Twisted 10.1.0):
314 | ```
315 | python twisted-server-4/poetry-proxy.py --port 10000 10001
316 | ```
317 | 现在我们可以用任何客户端从代理下载一首诗,或者仅使用 `curl`:
318 | ```
319 | curl localhost:10000
320 | ```
321 | 几秒钟后,按 `Ctrl-C` 停止客户端或者 `curl` 进程. 在终端运行代理你将看到如下输出:
322 | ```
323 | Fetching poem from server.
324 | Canceling poem download.
325 | ```
326 | 你应该看到慢速服务器已经停止了输出打印它所发送的诗歌片段,因为我们的代理断开了链接.
327 |
328 | 你可以多次启动和停止客户端来证实每个下载每次都被取消了.但是如果你让整首诗运行完,那么代理将缓存它并且在此之后立即发送它.
329 |
330 | ### 另一个难点
331 |
332 | 以上我们曾不止一次说取消一个已经激发的 `deferred` 是没有效果的.然而,这不是十分正确.在 第十三部分 中,我们知道 `deferred` 的回调和错误回调也可能返回另一个 `deferred`.在那种情况下,原始的(外层) `deferred` 暂停执行它的回调链并且等待内层 `deferred` 激发(参见 图28).
333 |
334 | 如此, 即使一个 `deferred` 激发了发出异步请求的高层代码,它也不能接收到结果,因为在等待内层 `deferred` 完成之前回调链暂停了. 所以当高层代码取消这个外部 `deferred` 时会发生什么情况呢? 在这种情况下,外部 `deferred` 不仅仅是取消它自己(它已经激发了);相反地,这个 `deferred` 也会取消内部的 `deferred`.
335 |
336 | 所以当你取消一个 `deferred` 时,你可能不是在取消主异步操作,而是一些其他的作为前者结果所触发的异步操作.呼!
337 |
338 | 我们可以用一个例子来说明.考虑代码 [deferred-cancel/defer-cancel-12.py](https://github.com/jdavisp3/twisted-intro/blob/master/deferred-cancel/defer-cancel-12.py#L1)
339 | ```python
340 | from twisted.internet import defer
341 |
342 | def cancel_outer(d):
343 | print "outer cancel callback."
344 |
345 | def cancel_inner(d):
346 | print "inner cancel callback."
347 |
348 | def first_outer_callback(res):
349 | print 'first outer callback, returning inner deferred'
350 | return inner_d
351 |
352 | def second_outer_callback(res):
353 | print 'second outer callback got:', res
354 |
355 | def outer_errback(err):
356 | print 'outer errback got:', err
357 |
358 | outer_d = defer.Deferred(cancel_outer)
359 | inner_d = defer.Deferred(cancel_inner)
360 |
361 | outer_d.addCallback(first_outer_callback)
362 | outer_d.addCallbacks(second_outer_callback, outer_errback)
363 |
364 | outer_d.callback('result')
365 |
366 | # at this point the outer deferred has fired, but is paused
367 | # on the inner deferred.
368 |
369 | print 'canceling outer deferred.'
370 | outer_d.cancel()
371 |
372 | print 'done'
373 | ```
374 | 在这个例子中,我们创建了两个 `deferred`, `outer` 和 `inner`,并且有一个外部回调返回内部的 `deferred`. 首先,我们激发外部 `deferred`,然后取消它. 输出结果如下:
375 | ```
376 | first outer callback, returning inner deferred
377 | canceling outer deferred.
378 | inner cancel callback.
379 | outer errback got: [Failure instance: Traceback (failure with no frames):
380 | : ]
381 | done
382 | ```
383 | 正如你看到的,取消外部 `deferred` 并没有使外部 `cancel` 回调被激发. 相反,它取消了内部 `deferred`,所以内部 `cancel` 回调被激发了,之后外部错误回调收到 `CancelledError` (来自内部 `deferred`).
384 |
385 | 你可能需要仔细看一看那些代码,并且做些变化看看如何影响结果.
386 |
387 | ### 讨论
388 |
389 | 取消 `deferred` 是非常有用的操作,使我们的程序避免去做不需要的工作. 然而正如我们看到的,它可能有一点点棘手.
390 |
391 | 需要明白的一个重要事实是取消一个 `deferred` 并不意味着取消了它后面的异步操作.事实上,当写这篇文章时,很多 `deferreds` 并不会被真的"取消",因为大部分Twisted代码写于Twisted 10.1.0之前并且还没有被升级.这包括很多Twisted本身的APIs！检查文档或源代码去发现"取消 `deferred`"是否真的取消了背后的请求,还是仅仅忽略它.
392 |
393 | 第二个重要事实是从你的异步APIs返回的 `deferred` 并不一定在完整意义上可取消. 如果你希望在自己的程序中实现取消,你应该先研究一下Twisted源代码中的许多例子. `Cancellation` 是一个崭新的特性,所以它的模式和最好实践还在制定当中.
394 |
395 | ### 展望未来
396 |
397 | 现在我们已经学习了关于 `Deferreds` 的方方面面以及Twisted背后的核心概念. 这意味着我们没什么需要介绍的了,因为Twisted的其余部分主要包括一些特定的应用,如网络编程或异步数据库处理.故而,在 接下来两部分,我们想走点弯路,看看其他两个使用异步I/O的系统跟Twisted有何理念相似之处.之后,在尾声中,我们会总结并且建议一些帮助你继续学习Twisted的方法.
398 |
399 | ### 参考练习
400 |
401 | 1. 你知道你可以用多种方式拼写"`cancelled`"吗? [真的](http://mw4.m-w.com/dictionary/canceled) 这取决于你的心情.
402 | 2. 细读 [Deferred](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.1.0/twisted/internet/defer.py#L167)类的源代码,关注 `cancellation` 的实现.
403 | 3. 在Twisted 10.1.0的 [源码](http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.1.0/)中找具有取消回调的 `deferred` 的例子.研究它们的实现.
404 | 4. 修改我们诗歌客户端中 `get_poetry` 方法返回的 `deferred`, 使其可取消.
405 | 5. 做一个基于 `reactor` 的例子展示取消外部 `deferred`,它被内层 `deferred` 暂停了.如果使用 `callLater` 你需要小心选择延迟时间,以确保外层 `deferred` 在正确的时刻被取消.
406 | 6. 找一个 Twisted 中还不支持"本质上取消操作"的异步API,为它实现本质取消. 并向 Twisted项目 提交一个 [补丁](http://twistedmatrix.com/trac/wiki/BasicGuideToContributingCode)不要忘记单元测试!
407 |
408 | ### 参考
409 |
410 | 本部分原作参见: dave @
411 |
412 | 本部分翻译内容参见luocheng @
413 |
--------------------------------------------------------------------------------
/zh/p20.md:
--------------------------------------------------------------------------------
1 | ### 简介
2 |
3 | 在这个系列中,有一个事实我们还没有介绍,即混合同步的"普通Python"代码与异步Twisted代码不是一个简单的工作,因为在Twisted程序中阻滞不定时间将使异步模型的优势丧失殆尽.
4 |
5 | 如果你是初次接触异步编程,那么你得到的知识看起来有一些局限.你可以在Twisted框架内使用这些新技术,而不是在更广阔的一般Python代码世界中.同时,当用Twisted工作时,你仅仅局限于那些专门为了作为Twisted程序一部分所写的库,至少如果你想直接从 `reactor` 线程调用它们的时候.
6 |
7 | 但是异步编程技术已经存在了很多年并且几乎不局限于Twisted.其实仅在Python中就有令人吃惊数量的异步编程模型. [搜索](http://www.google.com.hk/search?q=python+async+frameworks) 一下就会看到很多. 它们在细节方面不同于Twisted,但是基本的思想(如异步I/O,将大规模数据流分割为小块处理)是一样的.所以如果你需要,或者选择,使用一个不同的框架,你将会因为学习了Twisted而具备一个很好的开端.
8 |
9 | 当我们移步Python之外,同样会发现很多语言和系统基于或者使用异步编程模型.你在Twisted学习到的知识将继续为你在异步编程方面开拓更广阔的领域而服务.
10 |
11 | 在这个部分,我们将简单地看一看 [Erlang](http://www.erlang.org/),一种编程语言和运行时系统,它以一种独特的方式广泛使用异步编程概念.请注意我们不是要开始写 `Erlang入门`.而是稍稍探索一下Erlang中包含的一些思想,看看这些与Twisted思想的联系.基本主题就是你通过学习Twisted得到的知识可以应用到学习其他技术.
12 |
13 | ### 回顾回调
14 |
15 | 考虑 图6 ,回调的图形表示. 是 第六部分 中介绍的 [诗歌代理3.0](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-3/get-poetry.py#L1) 的回调和 [dataReceived](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-3/get-poetry.py#L56) 方法中的顺序诗歌客户端的原理. 每次从一个相连的诗歌服务器下载一小部分诗歌时将激发回调.
16 |
17 | 假设我们的客户端从3个不同的服务器下载3首诗.以 `reactor` 的角度看问题(这是在这个系列中一直主张的),我们得到一个单一的大循环,当每次轮询时激发一个或多个回调,如图40:
18 |
19 |
20 | 图40 以 reactor 角度的回调
21 |
22 | 此图显示了 `reactor` 欢快地运转,每次诗歌到来时它调用 `dataReceived`. 每次 `dataReceived` 调用应用于一个特定的 `PoetryProtocal` 类实例. 我们知道一共有3个实例因为我们正在下载3首诗(所以必须有3个连接).
23 |
24 | 以一个Protocol实例的角度考虑这张图.记住每个Protocol只有一个连接(一首诗). 这个实例可“看到”一个方法调用流,每个方法接收着诗歌的下一部分,如下:
25 | ```
26 | dataReceived(self, "When I have fears")
27 | dataReceived(self, " that I may cease to be")
28 | dataReceived(self, "Before my pen has glea")
29 | dataReceived(self, "n'd my teeming brain")
30 | ...
31 | ```
32 | 然而这不是严格意义上的Python循环,我们可以将其概念化为一个循环:
33 | ```python
34 | for data in poetry_stream(): # pseudo-code
35 | dataReceived(data)
36 | ```
37 | 我们可以设想"回调循环",如图41:
38 |
39 |
40 | 图41 一个虚拟回调循环
41 |
42 | 当然这不是一个 `for` 循环或 `while` 循环. 在我们诗歌客户端中唯一重要的Python循环是 `reactor`. 但是我们可以把每个Protocol视作一个虚拟循环,当有诗歌到来时它会启动循环. 根据这种想法, 我们可以用图42重构整个客户端:
43 |
44 |
45 | 图42 reactor 转动虚拟循环
46 |
47 | 在这张图中,有一个大循环 —— `reactor` 和三个虚拟循环 —— 诗歌协议实例个体.大循环转起来,如此,使得虚拟循环也转起来了,就像一组环环相扣的齿轮.
48 |
49 | ### 进入Erlang
50 |
51 | [Erlang](http://www.erlang.org/),与Python一样,源自一种八十年代创建的一般目的动态类型的编程语言.不像Python,Erlang是函数式编程语言而不是面向对象的,并且在句法上类似怀旧的 [Prolog](http://en.wikipedia.org/wiki/Prolog), Erlang最初就是由其实现的. Erlang被设计为建立高度可靠的分布式电话系统,因此Erlang包含广泛的网络支持.
52 |
53 | Erlang的一个最独特的特性是一个涉及轻量级进程的并发模型. 一个Erlang进程既不是一个操作系统进程也不是线程.它是在Erlang运行环境中一个独立运行的函数,它有自己的堆栈.Erlang进程不是轻量级的线程,因为Erlang进程不能共享状态(许多数据类型也是不可变的,Erlang是一种函数式编程语言).一个Erlang进程可以与其他Erlang进程交互,但仅仅是通过发送消息,消息总是(至少概念上)被复制的而不是共享.
54 |
55 | 所以一个Erlang程序看起来如图43:
56 |
57 |
58 | 图43 有3个进程的Erlang程序
59 |
60 | 在此图中,个体进程变成了"真实的存在".因为进程在Erlang中是第一构造,就像Python中的对象.但运行时变成了"虚拟的",不是由于它不存在,而是由于它不是一个简单的循环.Erlang运行时可能是多线程的,因为它必须去实现一个全面的编程语言,还要负责很多除异步I/O之外的东西.进一步,一个语言运行时也就是允许Erlang进程和代码执行的媒介,而不是像Twisted中的 `reactor` 那样的额外构造.
61 |
62 | 所以一个Erlang程序的更好表示如下图44:
63 |
64 |
65 | 图44 有若干进程的Erlang程序
66 |
67 | 当然, Erlang运行时确实需要使用异步I/O以及一个或多个选择循环,因为Erlang允许你创建 **大量** 进程. 大规模Erlang程序可以启动成千上万的Erlang进程,所以为每个进程分配一个实际地OS线程是问题所在.如果Erlang允许多进程执行I/O,同时允许其他进程运行即便那个I/O阻塞了,那么异步I/O就必须被包含进来了.
68 |
69 | 注意我们关于Erlang程序的图说明了每个进程是"靠它自己的力量"运行,而不是被回调旋转着. 随着 `reactor` 的工作被归纳成Erlang运行时的结构,回调不再扮演中心角色. 原来在Twisted中需要通过回调解决的问题,在Erlang中将通过从一个进程向另一个进程发送异步消息来解决.
70 |
71 | ### 一个Erlang诗歌代理
72 |
73 | 让我们看一下Erlang诗歌客户端. 这次我们直接跳入工作版本而不是像在Twisted中慢慢地搭建它.同样,这意味着不是完整版本的Erlang介绍. 但如果激起了你的兴趣,我们在本部分最后推荐了一些深度阅读资料.
74 |
75 | Erlang客户端位于 [erlang-client-1/get-poetry](https://github.com/jdavisp3/twisted-intro/blob/master/erlang-client-1/get-poetry#L1). 为了运行它,你需要安装 [Erlang](http://www.erlang.org/).
76 |
77 | 下面代码是 `main` 函数代码,与Python客户端中的 `main` 函数具有相同的目的:
78 | ```Erlang
79 | main([]) ->
80 | usage();
81 |
82 | main(Args) ->
83 | Addresses = parse_args(Args),
84 | Main = self(),
85 | [erlang:spawn_monitor(fun () -> get_poetry(TaskNum, Addr, Main) end)
86 | || {TaskNum, Addr} <- enumerate(Addresses)],
87 | collect_poems(length(Addresses), []).
88 | ```
89 | 如果你从来没有见过Prolog或者相似的语言,那么Erlang的句法将显得有一点奇怪.但是有一些人也这样认为Python.`main` 函数被两个分离的句群定义,被分号分割. Erlang根据参数选择运行哪一个句群,所以第一个句群只在我们执行客户端不提供任何命令行参数的情况下运行,它只打印出帮助信息.第二个句群是所有实际的处理.
90 |
91 | Erlang函数中的每条语句以逗号分隔,函数以句号结尾.让我们看一看第二个句群,第一行仅仅分析命令行参数并且将它们绑定到一个变量(Erlang中所有变量必须大写).第二行使用 `self` 函数来获取当下正在运行的Erlang进程(而非OS进程)的ID.由于这是主函数,你可以认为它等价于Python中的 `__main__` 模块. 第三行是最有趣的:
92 | ```Erlang
93 | [erlang:spawn_monitor(fun () -> get_poetry(TaskNum, Addr, Main) end)
94 | || {TaskNum, Addr} <- enumerate(Addresses)],
95 | ```
96 | 这个语句是对Erlang列表的理解,与Python有相似的句法.它对每个需要连接的服务器产生新的Erlang进程. 同时每个进程将运行相同的 `get_poetry` 函数, 但是根据特定的服务器用不同的参数.我们同时传递主进程的PID以便新的进程可以把诗歌发送回来(你通常需要一个进程的PID来向它发送消息)
97 |
98 | `main` 函数中的最后一条语句调用 `collect_poems` 函数,它等待诗歌传回来和 `get_poetry` 进程结束.我们可以看一下其他函数,但首先你可能会对比一下Erlang的 [main](https://github.com/jdavisp3/twisted-intro/blob/master/erlang-client-1/get-poetry#L96) 函数与等价地Twisted客户端中的 [main](https://github.com/jdavisp3/twisted-intro/blob/master/twisted-client-4/get-poetry.py#L96) 函数.
99 |
100 | 现在让我们看一下Erlang中的 `get_poetry` 函数.事实上在我们的脚本中有两个函数叫 `get_poetry`.在Erlang中,一个函数被名字和元数同时确定,所以我们的脚本包含两个不同的函数, `get_poetry/3` 和 `get_poetry/4`,它们分别接收3个或4个参数.这里是 [get_poetry/3](https://github.com/jdavisp3/twisted-intro/blob/master/erlang-client-1/get-poetry#L79),它是被 `main` 生成的:
101 | ```Erlang
102 | get_poetry(Tasknum, Addr, Main) ->
103 | {Host, Port} = Addr,
104 | {ok, Socket} = gen_tcp:connect(Host, Port,
105 | [binary, {active, false}, {packet, 0}]),
106 | get_poetry(Tasknum, Socket, Main, []).
107 | ```
108 | 这个函数首先创建一个TCP连接,就像Twisted客户端中的 `get_poetry`.但之后,不是返回,而是继续使用那个TCP连接,通过调用 [get_poetry/4](https://github.com/jdavisp3/twisted-intro/blob/master/erlang-client-1/get-poetry#L85),如下:
109 | ```Erlang
110 | get_poetry(Tasknum, Socket, Main, Packets) ->
111 | case gen_tcp:recv(Socket, 0) of
112 | {ok, Packet} ->
113 | io:format("Task ~w: got ~w bytes of poetry from ~s\n",
114 | [Tasknum, size(Packet), peername(Socket)]),
115 | get_poetry(Tasknum, Socket, Main, [Packet|Packets]);
116 | {error, _} ->
117 | Main ! {poem, list_to_binary(lists:reverse(Packets))}
118 | end.
119 | ```
120 | 这个Erlang函数正在做Twisted客户端中 `PoetryProtocol` 的工作,不同的是它使用阻塞函数调用. `gen_tcp:recv` 函数等待在套接字上一些数据的到来(或者套接字关闭),无论要等多长时间.但Erlang中的"阻塞"函数仅阻塞正在运行函数的进程,而不是整个Erlang运行时.那个TCP套接字并不是一个真正的阻塞套接字(你不能在纯Erlang代码中创建一个真正的阻塞套接字).对于Erlang中的每个套接字,在运行时的某处,一个"真正的"TCP套接字被设置为非阻塞模型并且用作选择循环的一部分.
121 |
122 | 但是Erlang进程并不知道这些.它仅仅等待一些数据的到来,如果阻塞了,其他Erlang进程会代替运行.甚至一个进程从不阻塞,Erlang运行时可以在任何时刻自由地在进程间切换.换句话说,Erlang具有一个非协同并发机制.
123 |
124 | 注意 `get_poetry/4`,在收到一小部分诗歌后,继续递归地调用它自己.对于一个急迫的语言程序员这看起来像耗尽内存的良方,但Erlang编译器却可以优化"尾"调用(函数调用一个函数中的最后一条语句)为循环.这照亮了又一个有趣的Erlang客户端和Twisted客户端之间的平行对比.在Twisted客户端中,"虚拟"循环是被 `reaactor` 创建的,它一次又一次地调用相同的函数(`dataReceived`).同时在Erlang客户端中,"真正"的运行进程(`get_poetry/4`)形成通过"[尾调优化](http://stackoverflow.com/questions/310974/what-is-tail-call-optimization)"一次又一次调用它们自己的循环.
125 |
126 | 如果连接关闭了, `get_poetry` 做的最后一件事情是把诗歌发送到主进程.同时结束 `get_poetry` 正在运行的进程,因为没有什么可做的了.
127 |
128 | 我们Erlang客户端中剩下的关键函数是 [collect_poems](https://github.com/jdavisp3/twisted-intro/blob/master/erlang-client-1/get-poetry#L58):
129 | ```Erlang
130 | collect_poems(0, Poems) ->
131 | [io:format("~s\n", [P]) || P <- Poems];
132 | collect_poems(N, Poems) ->
133 | receive
134 | {'DOWN', _, _, _, _} ->
135 | collect_poems(N-1, Poems);
136 | {poem, Poem} ->
137 | collect_poems(N, [Poem|Poems])
138 | end.
139 | ```
140 | 这个函数被主进程运行,就像 `get_poetry`,它对自身递归循环.它同样阻塞. `receive` 告诉进程等待符合给定模式的消息到来,并且从"信箱"中提取消息.
141 |
142 | `collect_poems` 函数等待两种消息: 诗歌和"DOWN"通知.后者是发送给主进程的, 当 `get_poetry` 进程之一由于某种原因死了的情况发送(这是 `spawn_monitor` 的监控部分).通过数 DOWN 消息,我们知道何时所有的诗歌都结束了. 前者是来自 `get_poetry` 进程的包含完整诗歌的消息.
143 |
144 | OK,让我们运行一下Erlang客户端.首先启动3个慢速服务器:
145 | ```
146 | python blocking-server/slowpoetry.py --port 10001 poetry/fascination.txt
147 | python blocking-server/slowpoetry.py --port 10002 poetry/science.txt
148 | python blocking-server/slowpoetry.py --port 10003 poetry/ecstasy.txt --num-bytes 30
149 | ```
150 | 现在我们可以运行Erlang客户端了,与Python客户端有相似的命令行语法.如果你在Linux或其他UNIX-样的系统,你应该可以直接运行客户端(假设你安装了Erlang并使得它在你的PATH上).在Windows中,你可能需要运行 `escript` 程序,将指向Erlang客户端的路径作为第一个参数(其他参数留给Erlang客户端自身的参数).
151 | ```
152 | ./erlang-client-1/get-poetry 10001 10002 10003
153 | ```
154 | 之后,你可以看到如下输出:
155 | ```
156 | Task 3: got 30 bytes of poetry from 127:0:0:1:10003
157 | Task 2: got 10 bytes of poetry from 127:0:0:1:10002
158 | Task 1: got 10 bytes of poetry from 127:0:0:1:10001
159 | ...
160 | ```
161 | 这就像之前的Python客户端之一,打印我们得到的每一小部分诗歌的信息.当所有诗歌都结束后,客户端应该打印每首诗的完整内容.注意客户端在所有服务器之间切换,这取决于哪个服务器可以发送诗歌.
162 |
163 | 图45展示了Erlang客户端的进程结构:
164 |
165 |
166 | 图45 Erlang诗歌客户端
167 |
168 | 这张图显示了3个 `get_poetry` 进程(每个服务器一个)和一个主进程.你可以看到消息从诗歌进程流向主进程.
169 |
170 | 那么当一个服务器失败了会发生什么呢? 让我们试试:
171 | ```
172 | ./erlang-client-1/get-poetry 10001 10005
173 | ```
174 | 上面命令包含一个活动的端口(假设你没有终止之前的诗歌服务器)和一个未激活的端口(假设你没有在10005端口运行任一服务器). 我们得到如下输出:
175 | ```
176 | Task 1: got 10 bytes of poetry from 127:0:0:1:10001
177 |
178 | =ERROR REPORT==== 25-Sep-2010::21:02:10 ===
179 | Error in process <0.33.0> with exit value: {{badmatch,{error,econnrefused}},[{erl_eval,expr,3}]}
180 |
181 | Task 1: got 10 bytes of poetry from 127:0:0:1:10001
182 | Task 1: got 10 bytes of poetry from 127:0:0:1:10001
183 | ...
184 | ```
185 | 最终客户端从活动的服务器完成诗歌下载,打印出诗歌并退出.那么 `main` 函数是怎样得知那两个进程完成工作了? 那个错误消息就是线索. 这个错误来自当 `get_poetry` 尝试连接到服务器时没有得到期望的值({ok, Socket}),而是得到一个连接被拒绝的错误.
186 |
187 | Erlang进程中一个未处理的异常将使其"崩溃",这意味着进程停止运行并且它们所有资源被回收了.但主进程,它监视所有 `get_poetry` 进程,当任何进程无论因为何种原因停止运行时将收到一个DOWN消息.这样,我们的客户端就退出了而不是一直运行下去.
188 |
189 | ### 讨论
190 |
191 | 让我们总结一下Twisted和Erlang客户端关于并行化的特点:
192 |
193 | 1. 它们都是同时连接到所有诗歌服务器(或尝试连接).
194 | 2. 它们都是从服务器立刻接收诗歌,无论是哪个服务器发送的.
195 | 3. 它们都是以小段方式处理诗歌,因此必须保存迄今为止收到的诗歌的一部分.
196 | 4. 它们都创建一个"对象"(或者Python对象或者Erlang进程)来为一个特定服务器处理所有工作.
197 | 5. 它们都需要小心地确定诗歌何时结束,无论一个特定的下载成功与否.
198 |
199 | 在最后, 两个客户端中的 `main` 函数异步地接收诗歌和"任务完成"通知.在Twisted客户端中这个信息是通过 `Deferred` 发送的,而在Erlang中客户端接收来自内部进程消息.
200 |
201 | 注意到两个客户端非常像,无论它们的整体策略还是代码架构.但机理有一点点不同,一个是使用对象, `deferreds` 和回调,另一个是使用进程和消息.然而在高层的思想模型方面,两个客户端是十分相似的,如果你熟悉两种语言可以很方便地把一种转化为另一种.
202 |
203 | 甚至 `reactor` 模式在Erlang客户端中以小型化形式重现.我们诗歌客户端中的每个Erlang进程终究转变为一个递归循环:
204 |
205 | 1. 等待一些事情发生(一小部分诗歌到来,一首诗传递完毕,另一个进程结束),以及
206 | 2. 采取相应的行动.
207 |
208 | 你可以把 Erlang 程序视作一系列小 `reactor` 的大集合,每个都自己旋转着并且偶尔向另一个小 `reactor` 发送一个信息(它将以另一个事件来处理这个信息).
209 |
210 | 另外如果你更加深入Erlang,你将发现回调露面了. Erlang的 [gen_server](http://www.erlang.org/doc/man/gen_server.html) 进程是一个通用的 `reactor` 循环,你可以用一系列回调函数来"实例化"它,这是一种在Erlang系统中重复出现的模式.
211 |
212 | ### 进一步阅读
213 |
214 | 在这个部分我们关注Twisted与Erlang的相似性,但它们毕竟有很多不同.Erlang的一个独特特性之一是它处理错误的方式.一个大的Erlang程序被结构化为一个树形结构的进程组,在高一层有"监管者",在叶子上有"工作者".如果一个工作进程崩溃了,监管进程会注意到并采取相应行动(通常重启失败的进程).
215 |
216 | 如果你有兴趣学习Erlang,那么很幸运.许多关于Erlang的书已经出版或将要出版:
217 |
218 | + [Programming Erlang](http://www.amazon.com/exec/obidos/ASIN/193435600X/krondonet-20) —— 作者是Erlang的发明者之一.这个语言的精彩入门.
219 | + [Erlang Programming](http://www.amazon.com/exec/obidos/ASIN/0596518188/krondonet-20) —— 此书补充了 `Armstrong` 的书,并且在许多关键部分深入更多细节.
220 | + [Erlang and OTP in Action](http://www.amazon.com/exec/obidos/ASIN/1933988789/krondonet-20) —— 此书尚未出版,但我正在等待.前两本书都没有介绍OTP,构造大型应用的Erlang框架.完全披露:这本书的两个作者是我的朋友.
221 |
222 | 关于Erlang先就这么多.在 下一部分 我们会看一看Haskell,另一种函数式语言,与Python和Erlang的感觉都不同.但我们将努力去发现一些共同点.
223 |
224 | ### 建议练习(为高度热情的人)
225 |
226 | 1. 浏览Erlang和Python客户端,并且确定它们在哪里相同哪里不同.它们是怎样处理错误的(比如连接到诗歌服务器的一个错误)?
227 | 2. 简化Erlang客户端以便它不再打印到来的诗歌片段(故而你也不需要跟踪任务号).
228 | 3. 修改Erlang客户端来计量下载每个诗歌所用的时间.
229 | 4. 修改Erlang客户端打印诗歌,并使诗歌的顺序与它们在命令行给定的相同.
230 | 5. 修改Erlang客户端来打印一个更加可读的错误信息当我们不能连接到诗歌服务器时.
231 | 6. 写一个Erlang版本的诗歌服务器正如我们在Twisted中写的.
232 |
233 | ### 参考
234 |
235 | 本部分原作参见: dave @
236 |
237 | 本部分翻译内容参见luocheng @
238 |
--------------------------------------------------------------------------------
/zh/p21.md:
--------------------------------------------------------------------------------
1 | ### 简介
2 |
3 | 在上一个部分我们对比了Twisted与 [Erlang](http://www.erlang.org/),并将注意力集中在它们共有的一些思想上.结果表明使用Erlang也是非常简便的,因为异步I/O和响应式编程是Erlang运行时和进程模型的关键元素.
4 |
5 | 今天我们想走得更远一点,去看一看 [Haskell](http://haskell.org/haskellwiki/Haskell) —— 另一种功能性语言,然而与Erlang有很大不同(当然与Python也不同).这里面没有太多的平行概念,但我们仍然会发现藏在下面的异步I/O概念.
6 |
7 | ### F —— 函数式
8 |
9 | 虽然Erlang是函数式语言,它主要关注可靠的并发模型.Haskell,另一方面,是彻头彻尾函数式的,它无耻地利用了范畴论的概念,如 [函子](http://en.wikipedia.org/wiki/Functor) 和 [单子](http://en.wikipedia.org/wiki/Monad_%28category_theory%29).
10 |
11 | 不要慌.我们这里不会涉及那些复杂的东西(虽然我们可以).相反,我们将关注一个Haskell的更加传统的功能特性:惰性. 像许多函数式语言一样(除了Erlang), Haskell支持 [惰性计算](http://en.wikipedia.org/wiki/Lazy_evaluation). 在懒惰计算语言中,程序的文字并不过多的描述怎样计算需要计算的东西.具体实施计算的细节一般留给了编译器和运行时系统.
12 |
13 | 同时,需要进一步指出,作为惰性计算推进的运行时可能一次只计算表达式的一部分(惰性的)而不是全部.一般地,运行时只提供维持当前计算继续所需的最小计算量.
14 |
15 | 这里有一个使用Haskell `head` 语句的简单例子,这是一个提取列表第一个元素的函数,对于列表[1,2,3](Haskell与Python共享一些列表句法):
16 | ```
17 | head [1,2,3]
18 | ```
19 | 如果你安装了GHC Haskell运行时,你可以自己试一试:
20 | ```
21 | [~] ghci
22 | GHCi, version 6.12.1: http://www.haskell.org/ghc/ : ? for help
23 | Loading package ghc-prim ... linking ... done.
24 | Loading package integer-gmp ... linking ... done.
25 | Loading package base ... linking ... done.
26 | Prelude> head [1,2,3]
27 | 1
28 | Prelude>
29 | ```
30 | 结果是 `1`, 正如所料.
31 |
32 | Haskell列表的语法包含从前几个元素定义列表的使用功能.例如,列表[2,4,..]是从2开始的偶数序列.到哪结束呢?实际上并不会结束.Haskell列表[2,4,..]和其他如此表述的都是(概念上)无限列表.你可以在交互式Haskell提示符下计算它,这将试图打印这个表达式的结果如下:
33 | ```
34 | Prelude> [2,4 ..]
35 | [2,4,6,8,10,12,14,16,18,20,22,24,26,28,30,32,34,36,38,40,42,44,46,48,50,52,54,56,58,60,62,64,66,68,70,72,74,76,78,80,82,84,86,88,90,92,94,96,98,100,102,104,106,108,110,112,114,116,118,120,122,124,126,128,130,132,134,136,138,140,142,144,146,
36 | ...
37 | ```
38 | 你不得不按 `Ctrl-C` 终止计算，因为它自己不会停下来.但由于是惰性计算,在Haskell中应用无限列表是没有问题的:
39 | ```
40 | Prelude> head [2,4 ..]
41 | 2
42 | Prelude> head (tail [2,4 ..])
43 | 4
44 | Prelude> head (tail (tail [2,4 ..]))
45 | 6
46 | ```
47 | 这里我们分别获取无限列表的第一、二、三个元素,没看到任何无限循环.这就是惰性计算的本质.Haskell运行时只构造完成 `head` 函数所需的列表,而不是先构造整个列表(这将导致无限循环),再将整个列表传递给 `head`.这个列表的其余部分跟本没有被构造,因为它们对继续推进计算毫无意义.
48 |
49 | 当我们引入 `tail` 函数时,Haskell被迫进一步构造列表,但是又一次仅仅构造了满足下一次计算所需的列表.同时,一旦计算结束,列表(未完成的)被丢弃了.
50 |
51 | 这里是一些部分计算无限列表的Haskell代码：
52 | ```
53 | Prelude> let x = [1..]
54 | Prelude> let y = [2,4 ..]
55 | Prelude> let z = [3,6 ..]
56 | Prelude> head (tail (tail (zip3 x y z)))
57 | (3,6,9)
58 | ```
59 | `zip` 函数将所有列表压缩在一起,之后抓取尾部的尾部的头部.又一次,Haskell没有发生任何问题,仅仅构造了计算所需的列表.我们可以将Haskell运行时"消耗"这些无限列表的过程可视化：
60 |
61 |
62 | 图46 Haskell消耗一些无限列表
63 |
64 | 虽然我们将Haskell运行时画为一个简单的循环,它可能被多线程实现(并且很可能如果你使用GHC版本的Haskell).但这幅图的关键点在于它十分像一个 `reactor` 循环,消耗从网络套接字传来的数据片段.
65 |
66 | 你可以把异步I/O和 `reactor` 模式视为一种有限形式的惰性计算.异步I/O的格言是:"仅仅推进你所拥有的数据".同时惰性计算的格言是:"仅仅推进你所需的数据".进一步,一个惰性计算语言在任何地方都使用这个格言,并不仅仅是有限范围的I/O.
67 |
68 | 但关键点在于,对于惰性计算语言,做异步I/O小菜一碟. 编译器和运行时已经被设计为一点一点地处理数据结构,因而惰性地处理到来的I/O数据流是标准问题. 如此Haskell运行时,就像Erlang运行时,简单地集成异步I/O为套接字抽象的一部分. 我们以实现一个Haskell诗歌客户端来展示这个概念.
69 |
70 | ### Haskell 诗歌
71 |
72 | 我们第一个Haskell诗歌客户端位于 [haskell-client-1/get-poetry.hs](https://github.com/jdavisp3/twisted-intro/blob/master/haskell-client-1/get-poetry.hs). 同Erlang一样,我们直接给出了完成版的客户端,如果你希望学习更多,我们列出进一步阅读的参考.
73 |
74 | Haskell同样支持轻量级线程或进程,尽管它们不是Haskell的核心,我们的Haskell客户端为每首需要下载的诗歌创建一个进程.关键函数是 [runTask](https://github.com/jdavisp3/twisted-intro/blob/master/haskell-client-1/get-poetry.hs#L64),它连接到一个套接字并且以轻量级线程启动 [getPoetry](https://github.com/jdavisp3/twisted-intro/blob/master/haskell-client-1/get-poetry.hs#L48) 函数.
75 |
76 | 在这个代码中,你将看到许多类型定义. Haskell,不像Python和Erlang,是静态类型的.我们没有为每个变量定义类型，因为Haskell可以自动地推断没有显示定义的变量(或者报告错误如果不能推断).许多函数包含IO类型(技术上叫单子)，因为Haskell要求我们将有副作用的代码从纯函数中干净地分离(如,执行I/O的代码).
77 |
78 | `getPoetry` 函数包含如下行:
79 | ```
80 | poem <- hGetContents h
81 | ```
82 | 看起来像从句柄一次读入整首诗(如TCP套接字).但是Haskell,像往常一样,是惰性的.Haskell运行时包含一个或更多实际线程,它们在一个选择循环中执行异步I/O,如此便保存了惰性处理I/O流的可能性.
83 |
84 | 仅仅为说明异步I/O正在进行,我们引入一个"回调"函数, [gotLine](https://github.com/jdavisp3/twisted-intro/blob/master/haskell-client-1/get-poetry.hs#L60),它为诗歌的每一行打印一些任务信息.但这不是一个真正的回调函数,无论我们用不用它程序都会使用异步I/O.甚至叫它"gotLine"反映了一个必要的语言思维,它是Haskell程序外的一部分.无论怎样,我们将一点点清扫它,先使Haskell客户端运转起来.
85 |
86 | 启动一些慢诗歌服务器:
87 | ```
88 | python blocking-server/slowpoetry.py --port 10001 poetry/fascination.txt
89 | python blocking-server/slowpoetry.py --port 10002 poetry/science.txt
90 | python blocking-server/slowpoetry.py --port 10003 poetry/ecstasy.txt --num-bytes 30
91 | ```
92 | 现在编译Haskell客户端:
93 | ```
94 | cd haskell-client-1/
95 | ghc --make get-poetry.hs
96 | ```
97 | 这将创建一个二进制 `get-poetry`.最后,针对我们的服务器运行客户端:
98 | ```
99 | /get-poetry 10001 10002 1000
100 | ```
101 | 你将看到如下输出:
102 | ```
103 | Task 3: got 12 bytes of poetry from localhost:10003
104 | Task 3: got 1 bytes of poetry from localhost:10003
105 | Task 3: got 30 bytes of poetry from localhost:10003
106 | Task 2: got 20 bytes of poetry from localhost:10002
107 | Task 3: got 44 bytes of poetry from localhost:10003
108 | Task 2: got 1 bytes of poetry from localhost:10002
109 | Task 3: got 29 bytes of poetry from localhost:10003
110 | Task 1: got 36 bytes of poetry from localhost:10001
111 | Task 1: got 1 bytes of poetry from localhost:10001
112 | ...
113 | ```
114 | 输出与前一个异步客户端有点不同,因为我们只打印一行而不是任意块的数据.但你可以清楚地看到,客户端是从所有服务器同时处理数据,而不是一个接一个.你同样可以注意到客户端立即打印第一首完成的诗,不等其他还在继续处理的诗.
115 |
116 | 好了,让我们清除还剩下的一点讨厌东西并且发布一个仅仅抓取诗歌而不介意任务序号的新版本.它位于 [haskell-client-2/get-poetry.hs](https://github.com/jdavisp3/twisted-intro/blob/master/haskell-client-2/get-poetry.hs). 注意它短多了,对于每个服务器,仅仅连接到套接字,抓取所有数据,之后将其发送回去.
117 |
118 | OK,让我们编译新的客户端：
119 | ```
120 | cd haskell-client-2/
121 | ghc --make get-poetry.hs
122 | ```
123 | 针对相同的诗歌服务器组运行它:
124 | ```
125 | ./get-poetry 10001 10002 10003
126 | ```
127 | 最终,你将看到屏幕上出现每首诗的文字.
128 |
129 | 注意到每个服务器同时向客户端发送数据.更重要的,客户端以最快速度打印出第一首诗的每一行,而不去等待其余的诗,甚至当它正在处理其它两首诗.之后它快速地打印出之前积累的第二首诗.
130 |
131 | 同时这所有发生的一切都不需要我们做什么.这里没有回调,没有传来传去的消息,仅仅是一个关于我们希望程序做什么的简洁地描述,而且很少需要告诉它应该怎样做.其余的事情都是由Haskell编译器和运行时处理的.漂亮!
132 |
133 | ### 讨论与进一步阅读
134 |
135 | 从Twisted到Erlang之后到Haskell,我们可以看到一个平行的移动,从前景到背景逐步深入异步编程背后的思想.在Twisted中,异步编程是其存在的核心激励理念. Twisted实现作为一个与Python分离的框架(Python缺乏核心的异步抽象如轻量级线程),当你用Twisted写程序时，将异步模型置于首位与核心.
136 |
137 | 在Erlang中,异步对于程序员仍然是可见的,但细节成为语言材料的一部分和运行时系统,形成一个抽象使得异步消息在同步进程之间交换.
138 |
139 | 最后,在Haskell中,异步I/O仅仅是运行时中的另一个技术,大部分对于程序员是不可见的,因为提供惰性计算是Haskell的中心理念.
140 |
141 | 对于以上情况,我们还没有介绍任何深邃的思想.我们仅仅指出许多有趣的异步模型出现的地方,这种模型可以被多种方式表达.
142 |
143 | 如果这些激起你对Haskell的兴趣,那么我们推荐"[Real World Haskell](http://www.amazon.com/exec/obidos/ASIN/0596514980/krondonet-20)"继续你的学习.这本书是介绍语言学习的典范.
144 |
145 | 虽然我没有读过它,我却听说到它饱受"[Learn You a Haskell](http://learnyouahaskell.com/)"的赞誉.
146 |
147 | 完成了本系列的倒数第二部分，现在到了结束探索Twisted之外异步系统的时刻. 在 第二十二节 中,我们将做一个总结,以及推荐一些学习Twisted的方法.
148 |
149 | ### 建议练习(献给令人吃惊的狂热者)
150 |
151 | 1. 互相对比Twisted,Erlang和Haskell客户端.
152 | 2. 修改Haskell客户端来处理连接诗歌服务器的失败,以便它们能够下载所有的能够下载的诗歌并为那些不能下载的诗歌输出合理的错误消息.
153 | 3. 写Haskell版本的对应Twisted中的诗歌服务器.
154 |
155 | ### 参考
156 |
157 | 本部分原作参见: dave @
158 |
159 | 本部分翻译内容参见luocheng @
160 |
--------------------------------------------------------------------------------
/zh/p22.md:
--------------------------------------------------------------------------------
1 | ### 完结
2 |
3 | 呼呼！ 感谢你一路支持. 在我开始时完全没有想到这个系列会这么长,会花这么多时间完成,但是创建这个系列的过程使我非常享受,也希望你喜欢它.
4 |
5 | 既然我已经完成了,我会进一步考虑将其转化为PDF格式.但是,不保证.
6 |
7 | 最后,我想总结一些帮助你继续学习Twisted的建议.
8 |
9 | ### 进一步阅读
10 |
11 | 首先,我建议阅读Twisted的 [在线文档](http://twistedmatrix.com/trac/wiki/Documentation). 虽然它备受指责,但我觉得这总比饱受赞誉要好.
12 |
13 | 如果你希望使用Twisted进行网络编程, 那么 **Jean-Paul Calderone** 的广受关注的系列 [Twisted网络编程60秒](http://jcalderone.livejournal.com/50562.html) 是不错的选择. 虽然我觉得60秒可能读不完.
14 |
15 | 但我认为比以上更重要的是阅读Twisted [源码](http://twistedmatrix.com/trac/browser/trunk), 因为这些源码是被非常熟悉Twisted的人写的,其中的任何例子都会告诉你怎样用"Twisted的方式"做事情.
16 |
17 | ### 参考练习
18 |
19 | 1. 将你写过的一个同步程序转化为使用Twisted的.
20 | 2. 从零开始,写一个Twisted程序.
21 | 3. 从Twisted的 [bug库](http://twistedmatrix.com/trac/report) 拾起一个错误,并修改它. 给Twisted的开发者提交一个补丁, 不要忘记阅读贡献源代码的 [操作流程](http://twistedmatrix.com/trac/wiki/ContributingToTwistedLabs).
22 |
23 | ### 真的要结束了
24 |
25 | 祝你编码快乐!
26 |
27 |
28 | 图47 结束
29 |
30 | ### 参考
31 |
32 | 本部分原作参见: dave @
33 |
34 | 本部分翻译内容参见luocheng @
35 |
--------------------------------------------------------------------------------
