farce 0.1.0-java → 0.2.0-java

data/lib/farce/abstract/scheduler.rb

@@ -6,7 +6,7 @@ module Farce
   module Abstract
     # @abstract A shared super class for all scheduler implementations.
     #
-    # @!method schedule(*args, mode: :copy, auto_local: true)
+    # @!method schedule(*args, mode: :smart, auto_local: true)
     #   @abstract This method must be implemented by concrete scheduler subclasses.
     #
     #   Schedules a block for execution.
@@ -23,7 +23,7 @@ module Farce
     #     May be handled according to `mode`.
     #
     #   @param mode [Symbol]
-    #     The mode in which to schedule the task. Defaults to `:copy`.
+    #     The mode in which to schedule the task. Defaults to `:smart`.
     #     May be ignored by some schedulers.
     #
     #   @param auto_local [Boolean]
@@ -82,7 +82,7 @@ module Farce
       #
       # @param (see #schedule)
       # @return [self]
-      def execute(*, mode: :copy, auto_local: true, &callback)
+      def execute(*, mode: :smart, auto_local: true, &callback)
         raise LocalJumpError, "Cannot yield without a block" unless block_given?
         raise SchedulerClosedError, "cannot execute task on a closed scheduler" if closed?
 

data/lib/farce/abstract/set.rb

@@ -61,7 +61,7 @@ module Farce
       # @param normalize [Symbol, Proc, Hash, Farce::Abstract::Map, nil] The element normalizer.
       # @param compare_by_identity [Boolean] Whether membership uses object identity.
       # @param mode [Symbol] The default transfer mode for Farce::Set, Farce::SortedSet,
-      #   and Farce::WeakSet. Defaults to :copy for strong sets and :raise for WeakSet.
+      #   and Farce::WeakSet. Defaults to :smart for strong sets and :raise for WeakSet.
       # @param options [Hash] Additional options for the selected variant.
       # @option options [Symbol] scope (:ractor) The scope used by Farce::Local variants.
       # @yield [element] Optionally transform each initial element before storage.
@@ -753,11 +753,22 @@ module Farce
       def prepare_mode_entry(element, requested_mode)
         if identity_membership?(element) && !Ractor.shareable?(element)
           case requested_mode
-          when :copy
+          when :copy, :marshal
             raise ArgumentError, "identity comparison cannot copy a non-shareable element"
           when :shareable_copy, :make_shareable
             payload = @manager.wrap(element, mode: requested_mode)
             return [insertion_key(payload), payload]
+          when :smart, :smart_raise, :smart_copy, :smart_move
+            token = IDENTITY_TOKENS[element]
+            payload = @manager.wrap(element, mode: requested_mode)
+            case payload
+            when Envelope::Copy, Envelope::Marshal
+              raise ArgumentError, "identity comparison cannot copy a non-shareable element"
+            when Envelope::Move
+              return [MembershipKey.new(token || Object.new.freeze, identity: true), payload]
+            end
+            key = @manager.managed_envelope?(payload) ? insertion_key(element) : insertion_key(payload)
+            return [key, payload]
           end
         end
 
@@ -812,9 +823,10 @@ module Farce
 
       def stored_mode(entry)
         case entry.payload
-        when Envelope::Copy  then :copy
-        when Envelope::Local then :local
-        when Envelope::Move  then :move
+        when Envelope::Copy    then :copy
+        when Envelope::Marshal then :marshal
+        when Envelope::Local   then :local
+        when Envelope::Move    then :move
         else @manager.mode
         end
       end

data/lib/farce/abstract/sorted_set.rb

@@ -11,12 +11,12 @@ module Farce
     # elements raise during insertion or lookup.
     class SortedSet < Set
       # Construct a set in ascending comparator order.
-      # @overload initialize(enumerable = nil, normalize: nil, compare_by_identity: false, mode: :copy, **options)
+      # @overload initialize(enumerable = nil, normalize: nil, compare_by_identity: false, mode: :smart, **options)
       #   @param enumerable [#each, nil] The initial elements, or nil for an empty set.
       #   @param normalize [Symbol, Proc, Hash, Farce::Abstract::Map, nil] The element normalizer.
       #   @param compare_by_identity [Boolean] Must be false. Membership uses <=>.
       #   @param mode [Symbol] The default transfer mode. Only Farce::SortedSet accepts
