Class: Tasker::Orchestration::FutureStateAnalyzer

Inherits:
Object
  • Object
show all
Defined in:
lib/tasker/orchestration/future_state_analyzer.rb

Overview

Abstraction layer for analyzing Concurrent::Future states in our domain context

This class encapsulates the complex state logic around Concurrent::Future objects, providing domain-specific methods that express our actual intentions rather than requiring callers to understand the intricacies of the Future state machine.

The Concurrent::Future state machine has these states:

  • unscheduled: Created but not yet executed
  • pending: Scheduled but not yet started
  • executing: Currently running
  • fulfilled: Completed successfully
  • rejected: Completed with error
  • cancelled: Cancelled before completion

Our domain needs are:

  • Should we cancel this future? (pending futures)
  • Should we wait for this future? (executing futures)
  • Can we ignore this future? (completed or unscheduled futures)

Instance Method Summary collapse

Constructor Details

#initialize(future) ⇒ FutureStateAnalyzer

Initialize with a Concurrent::Future object

Parameters:

  • future (Concurrent::Future) —

    The future to analyze



27
28
29
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 27

def initialize(future)
  @future = future
end

Instance Method Details

#can_ignore? ⇒ Boolean

Can we safely ignore this future during cleanup?

We can ignore futures that are either:

  • Already completed (fulfilled, rejected, or cancelled)
  • Never scheduled (unscheduled)

Returns:

  • (Boolean) —

    true if this future can be ignored



63
64
65
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 63

def can_ignore?
  completed? || unscheduled?
end

#completed? ⇒ Boolean

Is this future completed (in any completion state)?

A future is completed if it's fulfilled, rejected, or cancelled.

Returns:

  • (Boolean) —

    true if the future has completed



81
82
83
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 81

def completed?
  @future.complete?
end

#debug_state ⇒ Hash

Get detailed state information for debugging

Returns:

  • (Hash) —

    Detailed state information



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 118

def debug_state
  {
    state_description: state_description,
    should_cancel: should_cancel?,
    should_wait: should_wait_for_completion?,
    can_ignore: can_ignore?,
    raw_states: {
      pending: @future.pending?,
      complete: @future.complete?,
      incomplete: @future.incomplete?,
      unscheduled: @future.unscheduled?,
      fulfilled: @future.fulfilled?,
      rejected: @future.rejected?,
      cancelled: @future.cancelled?
    }
  }
end

#executing? ⇒ Boolean

Is this future currently executing?

A future is executing if it has been scheduled, started, but not completed.

Returns:

  • (Boolean) —

    true if the future is actively executing



72
73
74
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 72

def executing?
  @future.incomplete? && !@future.unscheduled? && !@future.pending?
end

#pending? ⇒ Boolean

Is this future pending (scheduled but not started)?

A pending future has been scheduled for execution but hasn't started yet.

Returns:

  • (Boolean) —

    true if the future is pending



97
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 97

delegate :pending?, to: :@future

#should_cancel? ⇒ Boolean

Should this future be cancelled during cleanup?

We cancel futures that are pending (scheduled but not started). This prevents them from starting when we're trying to clean up.

Returns:

  • (Boolean) —

    true if the future should be cancelled



37
38
39
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 37

def should_cancel?
  @future.pending?
end

#should_wait_for_completion? ⇒ Boolean

Should we wait for this future to complete during cleanup?

We wait for futures that are actively executing to give them a chance to complete gracefully before forcing cleanup.

A future is "executing" if:

  • It's incomplete (not finished)
  • It's scheduled (not unscheduled)
  • It's not pending (it has started)

Returns:

  • (Boolean) —

    true if we should wait for this future



52
53
54
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 52

def should_wait_for_completion?
  executing?
end

#state_description ⇒ String

Get a human-readable description of the future's state

This is useful for logging and debugging.

Returns:

  • (String) —

    A description of the current state



104
105
106
107
108
109
110
111
112
113
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 104

def state_description
  return 'unscheduled' if unscheduled?
  return 'pending' if pending?
  return 'executing' if executing?
  return 'fulfilled' if @future.fulfilled?
  return 'rejected' if @future.rejected?
  return 'cancelled' if @future.cancelled?

  'unknown'
end

#unscheduled? ⇒ Boolean

Is this future unscheduled (never started)?

An unscheduled future was created but never executed.

Returns:

  • (Boolean) —

    true if the future is unscheduled



90
 
# File 'lib/tasker/orchestration/future_state_analyzer.rb', line 90

delegate :unscheduled?, to: :@future