osCreateSemaphore function

Declaration:

HANDLE osCreateSemaphore(
  SYSNAME Name,
  INDEX InitialCount,
  INDEX MaxCount
);

Parameters:

Name

The name of the semaphore object (can be NULL).

InitialCount

The initial value of the semaphore counter. If the initial value is less than the maximum value, the task creating the semaphore automatically acquires a number of units equal to the difference between InitialCount and MaxCount. If the values are equal, the semaphore is created in a fully available (signaled) state. InitialCount may only be less than MaxCount if the function is called from a task context. The function will fail if InitialCount is greater than MaxCount.

MaxCount

The maximum value the semaphore counter can reach.

Return value:

On success, the return value is a handle to the newly created semaphore object. On failure, the function returns NULL_HANDLE. To retrieve extended error information, call the osGetLastError function.

Description:

This function creates a semaphore object.

Semaphores are synchronization primitives used to manage access to critical sections. A code segment protected by a semaphore is restricted to execution by no more than a specified number of concurrent tasks.

Semaphores should be utilized when priority inversion protection is required. While robust applications should be designed to prevent priority inversion entirely, if its occurrence is impossible, it is more efficient to use faster counting semaphores instead. The memory footprint of a semaphore object depends on the maximum number of tasks that can concurrently hold or wait for it.

During creation, an optional name may be assigned to the semaphore, enabling other tasks to open it via the osOpenSemaphore function. When a semaphore handle is no longer required, it should be closed using osCloseHandle. The semaphore object is deleted only after all tasks that opened the handle have closed it. Further details are available in the system objects management section.

If no osOpen* functions are referenced in the application, the system ignores object names and excludes the name management logic from the build to reduce the final binary size. For more information regarding object naming and opening, see the system objects management section.

If the InitialCount is set to a value less than MaxCount, the task creating the semaphore will immediately occupy the number of slots representing the difference. This behavior is only permitted when the function is called from a task context. For detailed information regarding semaphore acquisition, please refer to the semaphore objects section.

This function is available only when the OS_USE_SEMAPHORE configuration constant is set to 1.

Version:	1.0
Header file:	OS_Semaphore.h (include OS_API.h)
See also:	HANDLE, INDEX, NULL, NULL_HANDLE, OS_OPEN_SEMAPHORE_FUNC, osCloseHandle, osGetLastError, osOpenSemaphore, semaphores, SYSNAME, system objects management,

SpaceShadow documentation