ReleaseSemaphore 函式 (synchapi.h)

  • 發行項

依指定的數量增加指定旗號物件的計數。

語法

BOOL ReleaseSemaphore(
  [in]            HANDLE hSemaphore,
  [in]            LONG   lReleaseCount,
  [out, optional] LPLONG lpPreviousCount
);

參數

[in] hSemaphore

旗號物件的句柄。 CreateSemaphore 或 OpenSemaphore 函式會傳回此句柄。

此句柄必須具有 SEMAPHORE_MODIFY_STATE 訪問許可權。 如需詳細資訊，請參閱 同步處理物件安全性和訪問許可權。

[in] lReleaseCount

要增加旗號物件目前計數的數量。 此值必須大於零。 如果指定的數量會導致旗號的計數超過建立旗號時所指定的計數上限，則計數不會變更，而且函式會傳回 FALSE。

[out, optional] lpPreviousCount

要接收信號先前計數之變數的指標。 如果不需要先前的計數，這個參數可以是 NULL 。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

當旗號物件的計數大於零，且當計數等於零時，會發出訊號。 呼叫 CreateSemaphore 函式的程式會指定旗號的初始計數。 每次因為信號的訊號狀態而釋放等候線程時，旗號的計數會減少一個。

一般而言，應用程式會使用旗號來限制使用資源的線程數目。 在線程使用資源之前，它會在呼叫其中一個 等候函式中指定旗號句柄。 當等候函式傳回時，它會將旗號的計數減少一個。 當線程使用完資源時，它會呼叫 ReleaseSemaphore 來增加信號的計數一次。

ReleaseSemaphore 的另一個用法是在應用程式的初始化期間。 應用程式可以建立初始計數為零的旗號。 這會將旗號的狀態設定為非簽署，並封鎖所有線程存取受保護的資源。 當應用程式完成初始化時，它會使用 ReleaseSemaphore 將計數增加到其最大值，以允許對受保護資源的正常存取。

無法使用 ReleaseSemaphore 來減少旗號對象計數，因為 lReleaseCount 不能是負數。 若要暫時限制或減少存取權，請建立迴圈，在其中呼叫 WaitForSingleObject 函式，其時間間隔為零，直到旗號計數已足夠減少為止。 (請注意，當執行此迴圈時，其他線程可以減少計數。) 若要還原存取，請呼叫 ReleaseSemaphore ，其發行計數等於在迴圈中呼叫 WaitForSingleObject 的次數。

範例

如需使用 ReleaseSemaphore 的範例，請參閱 使用旗號物件。

規格需求

需求 值
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 synchapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CreateSemaphore

OpenSemaphore

旗號物件

同步處理函式