Python Tulip ( asyncio) 第2节 Base Event Loop 基本事件循环（2） 译文

Tulip 的 《基本事件循环》第二篇 （共三篇）

这是很长的一篇 所以分成了几部分

18.5.1. Base Event Loop  基本事件循环

（...续前文）

18.5.1.4. Coroutines  协程

• BaseEventLoop.create_task(coro)

  Schedule the execution of a coroutine object: wrap it in a future. Return a Task object.

  Third-party event loops can use their own subclass of Task for interoperability. In this case, the result type is a subclass of Task.

  
  

  安排执行coroutine object ，使用future封装。返回Task 对象。第三方事件循环可以用于他们的Task子类，用来互操作。这种情况下，返回类型也是一个Task子类。

  
  

  This method was added in Python 3.4.2. Use the async() function to support also older Python versions.

  这个方法是在Python 3.4.2中新加入的，使用async()函数也可以被更低一点的Python版本支持。

  
  

  New in version 3.4.2.   在3.4.2版本新增。

18.5.1.5. Creating connections 创建连接

• BaseEventLoop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None,local_addr=None, server_hostname=None)

  Create a streaming transport connection to a given Internet host and port: socket family AF_INET or AF_INET6 depending on host (or family if specified), socket type SOCK_STREAM. protocol_factory must be a callable returning a protocol instance.

  This method is a coroutine which will try to establish the connection in the background. When successful, the coroutine returns a (transport,protocol) pair.

  根据指定的host 和 port创建一个流传输链接：端口模式AF_INET或者AF_INET6 取决于主机，也可以手工指定，端口类型是SOCK_STREAM，protocol_factory必须是返回protocol的一个实例。此方法是一个在后台建立连接的coroutine ，协程返回一个(transport,protocol)对。
  

  
  

  The chronological synopsis of the underlying operation is as follows: 

  按先后顺序概要中介，其下的详细操作过程如下：    

1. The connection is established, and a transport is created to represent it.

2. protocol_factory is called without arguments and must return a protocol instance.

3. The protocol instance is tied to the transport, and its connection_made() method is called.

4. The coroutine returns successfully with the (transport, protocol) pair.

1. 连接被建立，并且一个transport被创建用以表示它。

2. 无参的protocol_factory被调用，要求返回一个protocol实例。

3. 协议实例试图传输数据，并调用其connection_made()方法。

4. 协程对象通过(transport, protocol)对成功返回。
   

The created transport is an implementation-dependent bidirectional stream. 

创建的连接是一个依赖于实现的双向流。

Note 注意 

  protocol_factory can be any kind of callable, not necessarily a class. For example, if you want to use a pre-created protocol instance, you can pass lambda: my_protocol.

protocol_factory可以是任何类型的回调，不必须是一个类。例如如果你想使用一个预先创建好的协议实例，��可以传递lambda: my_protocol。

Options allowing to change how the connection is created:

在创建连接时，可以使用下面的选项：

• ssl: if given and not false, a SSL/TLS transport is created (by default a plain TCP transport is created). If ssl is a ssl.SSLContextobject, this context is used to create the transport; if ssl is True, a context with some unspecified default settings is used.

  
  

  ssl:如果这个选项指定了值或者设置为True，会建立一个SSL/TLS传输（默认创建一个简单TCP传输）。如果ssl是一个 ssl.SSLContext 对象，这个容器将被用来创建传输，如果ssl 设置为 True，一个包含未指定默认值的容器会被使用。

  
  

  See also 参见 
  

  SSL/TLS security considerations SSL/TLS安全性说明

• server_hostname, is only for use together with ssl, and sets or overrides the hostname that the target server’s certificate will be matched against. By default the value of the host argument is used. If host is empty, there is no default and you must pass a value forserver_hostname. If server_hostname is an empty string, hostname matching is disabled (which is a serious security risk, allowing for man-in-the-middle-attacks).

  server_hostname - 仅仅配合ssl使用，并且这个设置会覆盖目标服务器证书进行重新匹配。默认这个使用的是host中的值。如果host为空，并且没有设置默认值，那么你需要传递一个值给server_hostname 。如果server_hostname也是空值，主机名匹配将会被禁用（这将是一个安全风险，它可以允许 man-in-the-middle攻击）。

• family, proto, flags are the optional address family, protocol and flags to be passed through to getaddrinfo() for host resolution. If given, these should all be integers from the corresponding socket module constants.

  family, proto, flags 是一组地址家族、协议和标志位的选项，可以通过getaddrinfo()实现host解析。如果给定这个选项，这些都是对应socket 模块常量的整型值。

• sock, if given, should be an existing, already connected socket.socket object to be used by the transport. If sock is given, none of host,port, family, proto, flags and local_addr should be specified.

  sock 如果指定值，应该是一个已存在的，并且已经连接到socket.socket的用来传输的对象。如果sock没有指定，host,port, family, proto, flags 及local_addr 都无需指定。
  

• local_addr, if given, is a (local_host, local_port) tuple used to bind the socket to locally. The local_host and local_port are looked up using getaddrinfo(), similarly to host and port.

  local_addr  如果指定是一个(local_host, local_port)数组，用来绑定协议到本地。这个 local_host  和 local_port用来 getaddrinfo()进行查找，类似于 host 和 port。

On Windows with ProactorEventLoop, SSL/TLS is not supported.  

