Provide mutex handling routines.

PASCAL

status = PMDF_set_mutex

(create, lock, unlock, delete, sleep)

C

status = PMDFsetMutex

(create, lock, unlock, delete, sleep)

int PMDFsetMutex(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 PMDFsetMutex before calling any other API routines, including PMDFinitialize. The procedures passed to PMDFsetMutex 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 wanting 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 can be supplied for sleep in which case PMDF will use a simple, non-thread aware routine to sleep the process.

Return Values

PMDF__OK	Normal, successful completion.
PMDF__BAD	One or more of the parameters create, lock, unlock, or delete was zero. Mutex routines not set.
PMDF__NO	PMDFinitialize was called prior to PMDFsetMutex; this should be treated as a fatal error.