【導(dǎo)讀】本的超時(shí)功能，檢測OS信號(hào)。bufferevent：為libevent基于事件的核心提供使用更方便的封裝。（bufferevent接口有多個(gè)后端，可以采用系統(tǒng)能夠提供的更快的非阻塞IO方。libevent_core：所有核心的事件和緩沖功能，包含了所有的event_base、evbuffer、libevent_extra：定義了程序可能需要，也可能不需要的協(xié)議特定功能，包括HTTP、不應(yīng)該使用這個(gè)庫，未來版本的libevent可能去掉這個(gè)庫。libevent以更合理的、不易出錯(cuò)的方式修正了API。在以及以后版本的libevent中，老的頭文件仍然會(huì)作為新頭文件的封裝而存在。結(jié)構(gòu)體持有一個(gè)事件集合，可以檢測以確定哪個(gè)事件是激活的。event_config是一個(gè)容納event_base配置信息的不透明結(jié)構(gòu)體。

　　

【正文】 evutil_secure_rng_init()。 可以調(diào)用 evutil_secure_rng_add_bytes()向熵池加入更多隨機(jī)字節(jié)，但通常不需要這么做。 這些函數(shù)是 版本引入的。 libevent 參考手冊(cè)第 六章： bufferevent：概念和入門 很多時(shí)候，除了響應(yīng)事件之外，應(yīng)用還希望做一定的數(shù)據(jù)緩沖。比如說，寫入數(shù)據(jù)的時(shí)候，通常的運(yùn)行模式是： ?? 決定要向連接寫入一些數(shù)據(jù)，把數(shù)據(jù)放入到緩沖區(qū)中 ?? 等待連接可以寫入 ?? 寫入盡量多的數(shù)據(jù) ?? 記住寫入了多少數(shù)據(jù)，如果還有更多數(shù)據(jù)要寫入，等待連接再次可以寫入 這種緩沖 IO 模式很通用， libevent 為此提供了一種通用機(jī)制，即 bufferevent。bufferevent 由一個(gè)底層的傳輸端口（如套接字），一個(gè)讀取緩沖區(qū)和一個(gè)寫入緩沖區(qū)組成。與通常的事件在底層傳輸 端口已經(jīng)就緒，可以讀取或者寫入的時(shí)候執(zhí)行回調(diào)不同的是，bufferevent 在讀取或者寫入了足夠量的數(shù)據(jù)之后調(diào)用用戶提供的回調(diào)。 有多種共享公用接口的 bufferevent 類型，編寫本文時(shí)已存在以下類型： ?? 基于套接字的 bufferevent：使用 event_*接口作為后端，通過底層流式套接字發(fā)送或者接收數(shù)據(jù)的 bufferevent ?? 異步 IO bufferevent：使用 Windows IOCP 接口，通過底層流式套接字發(fā)送或者接收數(shù)據(jù)的 bufferevent（僅用于 Windows，試驗(yàn)中） ?? 過濾型 bufferevent：將數(shù)據(jù)傳輸?shù)降讓?bufferevent 對(duì)象之前，處理輸入或者輸出數(shù)據(jù)的 bufferevent：比如說，為了壓縮或者轉(zhuǎn)換數(shù)據(jù)。 ?? 成對(duì)的 bufferevent：相互傳輸數(shù)據(jù)的兩個(gè) bufferevent。 注意 ：截止 版，這里列出的 bufferevent 接口還沒有完全正交于所有的bufferevent 類型。也就是說，下面將要介紹的接口不是都能用于所有 bufferevent 類型。libevent 開發(fā)者在未來版本中將修正這個(gè)問題。 也請(qǐng)注意 ：當(dāng)前 bufferevent 只 能用于像 TCP 這樣的面向流的協(xié)議，將來才可能會(huì)支持像 UDP 這樣的面向數(shù)據(jù)報(bào)的協(xié)議。 本節(jié)描述的所有函數(shù)和類型都在 event2/ 中聲明。特別提及的關(guān)于evbuffer 的函數(shù)聲明在 event2/ 中，詳細(xì)信息請(qǐng)參考下一章。 1 bufferevent 和 evbuffer 每個(gè) bufferevent 都有一個(gè)輸入緩沖區(qū)和一個(gè)輸出緩沖區(qū)，它們的類型都是“ struct evbuffer”。有數(shù)據(jù)要寫入到 bufferevent 時(shí)，添加數(shù)據(jù)到輸出緩沖區(qū)； bufferevent 中有數(shù)據(jù)供 讀取的時(shí)候，從輸入緩沖區(qū)抽?。?drain）數(shù)據(jù)。 evbuffer 接口支持很多種操作，后面的章節(jié)將討論這些操作。 2 回調(diào)和水位 每個(gè) bufferevent 有兩個(gè)數(shù)據(jù)相關(guān)的回調(diào)：一個(gè)讀取回調(diào)和一個(gè)寫入回調(diào)。默認(rèn)情況下，從底層傳輸端口讀取了任意量的數(shù)據(jù)之后會(huì)調(diào)用讀取回調(diào)；輸出緩沖區(qū)中足夠量的數(shù)據(jù)被清空到底層傳輸端口后寫入回調(diào)會(huì)被調(diào)用。通過調(diào)整 bufferevent 的讀取和寫入“水位（ watermarks）”可以覆蓋這些函數(shù)的默認(rèn)行為。 每個(gè) bufferevent 有四個(gè)水位： ?? 讀取低水位 ：讀取操作使得輸入緩 沖區(qū)的數(shù)據(jù)量在此級(jí)別或者更高時(shí)，讀取回調(diào)將被調(diào)用。默認(rèn)值為 0，所以每個(gè)讀取操作都會(huì)導(dǎo)致讀取回調(diào)被調(diào)用。 ?? 讀取高水位 ：輸入緩沖區(qū)中的數(shù)據(jù)量達(dá)到此級(jí)別后， bufferevent 將停止讀取，直到輸入緩沖區(qū)中足夠量的數(shù)據(jù)被抽取，使得數(shù)據(jù)量低于此級(jí)別。默認(rèn)值是無限，所以永遠(yuǎn)不會(huì)因?yàn)檩斎刖彌_區(qū)的大小而停止讀取。 ?? 寫入低水位 ：寫入操作使得輸出緩沖區(qū)的數(shù)據(jù)量達(dá)到或者低于此級(jí)別時(shí)，寫入回調(diào)將被調(diào)用。默認(rèn)值是 0，所以只有輸出緩沖區(qū)空的時(shí)候才會(huì)調(diào)用寫入回調(diào)。 ?? 寫入高水位 ： bufferevent 沒有直接使用這個(gè)水位。它 在 bufferevent 用作另外一個(gè)bufferevent的底層傳輸端口時(shí)有特殊意義。請(qǐng)看后面關(guān)于過濾型 bufferevent的介紹。 bufferevent 也有“錯(cuò)誤”或者“事件”回調(diào)，用于向應(yīng)用通知非面向數(shù)據(jù)的事件，如連接已經(jīng)關(guān)閉或者發(fā)生錯(cuò)誤。定義了下列事件標(biāo)志： ?? BEV_EVENT_READING：讀取操作時(shí)發(fā)生某事件，具體是哪種事件請(qǐng)看其他標(biāo)志。 ?? BEV_EVENT_WRITING：寫入操作時(shí)發(fā)生某事件，具體是哪種事件請(qǐng)看其他標(biāo)志。 ?? BEV_EVENT_ERROR ：操作時(shí)發(fā)生錯(cuò)誤。關(guān) 于 錯(cuò) 誤 的 更 多 信 息 ， 請(qǐng) 調(diào) 用EVUTIL_SOCKET_ERROR()。 ?? BEV_EVENT_TIMEOUT：發(fā)生超時(shí)。 ?? BEV_EVENT_EOF：遇到文件結(jié)束指示。 ?? BEV_EVENT_CONNECTED：請(qǐng)求的連接過程已經(jīng)完成。 上述標(biāo)志由 版新引入。 3 延遲回調(diào) 默認(rèn)情況下， bufferevent 的回調(diào)在相應(yīng)的條件發(fā)生時(shí)立即被執(zhí)行。（ evbuffer 的回調(diào)也是這樣的，隨后會(huì)介紹）在依賴關(guān)系復(fù)雜的情況下，這種立即調(diào)用會(huì)制造麻煩。比如說，假如某個(gè)回調(diào)在 evbuffer A 空 的時(shí)候向其中移入數(shù)據(jù)，而另一個(gè)回調(diào)在 evbuffer A 滿的時(shí)候從中取出數(shù)據(jù)。這些調(diào)用都是在棧上發(fā)生的，在依賴關(guān)系足夠復(fù)雜的時(shí)候，有棧溢出的風(fēng)險(xiǎn)。 要解決此問題，可以請(qǐng)求 bufferevent（或者 evbuffer）延遲其回調(diào)。條件滿足時(shí)，延遲回調(diào)不會(huì)立即調(diào)用，而是在 event_loop（）調(diào)用中被排隊(duì)，然后在通常的事件回調(diào)之后執(zhí)行。 （延遲回調(diào)由 libevent 版引入） 4 bufferevent 的選項(xiàng)標(biāo)志 創(chuàng)建 bufferevent 時(shí)可以使用一個(gè)或者多個(gè)標(biāo)志修改其行為?？勺R(shí)別的標(biāo) 志有： ?? BEV_OPT_CLOSE_ON_FREE：釋放 bufferevent 時(shí)關(guān)閉底層傳輸端口。這將關(guān)閉底層套接字，釋放底層 bufferevent 等。 ?? BEV_OPT_THREADSAFE：自動(dòng)為 bufferevent 分配鎖，這樣就可以安全地在多個(gè)線程中使用 bufferevent。 ?? BEV_OPT_DEFER_CALLBACKS：設(shè)置這個(gè)標(biāo)志時(shí)， bufferevent 延遲所有回調(diào)，如上所述。 ?? BEV_OPT_UNLOCK_CALLBACKS：默認(rèn)情況下，如果設(shè)置 bufferevent 為線程 安全的，則bufferevent 會(huì)在調(diào)用用戶提供的回調(diào)時(shí)進(jìn)行鎖定。設(shè)置這個(gè)選項(xiàng)會(huì)讓 libevent 在執(zhí)行回調(diào)的時(shí)候不進(jìn)行鎖定。 （ BEV_OPT_UNLOCK_CALLBACKS 由 版引入，其他選項(xiàng)由 版引入） 5 與基于套接字的 bufferevent 一起工作 基于套接字的 bufferevent 是最簡單的，它使用 libevent 的底層事件機(jī)制來檢測底層網(wǎng)絡(luò)套接字是否已經(jīng)就緒，可以進(jìn)行讀寫操作，并且使用底層網(wǎng)絡(luò)調(diào)用（如 readv、 writev、WSASend、 WSARecv）來發(fā)送和接收數(shù)據(jù)。 創(chuàng)建基于套接字的 bufferevent 可以使用 bufferevent_socket_new()創(chuàng)建基于套接字的 bufferevent。 接口 base 是 event_base， options 是表示 bufferevent 選項(xiàng)（ BEV_OPT_CLOSE_ON_FREE 等）的位掩碼， fd 是一個(gè)可選的表示套接字的文件描述符。如果想以后設(shè)置文件描述符，可以設(shè)置 fd 為 1。 成功時(shí)函數(shù)返回一個(gè) bufferevent，失敗則返回 NULL。 bufferevent_socket_new()函數(shù)由 版新引入。 在基于套接字的 bufferevent 上啟動(dòng)連接 如果 bufferevent 的套接字還沒有連接上，可以啟動(dòng)新的連接。 接口 address和 addrlen參數(shù)跟標(biāo)準(zhǔn)調(diào)用 connect()的參數(shù)相同。如果還沒有為 bufferevent設(shè)置套接字，調(diào)用函數(shù)將為其分配一個(gè)新的流套接字，并且設(shè)置為非阻塞的。 如果已經(jīng)為 bufferevent 設(shè)置套接字，調(diào)用 bufferevent_socket_connect()將告知libevent 套接字還未連接，直到連接成功之前不應(yīng)該對(duì)其進(jìn)行讀取或者寫入操作。 連接完成之前可以向輸出緩沖區(qū)添加數(shù)據(jù)。 如果連接成功啟動(dòng)，函數(shù)返回 0；如果發(fā)生錯(cuò)誤則返回 1。 示例 bufferevent_socket_connect()函數(shù)由 版引入。在此之前，必須自己手動(dòng)在套接字上調(diào)用 connect()，連接完成時(shí)， bufferevent 將報(bào)告寫入事件。 注意：如果使用 bufferevent_socket_connect() 發(fā)起連接，將只會(huì)收到BEV_EVENT_CONNECTED 事件。如果自己調(diào)用 connect()，則連接上將被報(bào)告為寫入事件。 這個(gè)函數(shù)在 版引入。 通過主機(jī)名啟動(dòng)連接 常常需要將解析主機(jī)名和連接到主機(jī)合并成單個(gè)操作， libevent 為此提供了： 接口 這個(gè)函數(shù)解析名字 hostname，查找其 family 類型的地址（允許的地址族類型有AF_INET,AF_INET6 和 AF_UNSPEC）。如果名字解析失敗，函數(shù)將調(diào)用事 件回調(diào)，報(bào)告錯(cuò)誤事件。如果解析成功，函數(shù)將啟動(dòng)連接請(qǐng)求，就像 bufferevent_socket_connect()一樣。 dns_base 參數(shù)是可選的：如果為 NULL，等待名字查找完成期間調(diào)用線程將被阻塞，而這通常不是期望的行為；如果提供 dns_base 參數(shù)， libevent 將使用它來異步地查詢主機(jī)名。關(guān)于 DNS 的更多信息，請(qǐng)看第九章。 跟 bufferevent_socket_connect()一樣，函數(shù)告知 libevent， bufferevent 上現(xiàn)存的套接字還沒有連接，在名字解析和連接操作成功完成之前 ，不應(yīng)該對(duì)套接字進(jìn)行讀取或者寫入操作。 函 數(shù) 返 回 的 錯(cuò) 誤 可 能 是 DNS 主 機(jī) 名 查 詢 錯(cuò) 誤 ， 可 以 調(diào) 用bufferevent_socket_get_dns_error()來獲取最近的錯(cuò)誤。返回值 0 表示沒有檢測到 DNS錯(cuò)誤。 示例：簡單的 HTTP v0 客戶端 6 通用 bufferevent 操作 本節(jié)描述的函數(shù)可用于多種 bufferevent 實(shí)現(xiàn)。 釋放 bufferevent 接口 這個(gè)函數(shù)釋放 bufferevent。 bufferevent 內(nèi)部具有引用計(jì)數(shù)，所以，如果釋放bufferevent 時(shí)還有未決的延 遲回調(diào)，則在回調(diào)完成之前 bufferevent 不會(huì)被刪除。 如果設(shè)置了 BEV_OPT_CLOSE_ON_FREE 標(biāo)志，并且 bufferevent 有一個(gè)套接字或者底層bufferevent 作為其傳輸端口，則釋放 bufferevent 將關(guān)閉這個(gè)傳輸端口。 這個(gè)函數(shù)由 libevent 版引入。 操作回調(diào)、水位和啟用 /禁用 接口 bufferevent_setcb()函數(shù)修改 bufferevent 的一個(gè)或者多個(gè)回調(diào)。 readcb、 writecb和 eventcb 函數(shù)將分別在已經(jīng)讀取足夠的數(shù)據(jù)、已經(jīng)寫 入足夠的數(shù)據(jù)，或者發(fā)生錯(cuò)誤時(shí)被調(diào)用。每個(gè)回調(diào)函數(shù)的第一個(gè)參數(shù)都是發(fā)生了事件的 bufferevent，最后一個(gè)參數(shù)都是調(diào)用bufferevent_setcb()時(shí)用戶提供的 cbarg 參數(shù)：可以通過它向回調(diào)傳遞數(shù)據(jù)。事件回調(diào)的events 參數(shù)是一個(gè)表示事件標(biāo)志的位掩碼：請(qǐng)看前面的“回調(diào)和水位”節(jié)。 要禁用回調(diào)，傳遞 NULL 而不是回調(diào)函數(shù)。 注意： bufferevent 的所有回調(diào)函數(shù)共享單個(gè) cbarg，所以修改它將影響所有回調(diào)函數(shù)。 這個(gè)函數(shù)由 版引入。類型名 bufferevent_data_cb 和 bufferevent_event_cb 由 版引入。 接口 可以啟用或者禁用 bufferevent 上的 EV_READ、 EV_WRITE 或者 EV_READ | EV_WRITE 事件。沒有啟用讀取或者寫入事件時(shí)， bufferevent 將不會(huì)試圖進(jìn)行數(shù)據(jù)讀取或者寫入。 沒有必要在輸出緩沖區(qū)空時(shí)禁用寫入事件： bufferevent 將自動(dòng)停止寫入，然后在有數(shù)據(jù)等待寫入時(shí)重新開始。 類似地，沒有必要在輸入緩沖區(qū)高于高水位時(shí)禁用讀取事件： bufferevent 將自動(dòng)停止讀取，然后在有空間用于讀取時(shí)重新開始 讀取。 默認(rèn)情況下，新創(chuàng)建的 bufferevent 的寫入是啟用的，但是讀取沒有啟用。 可以調(diào)用 bufferevent_get_enabled()確定 bufferevent 上當(dāng)前啟用的事件。 除了 bufferevent_get_enabled()由 ，這些函數(shù)都由 。 接口 bufferevent_setwatermark()函數(shù)調(diào)整單個(gè) bufferevent 的讀取水位、寫入水位，或者同時(shí)調(diào)整二者。（如果 events 參數(shù)設(shè)置了 EV_READ，調(diào)整讀取水位。如果