Added rwlock example

code/Makefile

@@ -20,7 +20,8 @@ examples=\
 	multi-echo-server\
 	tty\
 	tty-gravity\
-	interfaces
+	interfaces\
+	locks
 
 UV_PATH=$(shell pwd)/../libuv
 UV_LIB = $(UV_PATH)/libuv.a

code/locks/main.c

@@ -0,0 +1,57 @@
+#include <stdio.h>
+#include <uv.h>
+
+uv_barrier_t blocker;
+uv_rwlock_t numlock;
+int shared_num;
+
+void reader(void *n)
+{
+    int num = *(int *)n;
+    int i;
+    for (i = 0; i < 20; i++) {
+        uv_rwlock_rdlock(&numlock);
+        printf("Reader %d: acquired lock\n", num);
+        printf("Reader %d: shared num = %d\n", num, shared_num);
+        uv_rwlock_rdunlock(&numlock);
+        printf("Reader %d: released lock\n", num);
+    }
+    uv_barrier_wait(&blocker);
+}
+
+void writer(void *n)
+{
+    int num = *(int *)n;
+    int i;
+    for (i = 0; i < 20; i++) {
+        uv_rwlock_wrlock(&numlock);
+        printf("Writer %d: acquired lock\n", num);
+        shared_num++;
+        printf("Writer %d: incremented shared num = %d\n", num, shared_num);
+        uv_rwlock_wrunlock(&numlock);
+        printf("Writer %d: released lock\n", num);
+    }
+    uv_barrier_wait(&blocker);
+}
+
+int main()
+{
+    uv_barrier_init(&blocker, 4);
+
+    shared_num = 0;
+    uv_rwlock_init(&numlock);
+
+    uv_thread_t threads[3];
+
+    int thread_nums[] = {1, 2, 1};
+    uv_thread_create(&threads[0], reader, &thread_nums[0]);
+    uv_thread_create(&threads[1], reader, &thread_nums[1]);
+
+    uv_thread_create(&threads[2], writer, &thread_nums[2]);
+
+    uv_barrier_wait(&blocker);
+    uv_barrier_destroy(&blocker);
+
+    uv_rwlock_destroy(&numlock);
+    return 0;
+}

source/threads.rst

@@ -109,8 +109,21 @@ return an error in the second call to ``uv_mutex_lock()``.
 Locks
 ~~~~~
 
-Read-write locks are the other synchronization primitive supported. TODO some
-DB read/write example
+Read-write locks are a more granular access mechanism. Two readers can access
+shared memory at the same time. A writer may not acquire the lock when it is
+held by a reader. A reader or writer may not acquire a lock when a writer is
+holding it. Read-write locks are frequently used in databases. Here is a toy
+example.
+
+.. rubric:: locks/main.c - simple rwlocks
+.. literalinclude:: ../code/locks/main.c
+    :linenos:
+    :emphasize-lines: 13,16,27,31,42,55
+
+Run this and observe how the readers will sometimes overlap. In case of
+multiple writers, schedulers will usually give them higher priority, so if you
+add two writers, you'll see that both writers tend to finish first before the
+readers get a chance again.
 
 Others
 ~~~~~~