From 0810f1daac3c33d194d573d82ec436021e3e7255 Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Mon, 19 Jan 2009 13:31:37 +0000
Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@643
 35acf78f-673a-0410-8e92-d51de3d6d3f4

---
 docs/src/atomic.dox | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/src/atomic.dox

(limited to 'docs/src/atomic.dox')

diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox
new file mode 100644
index 000000000..0f678448b
--- /dev/null
+++ b/docs/src/atomic.dox
@@ -0,0 +1,50 @@
+/**
+ * @page article_atomic Invoking multiple primitives as a single atomic operation
+ * @{
+ * It is often necessary to invoke multiple operations involving a
+ * reschedulation as a single atomic operation.<br>
+ * ChibiOS/RT already implements APIs that perform complex operations, as
+ * example the API @p chSemSignalWait() performs two operations atomically.<br>
+ * If more complex operations are required in your application then it is
+ * possible to build macro-operations, see the following example:
+ * @code
+  chSysLock();
+ 
+  chSemSignalI(&sem1);
+  chSemSignalI(&sem2);
+  if (tp != NULL) {
+    chThdResumeI(tp);
+    tp = NULL;
+  }
+  chSchRescheduleS();
+ 
+  chSysUnlock();
+ * @endcode
+ * The above example performs a signal operation on two semaphores, optionally
+ * resumes a thread, and performs a final reschedulation. The three operations
+ * are performed atomically.<br>
+ * An hypotetical @p chSemSignalSignalWait() operation could be implemented as
+ * follow:
+ * @code
+  chSysLock();
+ 
+  chSemSignalI(&sem1);
+  chSemSignalI(&sem2);
+  /*
+   * The "if" is required because the chSemWaitS() does not always internally
+   * reschedule.
+   */
+  if (chSemGetCounter(&sem3) <= 0)
+    chSemWaitS(&Sem3);
+  else {
+    chSemFastWaitS(&sem3);
+    chSchRescheduleS();
+  }
+ 
+  chSysUnlock();
+ * @endcode
+ * In general multiple I-Class APIs can be included and the block is terminated
+ * by an S-Class API that performs a reschedulation. Optionally a
+ * @p chSchRescheduleS() is present at the very end of the block.
+ */
+/** @} */
-- 
cgit v1.2.3