From 8dcde6b05822db6a94e8bfef7e142640119a30b0 Mon Sep 17 00:00:00 2001
From: Ole Tange <ole@tange.dk>
Date: Sun, 22 Aug 2010 02:51:51 +0200
Subject: [PATCH] A (crappy) example of sem usage.

---
 doc/FUTURE_IDEAS |  7 -------
 src/parallel     | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/doc/FUTURE_IDEAS b/doc/FUTURE_IDEAS
index 8c72af4e..03792f0c 100644
--- a/doc/FUTURE_IDEAS
+++ b/doc/FUTURE_IDEAS
@@ -1,10 +1,3 @@
-Bug: seq 1 10 | stdout parallel --eta echo
-
-# Examples of sem
-
-find . -execdir sem -j100 'sleep 4; echo {}' \; ; sem --wait
-
-
 fex syntax for splitting fields
 http://www.semicomplete.com/projects/fex/
 sql :foo 'select * from bar' | parallel --fex '|{1,2}' do_stuff {2} {1}
diff --git a/src/parallel b/src/parallel
index ae38ab32..8fb4adac 100755
--- a/src/parallel
+++ b/src/parallel
@@ -1298,6 +1298,39 @@ As there is not a I<command> the option B<--command> is default
 because the jobs needs to be evaluated by the shell.
 
 
+=head1 EXAMPLE: Working as mutex and counting semaphore
+
+The command B<sem> is an alias for B<parallel --semaphore>.
+
+A counting semaphore will allow a given number of jobs to be started
+in the background.  When the number of jobs are running in the
+background, GNU B<sem> will wait for one of these to complete before
+starting another command. B<sem --wait> will wait for all jobs to
+complete.
+
+Run 10 jobs in parallel in the background:
+
+  for i in `ls *.log` ; do
+    echo $i
+    sem -j10 gzip $i ";" echo done
+  done
+  sem --wait
+
+A mutex is a counting semaphore allowing only one job to run. This
+will edit the file I<myfile> and prepends the file with lines with the
+numbers 1 to 3.
+
+  seq 1 3 | parallel sem sed -i -e 'i{}' myfile
+
+As I<myfile> can be very big it is important only one process edits
+the file at the same time.
+
+Name the semaphore to have multiple different semaphores active at the
+same time:
+
+  seq 1 3 | parallel sem --id mymutex sed -i -e 'i{}' myfile
+
+
 =head1 QUOTING
 
 For more advanced use quoting may be an issue. The following will