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.

  停止觀察用於寫可用性的文件描述符。