Add Semaphore documentation example

Author: anildigital

futures.rb

@@ -0,0 +1,14 @@
+require 'concurrent'
+
+Array.new(4) do 
+  Concurrent.zip(
+    Array.new(5) do |i|
+      Concurrent::Delay.new do 
+        puts "starting #{i}"
+        sleep(i)
+        puts "done #{i}"
+        i
+      end
+    end
+  )
+end.inject { |a,b| a.chain { b }.flat }.value!

lib/concurrent/atomic/semaphore.rb

@@ -108,6 +108,38 @@ module Concurrent
   #   count of the number available and acts accordingly.
   #
   # @!macro semaphore_public_api
+  # @example
+  #   semaphore = Concurrent::Semaphore.new(2)
+  #
+  #   t1 = Thread.new do
+  #     semaphore.acquire
+  #     puts "Thread 1 acquired semaphore"
+  #   end
+  #
+  #   t2 = Thread.new do
+  #     semaphore.acquire
+  #     puts "Thread 2 acquired semaphore"
+  #   end
+  #
+  #   t3 = Thread.new do
+  #     semaphore.acquire
+  #     puts "Thread 3 acquired semaphore"
+  #   end
+  #
+  #   t4 = Thread.new do
+  #     sleep(2)
+  #     puts "Thread 4 releasing semaphore"
+  #     semaphore.release
+  #   end
+  #
+  #   [t1, t2, t3, t4].each(&:join)
+  #
+  #   outputs
+  #   "Thread 3 acquired semaphore"
+  #   "Thread 2 acquired semaphore"
+  #   "Thread 4 releasing semaphore"
+  #   "Thread 1 acquired semaphore"
+  #
   class Semaphore < SemaphoreImplementation
   end
 end