[譯]The multi Interface

The multi Interface
multi接口

The easy interface as described in detail in this document is a synchronous interface that transfers one file at a time and doesn't return until it is done.
easy接口是同步的，調用同步接口傳輸文件，須要等到傳輸完畢函數纔會返回。

The multi interface, on the other hand, allows your program to transfer multiple files in both directions at the same time, without forcing you to use multiple threads. The name might make it seem that the multi interface is for multi-threaded programs, but the truth is almost the reverse. The multi interface allows a single-threaded application to perform the same kinds of multiple, simultaneous transfers that multi-threaded programs can perform. It allows many of the benefits of multi-threaded transfers without the complexity of managing and synchronizing many threads.
multi接口，容許你的程序同時向不一樣目標傳輸文件，而不須要使用多線程。
multi這個名字讓他看起來像是多線程的程序，可是實際上不是。
multi能夠在單線程、多線程程序中執行。

To complicate matters somewhat more, there are even two versions of the multi interface. The event based one, also called multi_socket and the "normal one" designed for using with select(). See the libcurl-multi.3 man page for details on the multi_socket event based API, this description here is for the select() oriented one.
比較麻煩的是，有2個版本的multi接口。
第一個被稱爲multi_socket，使用的是select()機制。

To use this interface, you are better off if you first understand the basics of how to use the easy interface. The multi interface is simply a way to make multiple transfers at the same time by adding up multiple easy handles into a "multi stack".
要使用這個接口，最好先了解如何使用easy接口。
Multi接口同時傳輸文件是經過把多個easy_curl的句柄添加到「multi stack」中。

You create the easy handles you want, one for each concurrent transfer, and you set all the options just like you learned above, and then you create a multi handle with curl_multi_init and add all those easy handles to that multi handle with curl_multi_add_handle.
建立easy句柄後，做爲併發傳輸的句柄之一，並設置你所須要的屬性，
而後使用curl_multi_init函數建立一個multi句柄，使用curl_multi_add_handle函數添加全部easy句柄到multi句柄中。

When you've added the handles you have for the moment (you can still add new ones at any time), you start the transfers by calling curl_multi_perform.
你能夠隨時添加easy句柄到multi句柄中，而後使用curl_multi_perfrorm函數執行傳輸。

curl_multi_perform is asynchronous. It will only perform what can be done now and then return back control to your program. It is designed to never block. You need to keep calling the function until all transfers are completed.
curl_multi_perform異步的，這個函數只執行當前能執行的操做，等到所有執行完畢再回調通知程序。
你須要保持這個函數的調用，直到全部傳輸完成。

The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also makes it easy for you to wait and respond to actions on your own application's sockets/handles. You figure out what to select() for by using curl_multi_fdset, that fills in a set of fd_set variables for you with the particular file descriptors libcurl uses for the moment.
這個接口最好的用法是：你select()全部文件描述符或者sokect，來查看libcurl是否通知了。
這也使得你的程序在等待、回覆時更簡單。
使用curl_multi_fdset函數來找出應該select()什麼，填入參數爲你當前使用的libcurl文件描述符的fd_set對。

When you then call select(), it'll return when one of the file handles signal action and you then call curl_multi_perform to allow libcurl to do what it wants to do. Take note that libcurl does also feature some time-out code so we advise you to never use very long timeouts on select() before you call curl_multi_perform again. curl_multi_timeout is provided to help you get a suitable timeout period.
當調用select()時候，當檢測到文件句柄有信號會返回，
你能夠調用curl_multi_perform來容許libcurl執行。
須要注意的是libcurl會超時，因此建議絕對不要在調用curl_multi_perform以前，設置長時間的select()設置長時間的超時。
curl_multi_timeout函數用於幫你獲取一個合適的超時時間。

Another precaution you should use: always call curl_multi_fdset immediately before the select() call since the current set of file descriptors may change in any curl function invoke.
其餘注意點:在調用select()前，使用curl_multi_fdset，防止當前文件描述符對被其餘libcurl函數改變。

If you want to stop the transfer of one of the easy handles in the stack, you can use curl_multi_remove_handle to remove individual easy handles. Remember that easy handles should be curl_easy_cleanuped.
若是你想中止multi stack中的easy handle，你可使用curl_mult_remove_handle函數來移除一個easy handle。
以後記得要使用curl_easy_cleanuped。

When a transfer within the multi stack has finished, the counter of running transfers (as filled in by curl_multi_perform) will decrease. When the number reaches zero, all transfers are done.
當multi stack中的一個傳輸完成，運行中的傳輸計數（curl_multi_perform函數的參數）會減一。
當計數爲0，表示全部傳輸完成。

curl_multi_info_read can be used to get information about completed transfers. It then returns the CURLcode for each easy transfer, to allow you to figure out success on each individual transfer.curl_multi_info_read用於獲取已完成的傳輸信息，這個函數會返回每一個easy handle傳輸的CURLcode，CURLcode用於查看傳輸結果