Changeset f02436c8 in mainline

Timestamp:

2005-10-02T17:11:12Z (19 years ago)

Author:

Jakub Jermar <jakub@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

63975c6

Parents:

ac4177ca

Message:

Doxygen-style comments for rwlock.c.

File:

• src/synch/rwlock.c (modified) (8 diffs)

src/synch/rwlock.c

@@ -51 +51 @@
  */
  
-#include <synch/synch.h>
 #include <synch/rwlock.h>
 #include <synch/spinlock.h>
 #include <synch/mutex.h>
 #include <synch/waitq.h>
-
+#include <synch/synch.h>
 #include <list.h>
 #include <typedefs.h>
@@ -70 +69 @@
 static void release_spinlock(void *arg);
 
+/** Initialize reader/writer lock
+ *
+ * Initialize reader/writer lock.
+ *
+ * @param rwl Reader/Writer lock.
+ */
 void rwlock_initialize(rwlock_t *rwl) {
         spinlock_initialize(&rwl->lock);
@@ -76 +81 @@
 }
 
+/** Acquire reader/writer lock for reading
+ *
+ * Acquire reader/writer lock for reading.
+ * Timeout and willingness to block may be specified.
+ *
+ * @param rwl Reader/Writer lock.
+ * @param usec Timeout in microseconds.
+ * @param trylock Switches between blocking and non-blocking mode.
+ *
+ * For exact description of possible combinations of
+ * 'usec' and 'trylock', see comment for waitq_sleep_timeout().
+ *
+ * @return See comment for waitq_sleep_timeout().
+ */
 int _rwlock_write_lock_timeout(rwlock_t *rwl, __u32 usec, int trylock)
 {
@@ -116 +135 @@
 }
 
+/** Acquire reader/writer lock for writing
+ *
+ * Acquire reader/writer lock for writing.
+ * Timeout and willingness to block may be specified.
+ *
+ * @param rwl Reader/Writer lock.
+ * @param usec Timeout in microseconds.
+ * @param trylock Switches between blocking and non-blocking mode.
+ *
+ * For exact description of possible combinations of
+ * 'usec' and 'trylock', see comment for waitq_sleep_timeout().
+ *
+ * @return See comment for waitq_sleep_timeout().
+ */
 int _rwlock_read_lock_timeout(rwlock_t *rwl, __u32 usec, int trylock)
 {
@@ -209 +242 @@
 }
 
+/** Release reader/writer lock held by writer
+ *
+ * Release reader/writer lock held by writer.
+ * Handoff reader/writer lock ownership directly
+ * to waiting readers or a writer.
+ *
+ * @param rwl Reader/Writer lock.
+ */
 void rwlock_write_unlock(rwlock_t *rwl)
 {
@@ -221 +262 @@
 }
 
+/** Release reader/writer lock held by reader
+ *
+ * Release reader/writer lock held by reader.
+ * Handoff reader/writer lock ownership directly
+ * to a waiting writer or don't do anything if more
+ * readers poses the lock.
+ *
+ * @param rwl Reader/Writer lock.
+ */
 void rwlock_read_unlock(rwlock_t *rwl)
 {
@@ -234 +284 @@
 
 
-/*
+/** Direct handoff
+ *
+ * Direct handoff of reader/writer lock ownership
+ * to waiting readers or a writer.
+ *
  * Must be called with rwl->lock locked.
  * Must be called with cpu_priority_high'ed.
- */
-/*
+ *
+ * @param rwl Reader/Writer lock.
+ * @param readers_only See the description below.
+ *
  * If readers_only is false: (unlock scenario)
  * Let the first sleeper on 'exclusive' mutex in, no matter
@@ -306 +362 @@
 }
 
+/** Release spinlock callback
+ *
+ * This is a callback function invoked from the scheduler.
+ * The callback is registered in _rwlock_read_lock_timeout().
+ *
+ * @param arg Spinlock.
+ */
 void release_spinlock(void *arg)
 {