Mutual Exclusion Locks

Assume that two threads need to access one or more global variables in a consistent fashion (for example, if each thread needs to add two numbers to a unique global counter). The unique global counter should always reflect the accurate sum of all numbers added by both threads, regardless of the scheduling.

Reflecting this sum could be done using semaphores. However, the ChorusOS operating system provides mutexes which have been specifically designed and tuned for these specific requirements.

A mutex is a binary flag associated with a (possibly empty) queue of waiting threads. The mutex may be locked or free. At initialization, the mutex is set to the free state.

#include <chorus.h>
int mutexInit(KnMutex* mutex);

For this example to work, the mutexes should have been previously allocated. Mutexes may be allocated wherever convenient for the application. There is no limit imposed on the maximum number of mutexes.

Three operations are provided with mutexes.

• mutexGet() acquires the mutex. If the mutex is free, it is atomically locked and the thread continues its execution.

  #include <chorus.h>
  int mutexGet(KnMutex* mutex);

  If the mutex is locked when the mutexGet() operation is invoked, the thread is blocked and queued in the list of threads (waiting for the mutex to become free).

  ---

  Note -

  There is no way to limit the time that a thread waits to acquire a mutex.

  ---

• mutexRel() releases the mutex, returning it to its free state. If threads are blocked while waiting for the mutex, one of them is picked up from the list and activated with the mutex locked.

  #include <chorus.h>
  int mutexRel(KnMutex* mutex);

• mutexTry() is similar to mutexGet() but the thread is not blocked if the mutex is already locked when the operation is invoked.

  #include <chorus.h>
  int mutexTry(KnMutex* mutex);

  By checking the return value of mutexTry(), you can determine whether the mutex was free and has been acquired by the current thread, or, whether the mutex was already locked, in which case the operation has failed.

For more information, refer to the mutexInit(2K) man page.

The following example shows a small, basic library routine called sampleAdd() which receives two integer arguments and adds them to a global variable one after the other. Both the main thread and the created thread perform a number of calls to the library. When the job is completed, the main thread prints the result and terminates the actor.

Example 9-3 Using Mutual Exclusion Locks

(file: progov/mutex.c)
#include <stdio.h>
#include <stdlib.h>
#include <chorus.h>
#define USER_STACK_SIZE (1024 * sizeof(long))
KnSem   sampleSem;
KnMutex sampleMutex;
long    grandTotal;
    int
childCreate(KnPc entry)
{
  KnActorPrivilege      actorP;
  KnDefaultStartInfo_f  startInfo;
  char*                 userStack;
  int                   childLid = -1;
  int                   res;
  startInfo.dsType            = K_DEFAULT_START_INFO;
  startInfo.dsSystemStackSize = K_DEFAULT_STACK_SIZE;
  res = actorPrivilege(K_MYACTOR, &actorP, NULL);
  if (res != K_OK) {
    printf("Cannot get the privilege of the actor, error %d\n", res);
    exit(1);
  }
  if (actorP == K_SUPACTOR) {
    startInfo.dsPrivilege = K_SUPTHREAD;
  } else {
    startInfo.dsPrivilege = K_USERTHREAD;
  }
  if (actorP != K_SUPACTOR) {
    userStack = malloc(USER_STACK_SIZE);
    if (userStack == NULL) {
      printf("Cannot allocate user stack\n");
      exit(1);
    }
    startInfo.dsUserStackPointer = userStack + USER_STACK_SIZE;
  } 
  startInfo.dsEntry = entry;
  res = threadCreate(K_MYACTOR, &childLid, K_ACTIVE, 0, &startInfo);
  if (res != K_OK) {
    printf("Cannot create the thread, error %d\n", res);
    exit(1);
  }
  return childLid;
}
    int
sampleAdd(int a, int b)
{
  (void) mutexGet(&sampleMutex)
  grandTotal += a + b;
  (void) mutexRel(&sampleMutex);
}
    void
sampleThread()
{
  int res;
  int i;
  for(i = 0; i < 10; i++) {
    sampleAdd(threadSelf(), i);        /* Why not ??? */
  }
  res  = semV(&sampleSem);
  if (res != K_OK){            
    printf("Cannot perform the semV operation, error %d\n", res);
    exit(1);
  }              
      /* Suicide */
  (void) threadDelete(K_MYACTOR, K_MYSELF);
}
int main(int argc, char** argv, char**envp)
{
  int        i;
  int        res;
  res = semInit(&sampleSem, 0);
  if (res != K_OK) {            
    printf("Cannot initialize the semaphore, error %d\n", res);
    exit(1);             
  }              
  (void) mutexInit(&sampleMutex);
  (void) childCreate((KnPc)sampleThread);
  for(i = 0; i < 20; i++){
    sampleAdd(threadSelf(), i);      /* Why not ??? */
  }
  res = semP(&sampleSem, K_NOTIMEOUT);
  if (res != K_OK) {            
    printf("Cannot perform the semP operation, error %d\n", res);     
    exit(1);             
  }              
  printf("grandTotal is %d\n", grandTotal);
  return 0;
}

Note the following points concerning the previous example:

• The mutex is allocated within the global data of the actor and is initialized before being used.

• The sampleAdd() routine uses the mutex to protect access to the grandTotal variable and make it atomic. Note that the mutexGet() and mutexRel() operations perform the bulk of the work. Mutex operations should always be used in pairs, as in the previous example.

• A mutex is not recursive. A thread that has locked a mutex will deadlock if it tries to perform a second mutexGet() operation on the same mutex.