在Windows系统使用ProactorEventLoop，SSL/TLS不支持。

  See also 参见 

  The open_connection() function can be used to get a pair of (StreamReader, StreamWriter) instead of a protocol.

  open_connection()函数用来获取一个(StreamReader, StreamWriter)对而不是协议。

• BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0)

  Create datagram connection: socket family AF_INET or AF_INET6 depending on host (or family if specified), socket type SOCK_DGRAM.

  创建一个数据报连接：依赖于 host 的端口族AF_INET 或 AF_INET6（或者自己指定）。端口类型是SOCK_DGRAM。
  

  
  

  This method is a coroutine which will try to establish the connection in the background. When successful, the coroutine returns a (transport,protocol) pair.

  这个方法是一个将试图建立后台连接的 coroutine。当连接成功，协程会返回(transport,protocol)对。

  
  

  See the BaseEventLoop.create_connection() method for parameters.

  参考BaseEventLoop.create_connection() 方法的更多说明。

• BaseEventLoop.create_unix_connection(protocol_factory, path, *, ssl=None, sock=None, server_hostname=None)

  Create UNIX connection: socket family AF_UNIX, socket type SOCK_STREAM. The AF_UNIX socket family is used to communicate between processes on the same machine efficiently.

  创建一个UNIX连接：端口族AF_UNIX，端口类型SOCK_STREAM。AF_UNIX 端口族用来建立同一台机器上的进程之间的高效连接。

  
  

  This method is a coroutine which will try to establish the connection in the background. When successful, the coroutine returns a (transport,protocol) pair.

  此方法是一个试图建立后台连接的coroutine。连接成功后，协程返回一个(transport,protocol)对。

  
  

  See the BaseEventLoop.create_connection() method for parameters.

  参考BaseEventLoop.create_connection()方法获得更多参数说明。

  
  

  Availability: UNIX.  可用性：UNIX系统

18.5.1.6. Creating listening connections 创建监听连接

• BaseEventLoop.create_server(protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE,sock=None, backlog=100, ssl=None, reuse_address=None)

  Create a TCP server bound to host and port. Return a Server object, its sockets attribute contains created sockets. Use theServer.close() method to stop the server: close listening sockets.

  创建一个TCP服务器暴露指定的主机和端口。返回一个服务器对象，它的端口属性包含创建的端口。使用theServer.close()方法停止服务器，关闭监听端口。

  
  

  This method is a coroutine.

  这个方法是一个coroutine。

  
  

  If host is an empty string or None all interfaces are assumed and a list of multiple sockets will be returned (most likely one for IPv4 and another one for IPv6).

  如果host是空字符串或空，所有的接口都是假定的，并且返回一个多重的socket（更像IPv4或IPv6的形式）。

  
  

  family can be set to either AF_INET or AF_INET6 to force the socket to use IPv4 or IPv6. If not set it will be determined from host (defaults toAF_UNSPEC).

  family 可以被设置为AF_INET or AF_INET6 强制端口使用IPv4或IPv6。如果没有设置将根据主机来判断（默认是AF_UNSPEC）。
  

  
  

  flags is a bitmask for getaddrinfo().

  flags 是按位模式的掩码，用于getaddrinfo()函数。
  

  
  

  sock can optionally be specified in order to use a preexisting socket object.

  sock 是一个可选项，用来实用一个已经存在的sokect对象。
  

  
  

  backlog is the maximum number of queued connections passed to listen() (defaults to 100).

  backlog 是传递给listen()函数的连接队列的最大值（默认是100）。

  
  

  ssl can be set to an SSLContext to enable SSL over the accepted connections.

  ssl可以设置到一个SSLContext以允许通过接收的连接实用SSL。

  
  

  reuse_address tells the kernel to reuse a local socket in TIME_WAIT state, without waiting for its natural timeout to expire. If not specified will automatically be set to True on UNIX.

  reuse_address 告知内核重用一个在TIME_WAIT状态的本地sokcet，无需等待期自然超时或过期。如果指定了，在UNIX系统将会自动设置为True。

  
  

  See also 参见

   

  The function start_server() creates a (StreamReader, StreamWriter) pair and calls back a function with this pair.

  start_server()函数创建一个(StreamReader, StreamWriter)对，并且通过这个成对数据调用一个返回函数。

• BaseEventLoop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None)

  Similar to BaseEventLoop.create_server(), but specific to the socket family AF_UNIX.

  类似BaseEventLoop.create_server()，但是指定一个端口族为AF_UNIX。
  

  
  

  Availability: UNIX.

 可用性：UNIX 系统

18.5.1.7. Watch file descriptors 观察文件描述符

• BaseEventLoop.add_reader(fd, callback, *args)

  Start watching the file descriptor for read availability and then call the callback with specified arguments.

  开始观察用于度可用性的文件描述符，用来在可用时读取并且使用指定的参数调用回调callback。

• BaseEventLoop.remove_reader(fd)

  Stop watching the file descriptor for read availability.

  停止观察用于读取可用性的文件描述符。

• BaseEventLoop.add_writer(fd, callback, *args)

  Start watching the file descriptor for write availability and then call the callback with specified arguments.

  开始观察用于写可用性的文件描述符，并且使用指定的参数调用回调callback。

• BaseEventLoop.remove_writer(fd)

  Stop watching the file descriptor for write availability.

  停止观察用于写可用性的文件描述符。