Skip to content

Commit b1070d8

Browse files
eregoneregon
committed
More docs fixes
1 parent 11da3fe commit b1070d8

File tree

4 files changed

+81
-96
lines changed

4 files changed

+81
-96
lines changed

‎Rakefile

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -337,9 +337,9 @@ namespace :release do
337337
desc '** print post release steps'
338338
task :post_steps do
339339
# TODO: (petr 05-Jun-2021) automate and renew the process
340-
# puts 'Manually: create a release on GitHub with relevant changelog part'
341-
# puts 'Manually: send email same as release with relevant changelog part'
342-
# puts 'Manually: tweet'
340+
puts 'Manually: create a release on GitHub with relevant changelog part'
341+
puts 'Manually: send email same as release with relevant changelog part'
342+
puts 'Manually: tweet'
343343
end
344344
end
345345
end

‎lib/concurrent-ruby/concurrent/atomic/atomic_reference.rb

Lines changed: 77 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -14,58 +14,6 @@ module TruffleRuby
1414

1515
module Concurrent
1616

17-
# @!macro atomic_reference
18-
#
19-
# An object reference that may be updated atomically. All read and write
20-
# operations have java volatile semantic.
21-
#
22-
# @!macro thread_safe_variable_comparison
23-
#
24-
# @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReference.html
25-
# @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html
26-
#
27-
# @!method initialize(value = nil)
28-
# @!macro atomic_reference_method_initialize
29-
# @param [Object] value The initial value.
30-
#
31-
# @!method get
32-
# @!macro atomic_reference_method_get
33-
# Gets the current value.
34-
# @return [Object] the current value
35-
#
36-
# @!method set(new_value)
37-
# @!macro atomic_reference_method_set
38-
# Sets to the given value.
39-
# @param [Object] new_value the new value
40-
# @return [Object] the new value
41-
#
42-
# @!method get_and_set(new_value)
43-
# @!macro atomic_reference_method_get_and_set
44-
# Atomically sets to the given value and returns the old value.
45-
# @param [Object] new_value the new value
46-
# @return [Object] the old value
47-
#
48-
# @!method compare_and_set(old_value, new_value)
49-
# @!macro atomic_reference_method_compare_and_set
50-
#
51-
# Atomically sets the value to the given updated value if
52-
# the current value == the expected value.
53-
#
54-
# @param [Object] old_value the expected value
55-
# @param [Object] new_value the new value
56-
#
57-
# @return [Boolean] `true` if successful. A `false` return indicates
58-
# that the actual value was not equal to the expected value.
59-
#
60-
# @!method update
61-
# @!macro atomic_reference_method_update
62-
#
63-
# @!method try_update
64-
# @!macro atomic_reference_method_try_update
65-
#
66-
# @!method try_update!
67-
# @!macro atomic_reference_method_try_update!
68-
6917
# @!macro internal_implementation_note
7018
AtomicReferenceImplementation = case
7119
when Concurrent.on_cruby? && Concurrent.c_extensions_loaded?
@@ -98,7 +46,83 @@ class TruffleRubyAtomicReference < TruffleRuby::AtomicReference
9846
end
9947
private_constant :AtomicReferenceImplementation
10048

