123456789_123456789_123456789_123456789_123456789_

Class: Concurrent::MutexAtomicFixnum

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Synchronization::SafeInitialization
Inherits: Object
Defined in: lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb

Overview

Note:

**Private Implementation:** This abstraction is a private, internal implementation detail. It should never be used directly.

A numeric value that can be updated atomically. Reads and writes to an atomic fixnum and thread-safe and guaranteed to succeed. Reads and writes may block briefly but no explicit locking is required.

## Thread-safe Variable Classes

Each of the thread-safe variable classes is designed to solve a different problem. In general:

  • *Agent:* Shared, mutable variable providing independent, uncoordinated, asynchronous change of individual values. Best used when the value will undergo frequent, complex updates. Suitable when the result of an update does not need to be known immediately.

  • *Atom:* Shared, mutable variable providing independent, uncoordinated, synchronous change of individual values. Best used when the value will undergo frequent reads but only occasional, though complex, updates. Suitable when the result of an update must be known immediately.

  • *AtomicReference:* A simple object reference that can be updated atomically. Updates are synchronous but fast. Best used when updates a simple set operations. Not suitable when updates are complex. AtomicBoolean and AtomicFixnum are similar but optimized for the given data type.

  • *Exchanger:* Shared, stateless synchronization point. Used when two or more threads need to exchange data. The threads will pair then block on each other until the exchange is complete.

  • *MVar:* Shared synchronization point. Used when one thread must give a value to another, which must take the value. The threads will block on each other until the exchange is complete.

  • *ThreadLocalVar:* Shared, mutable, isolated variable which holds a different value for each thread which has access. Often used as an instance variable in objects which must maintain different state for different threads.

  • *TVar:* Shared, mutable variables which provide coordinated, synchronous, change of many stated. Used when multiple value must change together, in an all-or-nothing transaction.

Performance:

“‘ Testing with ruby 2.1.2 Testing with MutexAtomicFixnum…

3.130000   0.000000   3.130000 (  3.136505)

Testing with CAtomicFixnum…

0.790000   0.000000   0.790000 (  0.785550)

Testing with jruby 1.9.3 Testing with MutexAtomicFixnum…

5.460000   2.460000   7.920000 (  3.715000)

Testing with Concurrent::JavaAtomicFixnum…

4.520000   0.030000   4.550000 (  1.187000)

“‘

See Also:

Class Method Summary

Synchronization::SafeInitialization - Extended

new

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(initial = 0) ⇒ MutexAtomicFixnum

Creates a new AtomicFixnum with the given initial value.

Parameters:

  • initial (Fixnum) (defaults to: 0) —

    the initial value

Raises:

  • (ArgumentError) —

    if the initial value is not a Fixnum

[ GitHub ] 

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 13



def initialize(initial = 0)
  super()
  @Lock = ::Mutex.new
  ns_set(initial)
end


  







Instance Attribute Details



  

    #value  ⇒ Fixnum  (rw)
  



  

    

Retrieves the current Fixnum value.


  





  
Returns:


    
  
  • 
    (Fixnum)
—    
    

    the current value
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 20



def value
  synchronize { @value }
end


  








  

    #value=(value)  ⇒ Fixnum  (rw)
  



  

    

Explicitly sets the value.


  





  
Parameters:


    
  
  • 
    value
    (Fixnum)
—    
    

    the new value to be set
    

    
  
    • 



Returns:


    
  
  • 
    (Fixnum)
—    
    

    the current value
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    

    if the new value is not a Fixnum
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 25



def value=(value)
  synchronize { ns_set(value) }
end


  







Instance Method Details



  

    #compare_and_set(expect, update)  ⇒ Boolean 
  



  

    

Atomically sets the value to the given updated value if the current value == the expected value.


  





  
Parameters:


    
  
  • 
    expect
    (Fixnum)
—    
    

    the expected value
    

    
  
    • 
  
  • 
    update
    (Fixnum)
—    
    

    the new value
    

    
  
    • 



Returns:


    
  
  • 
    (Boolean)
—    
    

    true if the value was updated else false
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 44



def compare_and_set(expect, update)
  synchronize do
    if @value == expect.to_i
      @value = update.to_i
      true
    else
      false
    end
  end
end


  








  

    #decrement(delta = 1)  ⇒ Fixnum 
    Also known as: #down
  



  

    

Decreases the current value by the given amount (defaults to 1).


  





  
Parameters:


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

    the amount by which to decrease the current value
    

    
  
    • 



Returns:


    
  
  • 
    (Fixnum)
—    
    

    the current value after decrementation
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 37



def decrement(delta = 1)
  synchronize { ns_set(@value - delta.to_i) }
end


  








  

    #down(delta = 1)  
  



  

    

Alias for #decrement.


  



  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 41



alias_method :down, :decrement


  








  

    #increment(delta = 1)  ⇒ Fixnum 
    Also known as: #up
  



  

    

Increases the current value by the given amount (defaults to 1).


  





  
Parameters:


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

    the amount by which to increase the current value
    

    
  
    • 



Returns:


    
  
  • 
    (Fixnum)
—    
    

    the current value after incrementation
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 30



def increment(delta = 1)
  synchronize { ns_set(@value + delta.to_i) }
end


  








  

    #ns_set(value)   (private)
  

  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 76



def ns_set(value)
  Utility::NativeInteger.ensure_integer_and_bounds value
  @value = value
end


  








  

    #synchronize   (private)
  

  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 65



def synchronize
  if @Lock.owned?
    yield
  else
    @Lock.synchronize { yield }
  end
end


  








  

    #up(delta = 1)  
  



  

    

Alias for #increment.


  



  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 34



alias_method :up, :increment


  








  

    #update {|Object| ... } ⇒ Object 
  



  

    

Pass the current value to the given block, replacing it with the block’s result. May retry if the value changes during the block’s execution.


  





  
Yields:


    
  
  • 
    (Object)
—    
    

    Calculate a new value for the atomic reference using given (old) value
    

    
  
    • 



Yield Parameters:


    
  
  • 
    old_value
    (Object)
—    
    

    the starting value of the atomic reference
    

    
  
    • 



Returns:





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/atomic/mutex_atomic_fixnum.rb', line 56



def update
  synchronize do
    @value = yield @value
  end
end