ReleaseSemaphore-Funktion (synchapi.h)

  • Artikel

Erhöht die Anzahl des angegebenen Semaphorobjekts um einen angegebenen Betrag.

Syntax

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

Parameter

[in] hSemaphore

Ein Handle für das Semaphorobjekt. Die Funktion CreateSemaphore oder OpenSemaphore gibt dieses Handle zurück.

Dieses Handle muss über das zugriffsrecht SEMAPHORE_MODIFY_STATE verfügen. Weitere Informationen finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsrechte.

[in] lReleaseCount

Der Betrag, um den die aktuelle Anzahl des Semaphorobjekts erhöht werden soll. Der Wert muss größer als 0 (null) sein. Wenn die angegebene Menge dazu führen würde, dass die Anzahl des Semaphors die maximale Anzahl überschreitet, die beim Erstellen des Semaphors angegeben wurde, wird die Anzahl nicht geändert, und die Funktion gibt FALSE zurück.

[out, optional] lpPreviousCount

Ein Zeiger auf eine Variable, um die vorherige Anzahl des Semaphors zu empfangen. Dieser Parameter kann NULL sein, wenn die vorherige Anzahl nicht erforderlich ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Der Zustand eines Semaphorobjekts wird signalisiert, wenn seine Anzahl größer als null und nicht signalisiert ist, wenn seine Anzahl gleich 0 ist. Der Prozess, der die CreateSemaphore-Funktion aufruft , gibt die anfängliche Anzahl des Semaphors an. Jedes Mal, wenn ein wartenden Thread aufgrund des signalisierten Zustands des Semaphors freigegeben wird, wird die Anzahl des Semaphors um eins verringert.

In der Regel verwendet eine Anwendung einen Semaphor, um die Anzahl von Threads zu begrenzen, die eine Ressource verwenden. Bevor ein Thread die Ressource verwendet, gibt er das Semaphorhandle in einem Aufruf einer der Wartefunktionen an. Wenn die Wartefunktion zurückgibt, verringert sie die Anzahl des Semaphors um eins. Wenn der Thread die Ressource verwendet hat, ruft er ReleaseSemaphore auf, um die Anzahl des Semaphors um eins zu erhöhen.

Eine andere Verwendung von ReleaseSemaphore erfolgt während der Initialisierung einer Anwendung. Die Anwendung kann ein Semaphor mit einer anfänglichen Anzahl von 0 erstellen. Dadurch wird der Zustand des Semaphors auf nicht signalisiert festgelegt, und alle Threads können nicht auf die geschützte Ressource zugreifen. Wenn die Anwendung ihre Initialisierung abgeschlossen hat, verwendet sie ReleaseSemaphore , um die Anzahl auf ihren maximalen Wert zu erhöhen, um den normalen Zugriff auf die geschützte Ressource zu ermöglichen.

Es ist nicht möglich, die Anzahl des Semaphorobjekts mit ReleaseSemaphore zu reduzieren, da lReleaseCount keine negative Zahl sein kann. Um den Zugriff vorübergehend einzuschränken oder zu reduzieren, erstellen Sie eine Schleife, in der Sie die WaitForSingleObject-Funktion mit einem Timeoutintervall von 0 0 aufrufen, bis die Semaphoranzahl ausreichend reduziert wurde. (Beachten Sie, dass andere Threads die Anzahl reduzieren können, während diese Schleife ausgeführt wird.) Um den Zugriff wiederherzustellen, rufen Sie ReleaseSemaphore auf, wobei die Releaseanzahl der Anzahl der Aufrufe von WaitForSingleObject in der Schleife entspricht.

Beispiele

Ein Beispiel, das ReleaseSemaphore verwendet, finden Sie unter Verwenden von Semaphorobjekten.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile synchapi.h (einschließlich Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

CreateSemaphor

OpenSemaphor

Semaphorobjekte

Synchronisierungsfunktionen