PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Provide mutex handling routines.

VMS FORMAT

status = PMDF_set_mutex

(create, lock, unlock, delete, sleep)

C FORMAT

status = PMDFsetMutex

(create, lock, unlock, delete, sleep)

int PMDFsetMutex (create, lock, unlock, delete, sleep) 
         int  (*create)(); 
         int  (*lock)(); 
         int  (*unlock)(); 
         int  (*delete)(); 
         void (*sleep)(); 

ARGUMENTS

create

Address of a procedure to create a mutex.

lock

Address of a procedure to lock a mutex.

unlock

Address of a procedure to unlock a mutex.

delete

Address of a procedure to delete a mutex.

sleep

Address of a procedure to sleep the specified number of hundreths of a second.

DESCRIPTION

The PMDF API and underlying routines are re-entrant and thread-safe. Multithreaded routines which will be using the PMDF API must call PMDF_set_mutex before calling any other API routines, including PMDF_initialize. The procedures passed to PMDF_set_mutex are then used by PMDF to manage thread mutexes and efficiently sleep a thread. The procedures referenced by create, lock, unlock, and delete each perform the mutex operation implied by their name:

• create: Create and initialize a mutex.
• lock: Block other threads wishing to use the mutex.
• unlock: Allow other threads to use the mutex.
• delete: Destroy the mutex and free up any memory associated with it.

Each of the four routines accept a single parameter which is the address of a pointer to a thread mutex. That is, if a thread mutex is the structure MUTEX then the routines would be declared in C as

int create (struct MUTEX **mutex) 
int lock (struct MUTEX **mutex) 
int unlock (struct MUTEX **mutex) 
int delete (struct MUTEX **mutex) 

The mutex creation routine should create the mutex, initialize it, and return the address of the mutex. The integer return value should be 0. It is not presently used by PMDF, but is provided for compatability with POSIX Threads mutex routines. For example,

int create (struct MUTEX **mutex) 
{ 
    struct MUTEX *mtx; 
 
    mtx = (struct MUTEX *)calloc (sizeof (struct MUTEX)); 
    mutex_init (mtx); 
    *mutex = mtx; 
    return (0); 
} 

Routines must not assume that only one mutex will be used by PMDF. PMDF creates and uses a number of mutexes. The procedure referenced by sleep accepts an unsigned longword passed by value and specifying the number of hundreths of seconds to sleep:

void sleep (unsigned long centi_seconds) 

The sleep procedure is not expected to return a value. Optionally, a value of zero may be supplied for sleep in which case PMDF will use a simple, non-thread aware routine to sleep the process.