Merge pull request #322 from ruby-concurrency/api-private

Marked private API abstractions.

Author: jdantonio

lib/concurrent.rb

@@ -26,6 +26,11 @@
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
 
+# @!macro [new] internal_implementation_note
+#
+#   @note **Private Implementation:** This abstraction is a private, internal
+#     implementation detail. It should never be used directly.
+
 # @!macro [new] monotonic_clock_warning
 #
 #   @note Time calculations one all platforms and languages are sensitive to

lib/concurrent/actor.rb

@@ -11,6 +11,8 @@ module Concurrent
   # TODO more effective executor
 
   # {include:file:doc/actor/main.md}
+  # @api Actor
+  # @!macro edge_warning
   module Actor
 
     require 'concurrent/actor/type_check'

lib/concurrent/agent.rb

@@ -79,6 +79,8 @@ module Concurrent
   #
   # @!attribute [r] timeout
   #   @return [Fixnum] the maximum number of seconds before an update is cancelled
+  #
+  # @!macro edge_warning
   class Agent
     include Concern::Dereferenceable
     include Concern::Observable
@@ -91,7 +93,15 @@ class Agent
     #
     # @param [Object] initial the initial value
     #
-    # @!macro executor_and_deref_options
+    # @!macro [attach] executor_and_deref_options
+    #  
+    #   @param [Hash] opts the options used to define the behavior at update and deref
+    #     and to specify the executor on which to perform actions
+    #   @option opts [Executor] :executor when set use the given `Executor` instance.
+    #     Three special values are also supported: `:task` returns the global task pool,
+    #     `:operation` returns the global operation pool, and `:immediate` returns a new
+    #     `ImmediateExecutor` object.
+    #   @!macro deref_options
     def initialize(initial, opts = {})
       @value                = initial
       @rescuers             = []

lib/concurrent/atomic/atomic_boolean.rb

@@ -22,6 +22,10 @@ module Concurrent
   #         3.340000   0.010000   3.350000 (  0.855000)
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicBoolean.html java.util.concurrent.atomic.AtomicBoolean
+  #
+  # @!visibility private
+  #
+  # @!macro internal_implementation_note
   class MutexAtomicBoolean < Synchronization::Object
 
     # @!macro [attach] atomic_boolean_method_initialize
@@ -105,6 +109,8 @@ def ns_make_value(value)
     end
   end
 
+  # @!visibility private
+  # @!macro internal_implementation_note
   AtomicBooleanImplementation = case
                                 when Concurrent.on_jruby?
                                   JavaAtomicBoolean

lib/concurrent/atomic/atomic_fixnum.rb

@@ -22,6 +22,9 @@ module Concurrent
   #         4.520000   0.030000   4.550000 (  1.187000)
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicLong.html java.util.concurrent.atomic.AtomicLong
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
   class MutexAtomicFixnum < Synchronization::Object
 
     # http://stackoverflow.com/questions/535721/ruby-max-integer
@@ -132,6 +135,8 @@ def range_check!(value)
     end
   end
 
+  # @!visibility private
+  # @!macro internal_implementation_note
   AtomicFixnumImplementation = case
                                when Concurrent.on_jruby?
                                  JavaAtomicFixnum

lib/concurrent/atomic/count_down_latch.rb

@@ -11,6 +11,9 @@ module Concurrent
   #   method. Each of the other threads calls `#count_down` when done with its work.
   #   When the latch counter reaches zero the waiting thread is unblocked and continues
   #   with its work. A `CountDownLatch` can be used only once. Its value cannot be reset.
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
   class PureCountDownLatch < Synchronization::Object
 
     # @!macro [attach] count_down_latch_method_initialize
@@ -69,6 +72,8 @@ def ns_initialize(count)
   if Concurrent.on_jruby?
 
     # @!macro count_down_latch
+    # @!visibility private
+    # @!macro internal_implementation_note
     class JavaCountDownLatch
 
       # @!macro count_down_latch_method_initialize

lib/concurrent/atomic/cyclic_barrier.rb

@@ -4,6 +4,7 @@ module Concurrent
 
   class CyclicBarrier < Synchronization::Object
 
+    # @!visibility private
     Generation = Struct.new(:status)
     private_constant :Generation
 

lib/concurrent/atomic/semaphore.rb

@@ -10,6 +10,10 @@ module Concurrent
   #   releasing a blocking acquirer.
   #   However, no actual permit objects are used; the Semaphore just keeps a
   #   count of the number available and acts accordingly.
+  #
+  # @!visibility private
+  #
+  # @!macro internal_implementation_note
   class MutexSemaphore < Synchronization::Object
 
     # @!macro [attach] semaphore_method_initialize
@@ -163,6 +167,8 @@ def try_acquire_timed(permits, timeout)
     end
   end
 
+  # @!visibility private
+  # @!macro internal_implementation_note
   SemaphoreImplementation = case
                             when Concurrent.on_jruby?
                               JavaSemaphore

lib/concurrent/atomic/thread_local_var.rb

@@ -32,8 +32,11 @@ module Concurrent
   #     v.value #=> 14
   #
   #   @see https://docs.oracle.com/javase/7/docs/api/java/lang/ThreadLocal.html Java ThreadLocal
+  #
+  # @!visibility private
   class AbstractThreadLocalVar
 
+    # @!visibility private
     NIL_SENTINEL = Object.new
     private_constant :NIL_SENTINEL
 
@@ -112,6 +115,8 @@ def set(value)
     end
   end
 
+  # @!visibility private
+  # @!macro internal_implementation_note
   class RubyThreadLocalVar < AbstractThreadLocalVar
 
     protected
@@ -144,6 +149,8 @@ def set(value)
 
   if Concurrent.on_jruby?
 
+    # @!visibility private
+    # @!macro internal_implementation_note
     class JavaThreadLocalVar < AbstractThreadLocalVar
 
       protected
@@ -165,6 +172,8 @@ def set(value)
     end
   end
 
+  # @!visibility private
+  # @!macro internal_implementation_note
   ThreadLocalVarImplementation = case
                                  when Concurrent.on_jruby?
                                    JavaThreadLocalVar
@@ -174,9 +183,6 @@ def set(value)
   private_constant :ThreadLocalVarImplementation
 
   # @!macro thread_local_var
-  #
-  # @see Concurrent::AbstractThreadLocalVar
-  # @see Concurrent::RubyThreadLocalVar
   class ThreadLocalVar < ThreadLocalVarImplementation
 
     # @!method initialize(default = nil)

lib/concurrent/atomic/thread_local_var/weak_key_map.rb

@@ -21,6 +21,7 @@
 
 module Concurrent
 
+  # @!visibility private
   class AbstractThreadLocalVar
 
     begin