Mutex library

For some parts in shared libraries (like the font cache in PROforma), some routines have to be called with mutual exclusion (for accessing shared data structures). Normally, this should be done by using the thing system, but when speed is critical, the thing system may be too slow. Therefore syslib contains a special routine to call something with mutual exclusion.

NOTE : The application programmer is then responsible for only accessing that routine through mutual exclusion !!

NOTE : This routine is called with an awkward descriptor, to be filled in, allocated and released by the application, which should not have a ZapRoutine. This is done to make the system fire proof, and efficient ! (For ZapRoutines, see mem library).

NOTE : This routine should not be called inside an atomic routine ! (see also atomic library).

MUTEXCall
Call a routine in with mutual exclusion over a status. Of course, several routines could be mutually exclusive over the same status.
The parameters of the routine will have to adhere to a few rules to allow passing them. e.g. no short or char as parameter. Double parameters count double when counting !

The MUTEXCall routine needs a descriptor which contains both (a pointer to) the byte which indicates when the mutex is in use, and a release routine (which is called when the job which is running in mutex is (force) removed.

typedef struct _MutexHandler {
    char *mutex;
    void (*MutexRelease)();
    } MutexHandler;

This can be used as in the following code (this simple example doesn't really do anything except give an example of the calling method) :

#include "err_h"
#include "mutex_h"
/* the byte to rule mutual exclusion */
/* global variable, thus shared between all calling code */
char mutex;

Error mutexfunction(int any)
{
    /* example function for mutex */
    /* one param, but does nothing */
    return ERR_OK;
}

void release()
{
    /* some actions to make the data structures return */
    /* to a safe state */
    /* ..... */
}

Error myfunction(...)
{
    Error err;
    MutexHandler *mh;
    /* initialise mutex */

    catch( MEMAllocate(sizeof(MutexHandler),&mh) );
    mh->mutex=&mutex;
    mh->MutexRelease=release;

    /* ..... */

    err=MUTEXCall(mh, mutexfunction, 1, 2001);

    /* ..... */
}

PROGS, Professional & Graphical Software
last edited January 7, 1996