Class: Concurrent::Semaphore

Inherits:
SemaphoreImplementation
  • Object
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. Alternatively, permits may be acquired within a block, and automatically released after the block finishes executing.

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
semaphore = Concurrent::Semaphore.new(1) puts semaphore.available_permits semaphore.acquire do puts semaphore.available_permits end puts semaphore.available_permits # prints: # 1 # 0 # 1

Instance Method Summary collapse

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

 161 162
 
# File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 161 class Semaphore < SemaphoreImplementation end

Instance Method Details

#acquire(permits = 1) ⇒ nil, BasicObject

Acquires the given number of permits from this semaphore, blocking until all are available. If a block is given, yields to it and releases the permits afterwards.

is given, its return value is returned.

Parameters:

  • permits (Fixnum) (defaults to: 1) —

    Number of permits to acquire

Returns:

  • (nil, BasicObject) —

    Without a block, nil is returned. If a block

Raises:

  • (ArgumentError) —

    if permits is not an integer or is less than zero

 161 162
 
# File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 161 class Semaphore < SemaphoreImplementation end

#available_permits ⇒ Integer

Returns the current number of permits available in this semaphore.

Returns:

  • (Integer) 
 161 162
 
# File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 161 class Semaphore < SemaphoreImplementation end

#drain_permits ⇒ Integer

Acquires and returns all permits that are immediately available.

Returns:

  • (Integer) 
 161 162
 
# File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 161 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 zero

 161 162
 
# File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 161 class Semaphore < SemaphoreImplementation end

#try_acquire(permits = 1, timeout = nil) ⇒ true, false, nil, BasicObject

Acquires the given number of permits from this semaphore, only if all are available at the time of invocation or within timeout interval. If a block is given, yields to it if the permits were successfully acquired, and releases them afterward, returning the block's return value.

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:

  • (true, false, nil, BasicObject) —

    false if no permits are available, true when acquired a permit. If a block is given, the block's return value is returned if the permits were acquired; if not, nil is returned.

Raises:

  • (ArgumentError) —

    if permits is not an integer or is less than zero

 161 162
 
# File 'lib/concurrent-ruby/concurrent/atomic/semaphore.rb', line 161 class Semaphore < SemaphoreImplementation end