mutex_lock() — Apollo

MUTEX_$LOCK                       Domain/OS                        MUTEX_$LOCK


NAME
     mutex_$lock - obtain a mutual exclusion lock

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/mutex.h>

     boolean mutex_$lock(
          mutex_$lock_rec_t *lock_record,
          time_$clock_t &wait_time)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/mutex.ins.pas';

     function mutex_$lock(
          var lock_record: mutex_$lock_rec_t;
          in wait_time: univ time_$clock_t): boolean;

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/mutex.ins.ftn'

           integer*2 wait_time(3), lock_record(4)
           integer*2 lock_ec_awaiters, clockh
           integer*4 lock_ec_value, clockl
           character*1 lock_byte
           logical lock_status

           equivalence (lock_byte, lock_record(1))
           equivalence (lock_ec_value, lock_record(2))
           equivalence (lock_ec_awaiters, lock_record(4))
           equivalence (clockh, wait_time(1))
           equivalence (clockl, wait_time(2))

           lock_status =  mutex_$lock(lock_record, wait_time)

DESCRIPTION
     Mutex_$lock requests a mutual exclusion lock on the object associated
     with lock_record.  If the lock is already held, mutex_$lock will keep the
     lock request pending for the interval defined by wait_time before return-
     ing.  If the calling process obtained the lock, mutex_$lock returns true.
     If mutex_$lock times out without obtaining the lock, it returns false.

     Before calling mutex_$lock, a process must map the file containing the
     lock record with ms_$cowriters concurrency and ms_$wr access.

     lock_record
          The mutual exclusion lock record for the object the lock is
          requested for.

     wait_time
          The length of time to wait for the lock before returning.  If
          mutex_$lock cannot obtain the lock within the specified time, it
          will return false.

          Set wait_time to mutex_$wait_forever to prevent mutex_$lock from
          timing out.

NOTES
     Note that the use of mutex_$lock and mutex_$unlock is a convention that
     cooperating programs use to control access to a shared object.  A process
     may ignore a mutual exclusion lock, or may indeed be unaware of the lock-
     ing mechanism, and access the object directly as long as it has permis-
     sion to do so.

SEE ALSO
     ms_$mapl.
Museum
