Class: Concurrent::Semaphore — Concurrent

Class List Method List File List

# Class: Concurrent::Semaphore

Inherits:
  SemaphoreImplementation
  - Object
  - Concurrent::Semaphore
  show all
Defined in:
  lib/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)

- - (nil) acquire(permits = 1)

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

- - (Integer) available_permits

  Returns the current number of permits available in this semaphore.

- - (Integer) drain_permits

  Acquires and returns all permits that are immediately available.

- - (undocumented) initialize(count) constructor

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

- - (nil) release(permits = 1)

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

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

  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

### - (`undocumented`) initialize(count)

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/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end

## Instance Method Details

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

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/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end

### - (`Integer`) available_permits

Returns the current number of permits available in this semaphore.

Returns:

- (`Integer`)

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

    class Semaphore < SemaphoreImplementation
    end

### - (`Integer`) drain_permits

Acquires and returns all permits that are immediately available.

Returns:

- (`Integer`)

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

    class Semaphore < SemaphoreImplementation
    end

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

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/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end

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

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/atomic/semaphore.rb', line 143

    class Semaphore < SemaphoreImplementation
    end