C/C++ User's Journal & Wi…eveloper's Journal Tools/C-C__Users_Journal_and_Windows_Developers_Journal_Tools_1997.iso/sysembed/mutex.edh

Text File | 1995-03-30 | 5.1 KB | 165 lines

[ 7. Mutual Exclusion Semaphores]
                     EMBEDDED DOS MUTEX SEMAPHORES
════════════════════════════════════════════════════════════════════════
The mutex object implements a mutual exclusion semaphore that is also
MP-safe in multiprocessor systems.  Mutex objects are allocated and
deallocated in the same way that events are.  They are acquired and
released as needed to guard a critical section.  A mutex is assigned
a state, and must always be in either the acquired or released states.

Mutexes may be used to control exclusive access to any object that they
are associated with.  For example, the disk BIOS may be assigned a mutex
that disallows more than one request at a time from being submitted to
the BIOS.  Similarly, a mutex can be used to guard a software object,
such as a data structure.

Mutexes should not be acquired at interrupt time, because an interrupt
occurs during the context of some arbitrary thread.  To acquire a mutex
in response to an interrupt, a secondary thread may be created or
unblocked on the fly at interrupt time so as to define a thread that
can acquire the mutex and perform the guarded work.

1.  AllocateMutex

A mutex object is created with the AllocateMutex kernel function.
Once the mutex is allocated, it is automatically maintained by
the kernel in response to service requests.

This function returns a handle to a mutex object that must be used
by the caller in subsequent kernel services that operate on mutexes.
The kernel initializes the mutex object to the released state.

Upon return, the macro instruction call clears the carry flag if
the operation was successful, and sets it if the operation was
not performed.

Assembly Language Format:

     mov  dl, SYS_ALLOCATE_MUTEX
     int  2dh                   ; (AX) = handle to mutex.
     jc   Failure

Macro Instruction Format:

label     AllocateMutex  <MutexHandle>

Portable Request Format:

STATUS AllocateMutex(
     OUT PHANDLE MutexHandle
     );

Parameters:

     MutexHandle - Specifies a 16-bit general purpose register or
          a pointer to a word in memory where the kernel will
          return a handle to the allocated mutex.

2.  DeallocateMutex

A mutex object is destroyed with the DeallocateMutex kernel
function.  Once the mutex is deallocated, it is no longer
available to the caller, and the handle becomes invalid.

If a mutex is deallocated that has one or more threads still
blocked trying to acquire it, those threads are automatically
destroyed by the kernel.

Upon return, the macro instruction call clears the carry flag if
the operation was successful, and sets it if the operation was
not performed.

Assembly Language Format:

     mov  ax, <MutexHandle>     ; (AX) = mutex handle.
     mov  dl, SYS_DEALLOCATE_MUTEX
     int  2dh
     jc   Failure

Macro Instruction Format:

label     DeallocateMutex     <MutexHandle>

Portable Request Format:

STATUS DeallocateMutex(
     IN HANDLE MutexHandle
     );

Parameters:

     MutexHandle - Specifies a 16-bit general purpose register or
          a word in memory containing a handle to the mutex to be
          deallocated.

3.  AcquireMutex

A mutex object is set to the acquired state with the AcquireMutex
kernel function.  Once the mutex is acquired, other threads will
block on any further attempts to acquire the mutex until the
first thread releases the mutex.

Upon return, the macro instruction call clears the carry flag if
the operation was successful, and sets it if the operation was
not performed.

Assembly Language Format:

     mov  ax, <MutexHandle>     ; (AX) = mutex handle.
     mov  dl, SYS_ACQUIRE_MUTEX
     int  2dh
     jc   Failure

Macro Instruction Format:

label     AcquireMutex   <MutexHandle>

Portable Request Format:

STATUS AcquireMutex(
     IN HANDLE MutexHandle
     );

Parameters:

     MutexHandle - Specifies a 16-bit general purpose register or
          a word in memory containing a handle to the mutex to be
          acquired.

4.  ReleaseMutex

A mutex object is set to the released state with the ReleaseMutex
kernel function.  Once the mutex is released, the kernel returns
to the caller.  Additionally, if there is at least one thread
blocked on the mutex waiting to acquire it, then the kernel
leaves the mutex in the acquired state and unblocks the next
thread waiting to acquire it.  If there are no other threads
waiting to acquire the mutex, then the kernel resets it to the
released state.

Upon return, the macro instruction call clears the carry flag if
the operation was successful, and sets it if the operation was
not performed.

Assembly Language Format:

     mov  ax, <MutexHandle>     ; (AX) = handle to mutex.
     mov  dl, SYS_RELEASE_MUTEX
     int  2dh
     jc   Failure

Macro Instruction Format:

label     ReleaseMutex   <MutexHandle>

Portable Request Format:

STATUS ReleaseMutex(
     IN HANDLE MutexHandle
     );

Parameters:

     MutexHandle - Specifies a 16-bit general purpose register or
          a word in memory containing a handle to the mutex to be
          released.