-      #     this option, which defaults to :copy.
+      #     this option, which defaults to :smart.
       #   @param options [Hash] Additional options for the selected variant.
       #   @option options [Symbol] scope (:ractor) The scope used by Farce::Local::SortedSet.
       #   @yield [element] Optionally transform each initial element before normalization.

data/lib/farce/abstract/timer_queue.rb

@@ -8,6 +8,37 @@ module Farce
     class TimerQueue < Queue
       include Internal::BlockingPriorityQueue
 
+      # A handle for canceling a scheduled value.
+      # Entries keep the stored value private, so canceling a moved value does not claim it.
+      # With local queues, cancellation uses the current scope.
+      #
+      # @example Cancel a delayed value
+      #   queue = Farce::TimerQueue.new
+      #   entry = queue.push(:work, delay: 60)
+      #   entry.delete # => true
+      class Entry
+        # @return [Float] the scheduled monotonic clock time
+        attr_reader :clock
+
+        # @return [Farce::Abstract::TimerQueue] the queue that created this entry
+        attr_reader :queue
+
+        # @api private
+        def initialize(value, clock, queue)
+          @value = value
+          @clock = clock
+          @queue = queue
+          freeze
+        end
+
+        # Cancel the scheduled value by identity at its exact timestamp.
+        # If the same value was queued more than once at that timestamp, delete the oldest match.
+        # @return [Boolean] whether a value was deleted
+        # @raise [Farce::ClosedQueueError] when the queue is closed
+        def delete = queue.delete(@value, at: clock, compare_by_identity: true)
+        alias cancel delete
+      end
+
       # @param capacity [Integer, nil] the maximum number of values, or nil for an unbounded queue
       def initialize(capacity: nil, track_age: false)
         super
@@ -22,10 +53,11 @@ module Farce
       #   With no scheduling option, the value is available immediately. Since `timeout:` controls the capacity wait,
       #   use `delay:` or `wait:` to schedule a relative offset.
       # @raise [ThreadError] when the queue is at capacity and non_block is true
-      # @return [Boolean] whether the value was added
+      # @return [Entry, false] the cancellation handle, or false if the capacity wait expires
       def push(value, non_block = false, timeout: nil, **time_options) # rubocop:disable Style/OptionalBooleanParameter
         at = Clock.parse(time_options)
-        push_to_storage(at, non_block, value, timeout:)
+        entry = Entry.new(value, at, self)
+        push_to_storage(at, non_block, value, timeout:) && entry
       end
 
       # Remove the earliest value, waiting until its timestamp is reached.
@@ -50,10 +82,11 @@ module Farce
       #   `at:`, `time:`, `timeout_at:`, `delay:`, `in:`, `offset:`, `timeout:`, `wait:`, or `clock:`.
       #   With no scheduling option, the value is available immediately.
       # @yield called when the queue is at capacity
-      # @return [Boolean, BasicObject] true, or the fallback result when full
+      # @return [Entry, BasicObject] the cancellation handle, or the fallback result when full
       def try_push(value, **time_options)
         at = Clock.parse(time_options)
-        return true if internal_queue.push(at, value)
+        entry = Entry.new(value, at, self)
+        return entry if internal_queue.push(at, value)
         block_given? ? yield : false
       end
 
@@ -100,12 +133,18 @@ module Farce
         !UNDEFINED.equal?(wait_for_timestamp(timeout_at(timeout)))
       end
 
-      # Delete the oldest matching value at the exact time.
-      # @param value [BasicObject] the value to delete
-      # @param at [Numeric, Time] the exact time to search
-      # @param compare_by_identity [Boolean] compare values by identity instead of equality
-      # @return [Boolean] whether a value was deleted
-      def delete(value, at:, compare_by_identity: false)
+      # Cancel an entry, or delete the oldest matching value at the exact time.
+      # Pass `at:` to delete an Entry that was itself queued as a value.
+      # @param value [Entry, BasicObject] the cancellation handle or value to delete
+      # @param at [Numeric, Time] the exact time to search, required when deleting a value
+      # @param compare_by_identity [Boolean] compare values by identity instead of equality when `at:` is given
+      # @return [Boolean] whether a value was deleted, or false if the entry belongs to another queue
+      # @raise [ArgumentError] when deleting a value without `at:`
+      def delete(value, at: UNDEFINED, compare_by_identity: false)
+        if UNDEFINED.equal?(at)
+          raise ArgumentError, "at: is required when deleting a value" unless Entry === value
+          return value.queue.equal?(self) && value.delete
+        end
         delete_from_storage(Clock.at(at), value, compare_by_identity:)
       end