Class: Concurrent::JavaSemaphore

Inherits:
Object
  • Object
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.

Instance Method Summary collapse

Constructor Details

#initialize(count) ⇒ JavaSemaphore

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



164
165
166
167
168
169
170
 
# File 'lib/concurrent/atomic/semaphore.rb', line 164

def initialize(count)
  unless count.is_a?(Fixnum) && count >= 0
    fail(ArgumentError,
         'count must be in integer greater than or equal zero')
  end
  @semaphore = java.util.concurrent.Semaphore.new(count)
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



173
174
175
176
177
178
 
# File 'lib/concurrent/atomic/semaphore.rb', line 173

def acquire(permits = 1)
  unless permits.is_a?(Fixnum) && permits > 0
    fail ArgumentError, 'permits must be an integer greater than zero'
  end
  @semaphore.acquire(permits)
end

#available_permits ⇒ Integer

Returns the current number of permits available in this semaphore.

Returns:

  • (Integer) 


181
182
183
 
# File 'lib/concurrent/atomic/semaphore.rb', line 181

def available_permits
  @semaphore.availablePermits
end

#drain_permits ⇒ Integer

Acquires and returns all permits that are immediately available.

Returns:

  • (Integer) 


186
187
188
 
# File 'lib/concurrent/atomic/semaphore.rb', line 186

def drain_permits
  @semaphore.drainPermits
end

#reduce_permits(reduction) ⇒ Nil

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Shrinks the number of available permits by the indicated reduction.

Parameters:

  • reduction (Fixnum) —

    Number of permits to remove.

Returns:

  • (Nil)

Raises:

  • (ArgumentError) —

    if ‘reduction` is not an integer or is negative

  • (ArgumentError) —

    if ‘@free` - `@reduction` is less than zero



214
215
216
217
218
219
 
# File 'lib/concurrent/atomic/semaphore.rb', line 214

def reduce_permits(reduction)
  unless reduction.is_a?(Fixnum) && reduction >= 0
    fail ArgumentError, 'reduction must be an non-negative integer'
  end
  @semaphore.reducePermits(reduction)
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



205
206
207
208
209
210
211
 
# File 'lib/concurrent/atomic/semaphore.rb', line 205

def release(permits = 1)
  unless permits.is_a?(Fixnum) && permits > 0
    fail ArgumentError, 'permits must be an integer greater than zero'
  end
  @semaphore.release(permits)
  true
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



191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/concurrent/atomic/semaphore.rb', line 191

def try_acquire(permits = 1, timeout = nil)
  unless permits.is_a?(Fixnum) && permits > 0
    fail ArgumentError, 'permits must be an integer greater than zero'
  end
  if timeout.nil?
    @semaphore.tryAcquire(permits)
  else
    @semaphore.tryAcquire(permits,
                           timeout,
                           java.util.concurrent.TimeUnit::SECONDS)
  end
end