libevent中文參考手冊(編輯修改稿)

　

【文章內容簡介】 性。 接口 除了 evtimer_new（）首次出現在 版本中之外，這些宏從 版本就存在了。 構造信號事件 libevent 也可以監測 POSIX 風格的信號。要構造信號處理器，使用： 接口 除了提供一個信號編號代替文件描述符之外，各個參數與 event_new（）相同。 示例 注意 ：信號回調是信號發生后在事件循環中被執行的，所以可 以安全地調用通常不能在POSIX 風格信號處理器中使用的函數。 警告：不要在信號事件上設置超時，這可能是不被支持的。 [待修正：真是這樣的嗎？ ] libevent 也提供了一組方便使用的宏用于處理信號事件： 接口 evsignal_*宏從 版本開始存在。先前版本中這些宏叫做 signal_add（）、signal_del（）等等。 關于信號的警告 在當前版本的 libevent 和大多數后端中，每個進程任何時刻只能有一個 event_base可以監聽信號。如果同時向兩個 event_base 添加信號 事件，即使是不同的信號，也只有一個 event_base 可以取得信號。 kqueue 后端沒有這個限制。 設置不使用堆分配的事件 出于性能考慮或者其他原因，有時需要將事件作為一個大結構體的一部分。對于每個事件的使用，這可以節省： ?? 內存分配器在堆上分配小對象的開銷 ?? 對 event 結構體指針取值的時間開銷 ?? 如果事件不在緩存中，因為可能的額外緩存丟失而導致的時間開銷 對于大多數應用來說，這些開銷是非常小的。所以，除非確定在堆上分配事件導致了嚴重的性能問題，應該堅持使用 event_new（）。如果將來 版本中的 event 結構體更大，不使用 event_new（）可能會導致難以診斷的錯誤。 不在堆上分配 event 具有破壞與其他版本 libevent 二進制兼容性的風險：其他版本中的 event 結構體大小可能不同。 接口 除了 event 參數必須指向一個未初始化的事件之外， event_assign（）的參數與event_new（）的參數相同。成功時函數返回 0，如果發生內部錯誤或者使用錯誤的參數，函數返回 1。 示例 也可以用 event_assign（）初始化棧上分配的，或者靜態分配的事件。 警告 不要對已經在 event_base 中未決的事件調用 event_assign（），這可能會導致難以診斷的錯誤。如果已經初始化和成為未決的，調用 event_assign（）之前需要調用 event_del（）。 libevent 提供了方便的宏將 event_assign（）用于僅超時事件或者信號事件。 接口 如果需要使用 event_assign（），又要保持與將來版本 libevent 的二進制兼容性，可以請求 libevent 告知 struct event 在運行時應該有多大： 接口 這個函數返回需要為 event 結構體保留的字節數 。再次強調，只有在確信堆分配是一個嚴重的性能問題時才應該使用這個函數，因為這個函數讓代碼難以閱讀和編寫。 注意，將來版本的 event_get_struct_event_size()的返回值可能比 sizeof(struct event)小，這表示 event 結構體末尾的額外字節僅僅是保留用于將來版本 libevent 的填充字節。 下面這個例子跟上面的那個相同，但是不依賴于 中的 event 結構體的大小，而是使用 event_get_struct_size（）來獲取運行時的正確大小。 示例 event_assign（）定義在 event2/中，從 版本開始就存在了。從 版 本 開 始 ， 函 數 返 回 int ， 在 這 之 前 函 數 返 回 void 。event_get_struct_event_size（）在 版本中引入。 event 結構體定義在event2/中。 2 讓事件未決和非未決 構造事件之后，在將其添加到 event_base 之前實際上是不能對其做任何操作的。使用event_add（）將事件添加到 event_base。 接口 在非未決的事件上調用 event_add（）將使其在配置的 event_base 中成為未決的。成功時函數返回 0，失敗時返回 1。如果 tv 為 NULL，添加的事件不會超時。否則， tv 以秒和微秒指定超時值。 如果對已經未決的事件調用 event_add（），事件將保持未決狀態，并在指定的超時時間被重新調度。 注意 ：不要設置 tv 為希望超時事件執行的時間。如果在 2020 年 1 月 1 日設置“ tvtv_sec=time(NULL)+10。”，超時事件將會等待 40 年，而不是 10 秒。 接口 對已經初始 化的事件調用 event_del（）將使其成為非未決和非激活的。如果事件不是未決的或者激活的，調用將沒有效果。成功時函數返回 0，失敗時返回 1。 注意 ：如果在事件激活后，其回調被執行前刪除事件，回調將不會執行。 這些函數定義在 event2/中，從 版本就存在了。 3 帶優先級的事件 多個事件同時觸發時， libevent 沒有定義各個回調的執行次序。可以使用優先級來定義某些事件比其他事件更重要。 在前一章討論過，每個 event_base 有與之相關的一個或者多個優先級。在初始化事件之后，但是在 添加到 event_base 之前，可以為其設置優先級。 接口 事件的優先級是一個在 0 和 event_base 的優先級減去 1 之間的數值。成功時函數返回0，失敗時返回 1。 多個不同優先級的事件同時成為激活的時候，低優先級的事件不會運行。 libevent 會執行高優先級的事件，然后重新檢查各個事件。只有在沒有高優先級的事件是激活的時候，低優先級的事件才會運行。 示例 如果不為事件設置優先級，則默認的優先級將會是 event_base 的優先級數目除以 2。 這個函數聲明在 event2/中，從 版本就存在了。 4 檢查事件狀態 有時候需要了解事件是否已經添加，檢查事件代表什么。 接口 event_pending（）函數確定給定的事件是否是未決的或者激活的。如果是，而且 what參數設置了 EV_READ、 EV_WRITE、 EV_SIGNAL 或者 EV_TIMEOUT 等標志，則函數會返回事件當前為之未決或者激活的所有標志。如果提供了 tv_out 參數，并且 what 參數中設置了EV_TIMEOUT 標志，而事件當前正因超時事件而未決或者激活，則 tv_out 會返回事件的超時值。 event_get_fd（）和 event_get_signal（）返回為事件配置的文件描述符或者信號值。event_get_base（）返回為事件配置的 event_base。 event_get_events（）返回事件的標志（ EV_READ、 EV_WRITE 等）。 event_get_callback（）和 event_get_callback_arg（）返回事件的回調函數及其參數指針。 event_get_assignment（）復制所有為事件分配的字段到提供的指針中。任何為 NULL的參數會被忽略。 示例 這些函數聲明在 event2/中。 event_pending（）函數從 版就存在了。 版引入了 event_get_fd（）和 event_get_signal（）。 引入了event_get_base（）。其他的函數在 版中引入。 5 配置一次觸發事件 如果不需要多次添加一個事件，或者要在添加后立即刪除事件，而事件又不需要是持久的，則可以使用 event_base_once（）。 接口 除了不支持 EV_SIGNAL 或者 EV_PERSIST 之外，這個函數的接 口與 event_new（）相同。安排的事件將以默認的優先級加入到 event_base 并執行。回調被執行后， libevent 內部將會釋放 event 結構。成功時函數返回 0，失敗時返回 1。 不能刪除或者手動激活使用 event_base_once（）插入的事件：如果希望能夠取消事件，應該使用 event_new（）或者 event_assign（）。 6 手動激活事件 極少數情況下，需要在事件的條件沒有觸發的時候讓事件成為激活的。 接口 這個函數讓事件 ev 帶有標志 what（ EV_READ、 EV_WRITE和 EV_TIMEOUT 的組合）成為激活的。事件不需要已經處于未決狀態，激活事件也不會讓它成為未決的。 這個函數定義在 event2/中，從 版本就存在了。 7 優化公用超時 當前版本的 libevent 使用二進制堆算法跟蹤未決事件的超時值，這讓添加和刪除事件超時值具有 O(logN)性能。對于隨機分布的超時值集合，這是優化的，但對于大量具有相同超時值的事件集合，則不是。 比如說，假定有 10000 個事件，每個都需要在添加后 5 秒觸發超時事件。這種情況下，使用雙鏈隊列實現才可以取得 O（ 1）性能。 自然地， 不希望為所有超時值使用隊列，因為隊列僅對常量超時值更快。如果超時值或多或少地隨機分布，則向隊列添加超時值的性能將是 O（ n），這顯然比使用二進制堆糟糕得多。 libevent 通過放置一些超時值到隊列中，另一些到二進制堆中來解決這個問題。要使用這個機制，需要向 libevent 請求一個“ 公用超時 (mon timeout)”值，然后使用它來添加事件。如果有大量具有單個公用超時值的事件，使用這個優化應該可以改進超時處理性能。 接口 這個函數需要 event_base 和要初始化的公用超時值作為參數。函數返回一個 到特別的timeval結構體的指針，可以使用這個指針指示事件應該被添加到 O（ 1）隊列，而不是 O（ logN）堆。可以在代碼中自由地復制這個特別的 timeval 或者進行賦值，但它僅對用于構造它的特定 event_base 有效。不能依賴于其實際內容： libevent 使用這個內容來告知自身使用哪個隊列。 示例 與所有優化函數一樣，除非確信適合使用，應該避免使用公用超時功能。 這個函數由 版本引入。 8 從已清除的內存識別事件 libevent 提供了函數，可以從已經通過設置為 0（比如說，通過 calloc（）分配的，或者使用 memset（）或者 bzero（）清除了的）而清除的內存識別出已初始化的事件。 接口 警告 這個函數不能可靠地從沒有初始化的內存塊中識別出已經初始化的事件。除非知道被查詢的內存要么是已清除的，要么是已經初始化為事件的，才能使用這個函數。 除非編寫一個非常特別的應用，通常不需要使用這個函數。 event_new（）返回的事件總是已經初始化的。 示例 event_initialized（）函數從 版本就存在了。 9 廢棄的事件操作函數 版本之前的 libevent 沒有 event_assign（）或者 event_new（）。替代的是將事件關聯到“當前” event_base 的 event_set（）。如果有多個 event_base，需要記得調用event_base_set（）來確定事件確實是關聯到當前使用的 event_base 的。 接口 除了使用當前 event_base 之外， event_set（）跟 event_assign（）是相似的。event_base_set（）用于修改事件所關聯到的 event_base。 event_set（）具有一些用于更方便地處理定時器和信號的變 體： evtimer_set（）大致對應 evtimer_assign（）； evsignal_set（）大致對應 evsignal_assign（）。 版本之前的 libevent 使用“ signal_”作為用于信號的 event_set（）等函數變體的前綴，而不是“ evsignal_”（也就是說，有 signal_set()、 signal_add()、 signal_del()、signal_pending()和 signal_initialized()）。遠古版本 ( 版之前 )的 libevent 使用“ timeout_”而不是“ evtimer_”。因此，做代碼考古（ code archeology）（注：這個翻譯似乎不正確，是否有更專業的術語？比如說，“代碼復審”）時可能會看到 timeout_add()、timeout_del()、 timeout_initialized()、 timeout_set()和 timeout_pending()等等。 較老版本（ 版之前）的 libevent 用宏 EVENT_FD()和 EVENT_SIGNAL()代表現在的event_get_fd()和 event_get_signal()函數。 這兩個宏直接檢查 event 結構體的內容，所以會妨礙不同版本之間的二進制兼容性。在 以及后續版本中，這兩個宏僅僅是event_get_fd()和 event_get_signal()的別名。 因為 之前的版本不支持鎖，所