INtime SDK Help
knCreateRtSemaphore
INtime SDK v7 > About INtime > INtime Kernel > Semaphores > knCreateRtSemaphore

Creates 1 of 3 kinds of low-level semaphores with 0 or 1 initial units. FIFO and priority semaphores can contain as many as 65,535 units, which are placed in the semaphore by using multiple calls to knReleaseRtSemaphore, 1 call for each unit.

If a low-level region is created with 0 units, the creating thread holds the region's unit and is therefore the owning thread.

If a low-level region is created with 1 unit, no thread owns the region until it invokes knWaitForRtSemaphore for that region.

This call is non-scheduling and is safe, but not recommended, for use by interrupt handlers.

Note: From INtime version 6.2, for performance reasons, the area for each low-level semaphore or mailbox in a process is also mapped into common virtual memory. The default maximum number of pages reserved for low-level objects is 256. Low-level objects which share a page consume only one mapping between them. knCreateRtSemaphore will fail and return a value of 0xffffffff is the number of mappings is exceeded.

KNHANDLE knCreateRtSemaphore( KNPTR lpSemaporeArea, // pointer to low-level semaphore area DWORD dwSemaphoreFlags // low-level semaphore flags );

Parameters

lpSemaphoreArea
A pointer to the area where the semaphore is to be created. This area must be at least KN_SEMAPHORE_SIZE bytes long. For better performance, align the area on a 4-byte boundary.
dwSemaphoreFlags
Specifies the semaphore's attributes:
KN_EXCH_TYPE_MASK Masks the queuing strategy field. Choose one of the following:
KN_FIFO_QUEUING
The semaphore uses FIFO queuing.
KN_PRIORITY_QUEUING
The semaphore uses priority queuing.
KN_REGION
The exchange is a 1 (or single) unit region.
KN_INITIAL_SEM_STATE_MASK Masks the number of initial units the semaphore receives. Choose one of these literals:
KN_ZERO_UNITS
The semaphore is created with no units.
KN_ONE_UNIT
The semaphore is created with 1 unit.
Note:   
  • KN_FIFO_QUEUING , KN_PRIORITY_QUEUING , and KN_REGION are mutually exclusive.
  • KN_ZERO_UNITS and KN_ONE_UNIT are mutually exclusive.
  • You must OR multiple literals together to produce the dwSemaphoreFlags value passed by the call.

Return Values

Success: a handle for the low-level semaphore.

Failure: the value 0xffffffff is returned if the lpSemaporeArea pointer was not valid, or if the maximum number of semaphore mappings for the process has been exceeded.

Requirements

Versions Defined in Include Link to
INtime 3.0 intime/rt/include/rtbase.h rt.h rt.lib
See Also