DosCreateSem
Bindings: C, MASM
This call creates a system semaphore used by multiple asynchronous threads
to serialize their access to resources.
DosCreateSem (NoExclusive, SemHandle, SemName)
NoExclusive (USHORT) - input
Indicates whether or not the process creating the semaphore wants
exclusive use of the semaphore. The meanings for the settings of this
flag are:
Value Definition
0 The creating process has exclusive use of the semaphore.
Only threads of the creating process may alter the state of
the semaphore with semaphore function calls.
1 The creating process has nonexclusive use of the semaphore.
Threads of other processes, as well as those of the creating
process, may alter the state of the semaphore with semaphore
function calls.
SemHandle (PHSYSSEM) - output
Address of handle of the new system semaphore.
SemName (PSZ) - input
Address of the name of the system semaphore. A system semaphore is
defined within the file system name space as a pseudo file; thus, a
semaphore has a full path name. The ASCIIZ string specifying the name
must include \SEM\ as the first element of the path. For example,
\SEM\RETRIEVE\SIGNAL.SEM is a valid semaphore name.
Although a system semaphore name takes the form of a file in a
subdirectory called \SEM, this subdirectory does not exist. System
semaphores and their names are kept in memory.
If your application provides long name support for an installable file
system, a semaphore name is not restricted to the DOS 8.3 filename
format.
rc (USHORT) - return
Return code descriptions are:
0 NO_ERROR
87 ERROR_INVALID_PARAMETER
100 ERROR_TOO_MANY_SEMAPHORES
123 ERROR_INVALID_NAME
183 ERROR_ALREADY_EXISTS
Remarks
A call to DosCreateSem creates a system semaphore, which can be
manipulated by threads issuing semaphore function calls. Manipulation of
a system semaphore is most often used to control access to a serially
reusable resource. Manipulation of the semaphore is also used to signal
the occurrence of an event to waiting threads.
To control access to a serially reusable resource, a process creates the
system semaphore with a call to DosCreateSem. If the users of the
resource are asynchronous threads of the creating process, NoExclusive=0
is specified to create an exclusive system semaphore. If the users of the
resource include threads of other processes, NoExclusive=1 is specified
to create a nonexclusive system semaphore.
DosCreateSem returns a semaphore handle used by the creating process and
any of its threads to access the semaphore. If the semaphore is
nonexclusive, a process other than the semaphore creator calls DosOpenSem
for a handle to access the semaphore.
Ownership of the system semaphore is established by a successful
DosSemRequest call. If another thread issues DosSemRequest while the
semaphore is owned, the thread can block and wait for the semaphore to
become available, or it can return immediately.
After accessing the resource, the owning thread can clear the semaphore
by a call to DosSemClear. If the semaphore is an exclusive system
semaphore, it has a use count associated with it, which is incremented by
DosSemRequest calls and decremented by DosSemClear calls. The semaphore
is not actually cleared and made available to the next thread waiting to
use the resource until the semaphore has been cleared the same number of
times it has been requested. This means that exclusive system semaphores
can be used in recursive routines.
If a process has created a nonexclusive system semaphore and terminates
while the semaphore is open, the system closes the handle to the
semaphore that was returned by DosCreateSem. If the process is currently
holding the semaphore when it terminates, OS/2 clears the semaphore and
returns ERROR_SEM_OWNER_DIED to the next thread that gets the resource
because of a DosSemRequest call. This error message alerts the holder of
the semaphore that the semaphore owner may have ended abnormally;
consequently, the resource is in an indeterminate state. The thread
should take appropriates steps to protect the integrity of the resource.
Upon completion of cleanup activity, the thread can release the
semaphore by calling DosSemClear. This call resets the error condition
flagged in the semaphore data structure and makes the semaphore available
to the next user of the resource. The semaphore remains available to all
processes that obtained handles to it with DosOpenSem requests until they
call DosCloseSem to release the semaphore handles.
If a process has created an exclusive system semaphore and terminates
while the semaphore is open, ownership of the semaphore is transferred to
the thread executing any exit list routines. If no exit list routines
have been identified to the system with DosExitList, the system closes
the handle to the semaphore.
In addition to controlling access to serially reusable resources, a
nonexclusive system semaphore is also used to signal an event, such as
the removal of an element from a queue, to other processes. A process
that sets the semaphore waits for another process to clear the semaphore,
signaling the event. When the signaling process issues a DosSemClear, any
waiting threads resume execution. Calls that support setting and waiting
upon a nonexclusive semaphore by one or more threads are DosSemSet,
DosSemWait, DosSemSetWait, and DosMuxSemWait.
Note: If a thread needs to signal another thread of the same process, a
RAM semaphore is used.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs