1. 程式人生 > >翻譯:Libevent參考手冊第一章:設定libevent (三) (轉)

翻譯:Libevent參考手冊第一章:設定libevent (三) (轉)

evthread_lock_callbacks結構體描述的鎖回撥函式及其能力。對於上述版本,lock_api_version欄位必須設定為EVTHREAD_LOCK_API_VERSION。必須設定supported_locktypes欄位為EVTHREAD_LOCKTYPE_*常量的組合以描述支援的鎖型別(在2.0.4-alpha版本中,EVTHREAD_LOCK_RECURSIVE是必須的,EVTHREAD_LOCK_READWRITE則沒有使用)。alloc函式必須返回指定型別的新鎖;free函式必須釋放指定型別鎖持有的所有資源;lock函式必須試圖以指定模式請求鎖定,如果成功則返回0,失敗則返回非零;unlock函式必須試圖解鎖,成功則返回0,否則返回非零。

可識別的鎖型別有:

v 0:通常的,不必遞迴的鎖。

v EVTHREAD_LOCKTYPE_RECURSIVE:不會阻塞已經持有它的執行緒的鎖。一旦持有它的執行緒進行原來鎖定次數的解鎖,其他執行緒立刻就可以請求它了。

v EVTHREAD_LOCKTYPE_READWRITE:可以讓多個執行緒同時因為讀而持有它,但是任何時刻只有一個執行緒因為寫而持有它。寫操作排斥所有讀操作。

可識別的鎖模式有:

v EVTHREAD_READ:僅用於讀寫鎖:為讀操作請求或者釋放鎖

v EVTHREAD_WRITE:僅用於讀寫鎖:為寫操作請求或者釋放鎖

v EVTHREAD_TRY:僅用於鎖定:僅在可以立刻鎖定的時候才請求鎖定

id_fn引數必須是一個函式,它返回一個無符號長整數,標識呼叫此函式的執行緒。對於相同執行緒,這個函式應該總是返回同樣的值;而對於同時呼叫該函式的不同執行緒,必須返回不同的值。

evthread_condition_callbacks結構體描述了與條件變數相關的回撥函式。對於上述版本,condition_api_version欄位必須設定為EVTHREAD_CONDITION_API_VERSION。alloc_condition函式必須返回到新條件變數的指標。它接受0作為其引數。free_condition函式必須釋放條件變數持有的儲存器和資源。wait_condition函式要求三個引數:一個由alloc_condition分配的條件變數,一個由你提供的evthread_lock_callbacks.alloc函式分配的鎖,以及一個可選的超時值。呼叫本函式時,必須已經持有引數指定的鎖;本函式應該釋放指定的鎖,等待條件變數成為授信狀態,或者直到指定的超時時間已經流逝(可選)。wait_condition應該在錯誤時返回-1,條件變數授信時返回0,超時時返回1。返回之前,函式應該確定其再次持有鎖。最後,signal_condition函式應該喚醒等待該條件變數的某個執行緒(broadcast引數為false時),或者喚醒等待條件變數的所有執行緒(broadcast引數為true時)。只有在持有與條件變數相關的鎖的時候,才能夠進行這些操作。

關於條件變數的更多資訊,請檢視pthreads的pthread_cond_*函式文件,或者Windows的CONDITION_VARIABLE(Windows Vista新引入的)函式文件。

示例

關於使用這些函式的示例,請檢視Libevent原始碼釋出版本中的evthread_pthread.c和evthread_win32.c檔案。

這些函式在<event2/thread.h>中宣告,其中大多數在2.0.4-alpha版本中首次出現。2.0.1-alpha到2.0.3-alpha使用較老版本的鎖函式。event_use_pthreads函式要求程式連結到event_pthreads庫。

條件變數函式是2.0.7-rc版本新引入的,用於解決某些棘手的死鎖問題。

可以建立禁止鎖支援的libevent。這時候已建立的使用上述執行緒相關函式的程式將不能執行。

5 除錯鎖的使用

為幫助除錯鎖的使用,libevent有一個可選的“鎖除錯”特徵。這個特徵包裝了鎖呼叫,以便捕獲典型的鎖錯誤,包括:

v 解鎖並沒有持有的鎖

v 重新鎖定一個非遞迴鎖

如果發生這些錯誤中的某一個,libevent將給出斷言失敗並且退出。

介面