101-
# @!macro atomic_reference
49+
# An object reference that may be updated atomically. All read and write
50+
# operations have java volatile semantic.
51+
#
52+
# @!macro thread_safe_variable_comparison
53+
#
54+
# @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReference.html
55+
# @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html
56+
#
57+
# @!method initialize(value = nil)
58+
# @!macro atomic_reference_method_initialize
59+
# @param [Object] value The initial value.
60+
#
61+
# @!method get
62+
# @!macro atomic_reference_method_get
63+
# Gets the current value.
64+
# @return [Object] the current value
65+
#
66+
# @!method set(new_value)
67+
# @!macro atomic_reference_method_set
68+
# Sets to the given value.
69+
# @param [Object] new_value the new value
70+
# @return [Object] the new value
71+
#
72+
# @!method get_and_set(new_value)
73+
# @!macro atomic_reference_method_get_and_set
74+
# Atomically sets to the given value and returns the old value.
75+
# @param [Object] new_value the new value
76+
# @return [Object] the old value
77+
#
78+
# @!method compare_and_set(old_value, new_value)
79+
# @!macro atomic_reference_method_compare_and_set
80+
#
81+
# Atomically sets the value to the given updated value if
82+
# the current value == the expected value.
83+
#
84+
# @param [Object] old_value the expected value
85+
# @param [Object] new_value the new value
86+
#
87+
# @return [Boolean] `true` if successful. A `false` return indicates
88+
# that the actual value was not equal to the expected value.
89+
#
90+
# @!method update
91+
# Pass the current value to the given block, replacing it
92+
# with the block's result. May retry if the value changes
93+
# during the block's execution.
94+
#
95+
# @yield [Object] Calculate a new value for the atomic reference using
96+
# given (old) value
97+
# @yieldparam [Object] old_value the starting value of the atomic reference
98+
# @return [Object] the new value
99+
#
100+
# @!method try_update
101+
# Pass the current value to the given block, replacing it
102+
# with the block's result. Return nil if the update fails.
103+
#
104+
# @yield [Object] Calculate a new value for the atomic reference using
105+
# given (old) value
106+
# @yieldparam [Object] old_value the starting value of the atomic reference
107+
# @note This method was altered to avoid raising an exception by default.
108+
# Instead, this method now returns `nil` in case of failure. For more info,
109+
# please see: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
110+
# @return [Object] the new value, or nil if update failed
111+
#
112+
# @!method try_update!
113+
# Pass the current value to the given block, replacing it
114+
# with the block's result. Raise an exception if the update
115+
# fails.
116+
#
117+
# @yield [Object] Calculate a new value for the atomic reference using
118+
# given (old) value
119+
# @yieldparam [Object] old_value the starting value of the atomic reference
120+
# @note This behavior mimics the behavior of the original
121+
# `AtomicReference#try_update` API. The reason this was changed was to
122+
# avoid raising exceptions (which are inherently slow) by default. For more
123+
# info: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
124+
# @return [Object] the new value
125+
# @raise [Concurrent::ConcurrentUpdateError] if the update fails
102126
class AtomicReference < AtomicReferenceImplementation
103127

104128
# @return [String] Short string representation.

‎lib/concurrent-ruby/concurrent/atomic_reference/atomic_direct_update.rb

Lines changed: 0 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -7,34 +7,11 @@ module Concurrent
77
# @!visibility private
88
# @!macro internal_implementation_note
99
module AtomicDirectUpdate
10-
11-
# @!macro atomic_reference_method_update
12-
#
13-
# Pass the current value to the given block, replacing it
14-
# with the block's result. May retry if the value changes
15-
# during the block's execution.
16-
#
17-
# @yield [Object] Calculate a new value for the atomic reference using
18-
# given (old) value
19-
# @yieldparam [Object] old_value the starting value of the atomic reference
20-
# @return [Object] the new value
2110
def update
2211
true until compare_and_set(old_value = get, new_value = yield(old_value))
2312
new_value
2413
end
2514

26-
# @!macro atomic_reference_method_try_update
27-
#
28-
# Pass the current value to the given block, replacing it
29-
# with the block's result. Return nil if the update fails.
30-
#
31-
# @yield [Object] Calculate a new value for the atomic reference using
32-
# given (old) value
33-
# @yieldparam [Object] old_value the starting value of the atomic reference
34-
# @note This method was altered to avoid raising an exception by default.
35-
# Instead, this method now returns `nil` in case of failure. For more info,
36-
# please see: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
37-
# @return [Object] the new value, or nil if update failed
3815
def try_update
3916
old_value = get
4017
new_value = yield old_value
@@ -44,21 +21,6 @@ def try_update
4421
new_value
4522
end
4623

47-
# @!macro atomic_reference_method_try_update!
48-
#
49-
# Pass the current value to the given block, replacing it
50-
# with the block's result. Raise an exception if the update
51-
# fails.
52-
#
53-
# @yield [Object] Calculate a new value for the atomic reference using
54-
# given (old) value
55-
# @yieldparam [Object] old_value the starting value of the atomic reference
56-
# @note This behavior mimics the behavior of the original
57-
# `AtomicReference#try_update` API. The reason this was changed was to
58-
# avoid raising exceptions (which are inherently slow) by default. For more
59-
# info: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
60-
# @return [Object] the new value
61-
# @raise [Concurrent::ConcurrentUpdateError] if the update fails
6224
def try_update!
6325
old_value = get
6426
new_value = yield old_value

‎lib/concurrent-ruby/concurrent/synchronization.rb

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@
66
require 'concurrent/synchronization/lock'
77

88
module Concurrent
9-
# {include:file:docs-source/synchronization.md}
10-
# {include:file:docs-source/synchronization-notes.md}
9+
# @!visibility private
1110
module Synchronization
1211
end
1312
end

0 commit comments

Comments
 (0)