Add Semaphore doc as per #393

From @martinmm

Author: jonathanstowe

doc/Type/Semaphore.pod

@@ -0,0 +1,76 @@
+=begin pod
+
+=TITLE class Semaphore
+
+=SUBTITLE Control access to shared resources by multiple processes
+
+  class Semaphore { }
+
+Protect your shared code, data or device access using semaphores. An example is
+a printer manager managing a pool of printers without the need of storing print
+jobs when all printers are occupied. The next job is just blocked until a
+printer becomes available.
+
+  class print-manager {
+    has Array $!printers;
+    has Semaphore $!print-control;
+
+    method BUILD ( Int:D :$nbr-printers ) {
+      for ^$nbr-printers -> $pc {
+        $!printers[$pc] = { :name{"printer-$pc"}, ... };
+      }
+
+      $!print-control .= new($nbr-printers);
+    }
+
+    method print ( $print-job ) {
+      $!print-control.acquire;
+
+      find-available-printer-and-print-it($job);
+
+      $!print-control.release;
+    }
+  }
+
+Another example is a protection around code updating sensitive data. In such a
+case the semaphore is typically initialized to 1.
+
+It is important to have a release on every exit of your program! While this is
+obvious, it is easy to fall in traps such as trowing an exception caused by some
+event. When the program dies there is no problem. When the exception is caught
+your program might eventualy come back to the acquire method and will hang
+indefinitely.
+
+=head1 Methods
+
+=head2 method new
+
+  method new ( int $permits )
+
+Initialize the semaphore with the number of permitted accesses. E.g. when set to
+2, program threads can pass the acquire method twice until it blocks on the
+third time acquire is called.
+
+=head2 method acquire
+
+  method acquire()
+
+Acquire access. When other threads have called the method before and the the
+number of permits are used up, the process blocks until threads passed before
+releases the semaphore.
+
+=head2 method try_acquire
+
+  method try_acquire() returns Bool
+
+Same as acquire but will not block. Instead it returns True if access is
+permitted or False otherwise.
+
+=head2 method release
+
+  method release()
+
+Release the semaphore raising the number of permissions. Any blocked thread will
+get access after that.
+
+=end pod