From b1070d84cec4dc96be48d375040a2ff11c268c23 Mon Sep 17 00:00:00 2001 From: Benoit Daloze Date: Mon, 23 Jan 2023 15:52:14 +0100 Subject: [PATCH] More docs fixes --- Rakefile | 6 +- .../concurrent/atomic/atomic_reference.rb | 130 +++++++++++------- .../atomic_reference/atomic_direct_update.rb | 38 ----- .../concurrent/synchronization.rb | 3 +- 4 files changed, 81 insertions(+), 96 deletions(-) diff --git a/Rakefile b/Rakefile index 3d6450966..f210c9e72 100644 --- a/Rakefile +++ b/Rakefile @@ -337,9 +337,9 @@ namespace :release do desc '** print post release steps' task :post_steps do # TODO: (petr 05-Jun-2021) automate and renew the process - # puts 'Manually: create a release on GitHub with relevant changelog part' - # puts 'Manually: send email same as release with relevant changelog part' - # puts 'Manually: tweet' + puts 'Manually: create a release on GitHub with relevant changelog part' + puts 'Manually: send email same as release with relevant changelog part' + puts 'Manually: tweet' end end end diff --git a/lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb b/lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb index 2b40ce99e..bb5fb7745 100644 --- a/lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb +++ b/lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb @@ -14,58 +14,6 @@ module TruffleRuby module Concurrent - # @!macro atomic_reference - # - # An object reference that may be updated atomically. All read and write - # operations have java volatile semantic. - # - # @!macro thread_safe_variable_comparison - # - # @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReference.html - # @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html - # - # @!method initialize(value = nil) - # @!macro atomic_reference_method_initialize - # @param [Object] value The initial value. - # - # @!method get - # @!macro atomic_reference_method_get - # Gets the current value. - # @return [Object] the current value - # - # @!method set(new_value) - # @!macro atomic_reference_method_set - # Sets to the given value. - # @param [Object] new_value the new value - # @return [Object] the new value - # - # @!method get_and_set(new_value) - # @!macro atomic_reference_method_get_and_set - # Atomically sets to the given value and returns the old value. - # @param [Object] new_value the new value - # @return [Object] the old value - # - # @!method compare_and_set(old_value, new_value) - # @!macro atomic_reference_method_compare_and_set - # - # Atomically sets the value to the given updated value if - # the current value == the expected value. - # - # @param [Object] old_value the expected value - # @param [Object] new_value the new value - # - # @return [Boolean] `true` if successful. A `false` return indicates - # that the actual value was not equal to the expected value. - # - # @!method update - # @!macro atomic_reference_method_update - # - # @!method try_update - # @!macro atomic_reference_method_try_update - # - # @!method try_update! - # @!macro atomic_reference_method_try_update! - # @!macro internal_implementation_note AtomicReferenceImplementation = case when Concurrent.on_cruby? && Concurrent.c_extensions_loaded? @@ -98,7 +46,83 @@ class TruffleRubyAtomicReference < TruffleRuby::AtomicReference end private_constant :AtomicReferenceImplementation - # @!macro atomic_reference + # An object reference that may be updated atomically. All read and write + # operations have java volatile semantic. + # + # @!macro thread_safe_variable_comparison + # + # @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReference.html + # @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html + # + # @!method initialize(value = nil) + # @!macro atomic_reference_method_initialize + # @param [Object] value The initial value. + # + # @!method get + # @!macro atomic_reference_method_get + # Gets the current value. + # @return [Object] the current value + # + # @!method set(new_value) + # @!macro atomic_reference_method_set + # Sets to the given value. + # @param [Object] new_value the new value + # @return [Object] the new value + # + # @!method get_and_set(new_value) + # @!macro atomic_reference_method_get_and_set + # Atomically sets to the given value and returns the old value. + # @param [Object] new_value the new value + # @return [Object] the old value + # + # @!method compare_and_set(old_value, new_value) + # @!macro atomic_reference_method_compare_and_set + # + # Atomically sets the value to the given updated value if + # the current value == the expected value. + # + # @param [Object] old_value the expected value + # @param [Object] new_value the new value + # + # @return [Boolean] `true` if successful. A `false` return indicates + # that the actual value was not equal to the expected value. + # + # @!method update + # 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. + # + # @yield [Object] Calculate a new value for the atomic reference using + # given (old) value + # @yieldparam [Object] old_value the starting value of the atomic reference + # @return [Object] the new value + # + # @!method try_update + # Pass the current value to the given block, replacing it + # with the block's result. Return nil if the update fails. + # + # @yield [Object] Calculate a new value for the atomic reference using + # given (old) value + # @yieldparam [Object] old_value the starting value of the atomic reference + # @note This method was altered to avoid raising an exception by default. + # Instead, this method now returns `nil` in case of failure. For more info, + # please see: https://github.com/ruby-concurrency/concurrent-ruby/pull/336 + # @return [Object] the new value, or nil if update failed + # + # @!method try_update! + # Pass the current value to the given block, replacing it + # with the block's result. Raise an exception if the update + # fails. + # + # @yield [Object] Calculate a new value for the atomic reference using + # given (old) value + # @yieldparam [Object] old_value the starting value of the atomic reference + # @note This behavior mimics the behavior of the original + # `AtomicReference#try_update` API. The reason this was changed was to + # avoid raising exceptions (which are inherently slow) by default. For more + # info: https://github.com/ruby-concurrency/concurrent-ruby/pull/336 + # @return [Object] the new value + # @raise [Concurrent::ConcurrentUpdateError] if the update fails class AtomicReference < AtomicReferenceImplementation # @return [String] Short string representation. diff --git a/lib/concurrent-ruby/concurrent/atomic_reference/atomic_direct_update.rb b/lib/concurrent-ruby/concurrent/atomic_reference/atomic_direct_update.rb index 151ab1794..5d2d7edd4 100644 --- a/lib/concurrent-ruby/concurrent/atomic_reference/atomic_direct_update.rb +++ b/lib/concurrent-ruby/concurrent/atomic_reference/atomic_direct_update.rb @@ -7,34 +7,11 @@ module Concurrent # @!visibility private # @!macro internal_implementation_note module AtomicDirectUpdate - - # @!macro atomic_reference_method_update - # - # 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. - # - # @yield [Object] Calculate a new value for the atomic reference using - # given (old) value - # @yieldparam [Object] old_value the starting value of the atomic reference - # @return [Object] the new value def update true until compare_and_set(old_value = get, new_value = yield(old_value)) new_value end - # @!macro atomic_reference_method_try_update - # - # Pass the current value to the given block, replacing it - # with the block's result. Return nil if the update fails. - # - # @yield [Object] Calculate a new value for the atomic reference using - # given (old) value - # @yieldparam [Object] old_value the starting value of the atomic reference - # @note This method was altered to avoid raising an exception by default. - # Instead, this method now returns `nil` in case of failure. For more info, - # please see: https://github.com/ruby-concurrency/concurrent-ruby/pull/336 - # @return [Object] the new value, or nil if update failed def try_update old_value = get new_value = yield old_value @@ -44,21 +21,6 @@ def try_update new_value end - # @!macro atomic_reference_method_try_update! - # - # Pass the current value to the given block, replacing it - # with the block's result. Raise an exception if the update - # fails. - # - # @yield [Object] Calculate a new value for the atomic reference using - # given (old) value - # @yieldparam [Object] old_value the starting value of the atomic reference - # @note This behavior mimics the behavior of the original - # `AtomicReference#try_update` API. The reason this was changed was to - # avoid raising exceptions (which are inherently slow) by default. For more - # info: https://github.com/ruby-concurrency/concurrent-ruby/pull/336 - # @return [Object] the new value - # @raise [Concurrent::ConcurrentUpdateError] if the update fails def try_update! old_value = get new_value = yield old_value diff --git a/lib/concurrent-ruby/concurrent/synchronization.rb b/lib/concurrent-ruby/concurrent/synchronization.rb index 0d5d40438..6d8cf4bd5 100644 --- a/lib/concurrent-ruby/concurrent/synchronization.rb +++ b/lib/concurrent-ruby/concurrent/synchronization.rb @@ -6,8 +6,7 @@ require 'concurrent/synchronization/lock' module Concurrent - # {include:file:docs-source/synchronization.md} - # {include:file:docs-source/synchronization-notes.md} + # @!visibility private module Synchronization end end