Función ReleaseSemaphore (synchapi.h)

Artículo
03/08/2023

Aumenta el recuento del objeto semáforo especificado por una cantidad especificada.

Sintaxis

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

Parámetros

[in] hSemaphore

Identificador del objeto semáforo. La función CreateSemaphore o OpenSemaphore devuelve este identificador.

Este identificador debe tener el derecho de acceso SEMAPHORE_MODIFY_STATE . Para obtener más información, vea Seguridad de objetos de sincronización y derechos de acceso.

[in] lReleaseCount

Cantidad por la que se va a aumentar el recuento actual del objeto semáforo. El valor debe ser mayor que cero. Si la cantidad especificada haría que el recuento del semáforo superara el recuento máximo que se especificó cuando se creó el semáforo, el recuento no se cambia y la función devuelve FALSE.

[out, optional] lpPreviousCount

Puntero a una variable para recibir el recuento anterior del semáforo. Este parámetro puede ser NULL si no se requiere el recuento anterior.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

El estado de un objeto semáforo se señala cuando su recuento es mayor que cero y no se asigna cuando su recuento es igual a cero. El proceso que llama a la función CreateSemaphore especifica el recuento inicial del semáforo. Cada vez que se libera un subproceso en espera debido al estado señalado del semáforo, el recuento del semáforo se reduce en uno.

Normalmente, una aplicación usa un semáforo para limitar el número de subprocesos mediante un recurso. Antes de que un subproceso use el recurso, especifica el identificador de semáforo en una llamada a una de las funciones de espera. Cuando se devuelve la función wait, disminuye el recuento del semáforo en uno. Cuando el subproceso haya terminado de usar el recurso, llama a ReleaseSemaphore para aumentar el recuento del semáforo en uno.

Otro uso de ReleaseSemaphore es durante la inicialización de una aplicación. La aplicación puede crear un semáforo con un recuento inicial de cero. Esto establece el estado del semáforo en no asignado y impide que todos los subprocesos accedan al recurso protegido. Cuando la aplicación finaliza su inicialización, usa ReleaseSemaphore para aumentar el recuento a su valor máximo, para permitir el acceso normal al recurso protegido.

No es posible reducir el recuento de objetos semáforos mediante ReleaseSemaphore, porque lReleaseCount no puede ser un número negativo. Para restringir o reducir temporalmente el acceso, cree un bucle en el que llame a la función WaitForSingleObject con un intervalo de tiempo de espera de cero hasta que el recuento de semáforos se haya reducido lo suficiente. (Tenga en cuenta que otros subprocesos pueden reducir el recuento mientras se ejecuta este bucle). Para restaurar el acceso, llame a ReleaseSemaphore con el recuento de versiones igual al número de veces que se llamó a WaitForSingleObject en el bucle.

Ejemplos

Para obtener un ejemplo que usa ReleaseSemaphore, vea Uso de objetos semaphore.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	synchapi.h (incluye Windows.h en Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll