txt: ## semaphore.md
  class Semaphore
  
  Control access to shared resources by multiple threads
  
  ```raku
  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.
  
  ```raku
  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 find-available-printer-and-print-it($job) { say "Is printed!"; }
  
    method print( $print-job ) {
      $!print-control.acquire;
  
      self.find-available-printer-and-print-it($print-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 throwing an exception caused by some event. When the program dies there is no problem. When the exception is caught your program might eventually come back to the acquire method and will hang indefinitely.
  
  # [Methods](#class_Semaphore "go to top of document")[§](#Methods "direct link")
  
  ## [method new](#class_Semaphore "go to top of document")[§](#method_new "direct link")
  
  ```raku
  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.
  
  ## [method acquire](#class_Semaphore "go to top of document")[§](#method_acquire "direct link")
  
  ```raku
  method acquire()
  ```
  
  Acquire access. When other threads have called the method before and the number of permits are used up, the process blocks until threads passed before releases the semaphore.
  
  ## [method try\_acquire](#class_Semaphore "go to top of document")[§](#method_try_acquire "direct link")
  
  ```raku
  method try_acquire(--> Bool)
  ```
  
  Same as acquire but will not block. Instead it returns `True` if access is permitted or `False` otherwise.
  
  ## [method release](#class_Semaphore "go to top of document")[§](#method_release "direct link")
  
  ```raku
  method release()
  ```
  
  Release the semaphore raising the number of permissions. Any blocked thread will get access after that.
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Semaphore`
  
  
  
  raku-type-graph
  
  
  
  Semaphore
  Semaphore
  
  
  Any
  Any
  
  
  Semaphore->Any
  
  
  
  Mu
  Mu
  
  
  Any->Mu
  
  [Expand chart above](/assets/typegraphs/Semaphore.svg)
  