A mutex can be initialized with the pthread_mutex_init function, which has the following prototype:

int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr);

The input argument mutex is a pointer to the mutex to be initialized and attr indicates the attributes of mutex. If attr is set to NULL, the default attributes will be used. The function will return a zero if the mutex is initialized successfully and a non-zero value otherwise.

When we are done with the mutex, we can destroy it with the pthread_mutex_destroy function, which has the following prototype:

int pthread_mutex_destroy(pthread_mutex_t *mutex);

The input argument is a pointer pointing to the mutex to be destroyed.

In our sample project, we created two mutexes mux1 and mux2 to synchronize the access of a shared counter cnt by the two threads. After the two threads exit, we destroyed the mutexes.

The following four functions are available to lock and unlock a mutex:

int pthread_mutex_lock(pthread_mutex_t *mutex);
int pthread_mutex_unlock(pthread_mutex_t *mutex);
int pthread_mutex_trylock(pthread_mutex_t *mutex);
int pthread_mutex_lock_timeout_np(pthread_mutex_t *mutex, unsigned msecs);

In all the four functions, the input argument refers to the mutex object in use. A zero return value indicates the mutex is locked or unlocked successfully. The last function allows us to specify a wait timeout in milliseconds. If it cannot acquire the mutex after the timeout, it will return EBUSY to indicate failure.

We demonstrated the usage of the functions previously in our example. In function run_by_thread1, we first lock mux1 by pthread_mutex_lock, and then mux2 by pthread_mutex_trylock. If mux2 cannot be locked, we unlock mux1, sleep for 50 milliseconds, and try again. If mux2 can be locked, we update the shared counter cnt, log its current value, and then release the two mutexes. Another function run_by_thread2 is similar to run_by_thread1, except that it locks mux2 first, and then mux1. The two functions are executed by two threads. This can be illustrated by the following diagram:

As shown in the preceding diagram, thread 1 needs to obtain mux1, then mux2 in order to update cnt, while thread 2 needs to acquire mux2, then mux1 to update cnt. In case thread 1 locked mux1 and thread 2 locked mux2, neither threads can proceed. This corresponds to the situation where pthread_mutex_trylock returns a nonzero value. If this happens, one thread will give up its mutex so the other thread can proceed to update the shared counter cnt and release the two mutexes. Note that we can replace the pthread_mutex_trylock with pthread_mutex_lock_timeout_np in our code. Readers are encouraged to try it out themselves.

We also implemented a native method jni_start_threads_dead which will probably cause a deadlock. The thread setup is similar to the previous case, but we use pthread_mutex_lock instead of pthread_mutex_trylock, and the threads do not give up the mutexes they have already locked. This can be illustrated as shown in the following diagram:

Thread 1 tries to lock mux1 and then mux2, while thread 2 tries to lock mux2 and then mux1. In case where thread 1 has locked mux1 and thread 2 has locked mux2, none of the threads can proceed. Because they won't give up the mutexes they've obtained, the two threads will be blocked forever. This is referred to as a deadlock.