# Class: Concurrent::Semaphore

Inherits:
  SemaphoreImplementation
  - Object
  - Concurrent::Semaphore
  show all

Defined in:
  lib/concurrent-ruby/concurrent/atomic/semaphore.rb

## Overview

A counting semaphore. Conceptually, a semaphore maintains a set of permits. Each #acquire blocks if necessary until a permit is available, and then takes it. Each #release adds a permit, potentially releasing a blocking acquirer. However, no actual permit objects are used; the Semaphore just keeps a count of the number available and acts accordingly.

Examples:

    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)

    # prints:
    # Thread 3 acquired semaphore
    # Thread 2 acquired semaphore
    # Thread 4 releasing semaphore
    # Thread 1 acquired semaphore

## Instance Method Summary collapse

- #acquire(permits = 1) ⇒ nil

  Acquires the given number of permits from this semaphore, blocking until all are available.

- #available_permits ⇒ Integer

  Returns the current number of permits available in this semaphore.

- #drain_permits ⇒ Integer

  Acquires and returns all permits that are immediately available.

- #initialize(count) ⇒ undocumented constructor

  Create a new `Semaphore` with the initial `count`.

- #release(permits = 1) ⇒ nil

  Releases the given number of permits, returning them to the semaphore.

- #try_acquire(permits = 1, timeout = nil) ⇒ Boolean

  Acquires the given number of permits from this semaphore, only if all are available at the time of invocation or within `timeout` interval.

## Constructor Details

### #initialize(count) ⇒ `undocumented`

Create a new `Semaphore` with the initial `count`.

Parameters:

- count (`Fixnum`) —

  the initial count

Raises:

- (`ArgumentError`) —

  if `count` is not an integer or is less than zero

    143
    144

    # File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end

## Instance Method Details

### #acquire(permits = 1) ⇒ `nil`

Acquires the given number of permits from this semaphore, blocking until all are available.

Parameters:

- permits (`Fixnum`) (defaults to: `1`) —

  Number of permits to acquire

Returns:

- (`nil`)

Raises:

- (`ArgumentError`) —

  if `permits` is not an integer or is less than one

    143
    144

    # File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end

### #available_permits ⇒ `Integer`

Returns the current number of permits available in this semaphore.

Returns:

- (`Integer`)

    143
    144

    # File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end

### #drain_permits ⇒ `Integer`

Acquires and returns all permits that are immediately available.

Returns:

- (`Integer`)

    143
    144

    # File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end

### #release(permits = 1) ⇒ `nil`

Releases the given number of permits, returning them to the semaphore.

Parameters:

- permits (`Fixnum`) (defaults to: `1`) —

  Number of permits to return to the semaphore.

Returns:

- (`nil`)

Raises:

- (`ArgumentError`) —

  if `permits` is not a number or is less than one

    143
    144

    # File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end

### #try_acquire(permits = 1, timeout = nil) ⇒ `Boolean`

Acquires the given number of permits from this semaphore, only if all are available at the time of invocation or within `timeout` interval

Parameters:

- permits (`Fixnum`) (defaults to: `1`) —

  the number of permits to acquire

- timeout (`Fixnum`) (defaults to: `nil`) —

  the number of seconds to wait for the counter or `nil` to return immediately

Returns:

- (`Boolean`) —

  `false` if no permits are available, `true` when acquired a permit

Raises:

- (`ArgumentError`) —

  if `permits` is not an integer or is less than one

    143
    144

    # File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end