simple_flow 0.1.0

data/examples/09_pipeline_visualization.rb

@@ -0,0 +1,266 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/simple_flow'
+require 'timecop'
+Timecop.travel(Time.local(2001, 9, 11, 7, 0, 0))
+
+# Direct pipeline visualization - no need to recreate dependency structure!
+
+puts "=" * 60
+puts "Direct Pipeline Visualization"
+puts "=" * 60
+puts
+
+# Example 1: Visualize directly from pipeline
+puts "Example 1: Simple Pipeline Visualization"
+puts "-" * 60
+puts
+
+pipeline = SimpleFlow::Pipeline.new do
+  step :validate, ->(result) {
+    result.with_context(:validated, true).continue(result.value)
+  }, depends_on: :none
+
+  step :fetch_data, ->(result) {
+    result.with_context(:data, [1, 2, 3]).continue(result.value)
+  }, depends_on: [:validate]
+
+  step :process_data, ->(result) {
+    result.continue(result.value * 2)
+  }, depends_on: [:fetch_data]
+end
+
+# Visualize directly - no manual graph creation needed!
+puts pipeline.visualize_ascii
+puts
+
+# Example 2: E-commerce pipeline with parallel steps
+puts "\n" + "=" * 60
+puts "Example 2: E-commerce Pipeline (Automatic Visualization)"
+puts "=" * 60
+puts
+
+ecommerce_pipeline = SimpleFlow::Pipeline.new do
+  step :validate_order, ->(result) {
+    result.continue(result.value)
+  }, depends_on: :none
+
+  # These will run in parallel
+  step :check_inventory, ->(result) {
+    result.with_context(:inventory, :ok).continue(result.value)
+  }, depends_on: [:validate_order]
+
+  step :calculate_shipping, ->(result) {
+    result.with_context(:shipping, 10).continue(result.value)
+  }, depends_on: [:validate_order]
+
+  step :calculate_totals, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:check_inventory, :calculate_shipping]
+
+  step :process_payment, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:calculate_totals]
+
+  step :reserve_inventory, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:process_payment]
+
+  step :create_shipment, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:reserve_inventory]
+
+  # These will run in parallel
+  step :send_email, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:create_shipment]
+
+  step :send_sms, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:create_shipment]
+
+  step :finalize_order, ->(result) {
+    result.continue("Order complete!")
+  }, depends_on: [:send_email, :send_sms]
+end
+
+# Display the visualization
+puts ecommerce_pipeline.visualize_ascii
+puts
+
+# Example 3: Get execution plan
+puts "\n" + "=" * 60
+puts "Example 3: Execution Plan (Direct from Pipeline)"
+puts "=" * 60
+puts
+
+puts ecommerce_pipeline.execution_plan
+puts
+
+# Example 4: Export to different formats
+puts "\n" + "=" * 60
+puts "Example 4: Export Formats (Direct from Pipeline)"
+puts "=" * 60
+puts
+
+# Export to Graphviz DOT
+File.write('pipeline_graph.dot', ecommerce_pipeline.visualize_dot)
+puts "✓ Exported to Graphviz DOT: pipeline_graph.dot"
+puts "  Generate image: dot -Tpng pipeline_graph.dot -o pipeline.png"
+puts
+
+# Export to Mermaid
+File.write('pipeline_graph.mmd', ecommerce_pipeline.visualize_mermaid)
+puts "✓ Exported to Mermaid: pipeline_graph.mmd"
+puts "  View at: https://mermaid.live/"
+puts
+
+# Export to HTML (need the visualizer object for this)
+if visualizer = ecommerce_pipeline.visualize
+  File.write('pipeline_graph.html', visualizer.to_html(title: "E-commerce Pipeline"))
+  puts "✓ Exported to HTML: pipeline_graph.html"
+  puts "  Open in browser for interactive visualization"
+end
+puts
+
+# Example 5: ETL Pipeline
+puts "\n" + "=" * 60
+puts "Example 5: ETL Pipeline Visualization"
+puts "=" * 60
+puts
+
+etl_pipeline = SimpleFlow::Pipeline.new do
+  # Extract phase - all run in parallel
+  step :extract_users, ->(result) {
+    result.with_context(:users, []).continue(result.value)
+  }, depends_on: :none
+
+  step :extract_orders, ->(result) {
+    result.with_context(:orders, []).continue(result.value)
+  }, depends_on: :none
+
+  step :extract_products, ->(result) {
+    result.with_context(:products, []).continue(result.value)
+  }, depends_on: :none
+
+  # Transform phase - all run in parallel after extraction
+  step :transform_users, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:extract_users]
+
+  step :transform_orders, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:extract_orders]
+
+  step :transform_products, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:extract_products]
+
+  # Aggregate phase - can run in parallel
+  step :aggregate_user_stats, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:transform_users, :transform_orders]
+
+  step :aggregate_category_stats, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:transform_products]
+
+  # Validate
+  step :validate_data, ->(result) {
+    result.continue(result.value)
+  }, depends_on: [:aggregate_user_stats]
+
+  # Load
+  step :prepare_output, ->(result) {
+    result.continue("ETL Complete!")
+  }, depends_on: [:validate_data, :aggregate_category_stats]
+end
+
+puts etl_pipeline.execution_plan
+puts
+
+# Example 6: Check if pipeline can be visualized
+puts "\n" + "=" * 60
+puts "Example 6: Checking Visualization Availability"
+puts "=" * 60
+puts
+
+# Pipeline with named steps - can be visualized
+named_pipeline = SimpleFlow::Pipeline.new do
+  step :step_a, ->(r) { r.continue(r.value) }, depends_on: :none
+  step :step_b, ->(r) { r.continue(r.value) }, depends_on: [:step_a]
+end
+
+# Pipeline with unnamed steps - cannot be auto-visualized
+unnamed_pipeline = SimpleFlow::Pipeline.new do
+  step ->(r) { r.continue(r.value) }
+  step ->(r) { r.continue(r.value) }
+end
+
+puts "Named pipeline has dependency graph? #{!named_pipeline.dependency_graph.nil?}"
+puts "Unnamed pipeline has dependency graph? #{!unnamed_pipeline.dependency_graph.nil?}"
+puts
+puts "Note: Only pipelines with named steps and dependencies can be auto-visualized"
+puts
+
+# Example 7: Working with the dependency graph directly
+puts "\n" + "=" * 60
+puts "Example 7: Advanced - Access Dependency Graph"
+puts "=" * 60
+puts
+
+if graph = ecommerce_pipeline.dependency_graph
+  puts "Pipeline dependency information:"
+  puts "  Total steps: #{graph.dependencies.size}"
+  puts "  Execution phases: #{graph.parallel_order.size}"
+  puts "  Parallel groups:"
+  graph.parallel_order.each_with_index do |group, idx|
+    puts "    Phase #{idx + 1}: #{group.join(', ')}"
+  end
+end
+puts
+
+# Example 8: Compare different pipeline structures
+puts "\n" + "=" * 60
+puts "Example 8: Pipeline Structure Comparison"
+puts "=" * 60
+puts
+
+# Linear pipeline
+linear = SimpleFlow::Pipeline.new do
+  step :step1, ->(r) { r.continue(r.value) }, depends_on: :none
+  step :step2, ->(r) { r.continue(r.value) }, depends_on: [:step1]
+  step :step3, ->(r) { r.continue(r.value) }, depends_on: [:step2]
+  step :step4, ->(r) { r.continue(r.value) }, depends_on: [:step3]
+end
+
+# Parallel pipeline
+parallel = SimpleFlow::Pipeline.new do
+  step :start, ->(r) { r.continue(r.value) }, depends_on: :none
+  step :task1, ->(r) { r.continue(r.value) }, depends_on: [:start]
+  step :task2, ->(r) { r.continue(r.value) }, depends_on: [:start]
+  step :task3, ->(r) { r.continue(r.value) }, depends_on: [:start]
+  step :end, ->(r) { r.continue(r.value) }, depends_on: [:task1, :task2, :task3]
+end
+
+puts "Linear Pipeline:"
+puts linear.execution_plan
+puts
+
+puts "\nParallel Pipeline:"
+puts parallel.execution_plan
+puts
+
+puts "=" * 60
+puts "Direct pipeline visualization completed!"
+puts
+puts "Key Takeaway:"
+puts "  No need to manually recreate dependency structures!"
+puts "  Just call pipeline.visualize_ascii, pipeline.visualize_dot, etc."
+puts
+puts "Generated files:"
+puts "  - pipeline_graph.dot"
+puts "  - pipeline_graph.mmd"
+puts "  - pipeline_graph.html"
+puts "=" * 60

data/examples/10_concurrency_control.rb

@@ -0,0 +1,235 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/simple_flow'
+require 'timecop'
+Timecop.travel(Time.local(2001, 9, 11, 7, 0, 0))
+
+# Controlling Concurrency Model Per Pipeline
+
+puts "=" * 60
+puts "Per-Pipeline Concurrency Control"
+puts "=" * 60
+puts
+
+# Check async availability
+async_available = SimpleFlow::ParallelExecutor.async_available?
+puts "Async gem available: #{async_available ? '✓ Yes' : '✗ No'}"
+puts
+
+# Example 1: Auto-detect (default behavior)
+puts "Example 1: Auto-Detect Concurrency (Default)"
+puts "-" * 60
+puts
+
+pipeline_auto = SimpleFlow::Pipeline.new do  # concurrency: :auto is default
+  step ->(result) {
+    puts "  Processing with auto-detected concurrency..."
+    result.continue(result.value)
+  }
+end
+
+puts "Pipeline concurrency setting: #{pipeline_auto.concurrency}"
+puts "Will use: #{async_available ? 'Async (fiber-based)' : 'Threads'}"
+puts
+
+# Example 2: Force threads (even if async is available)
+puts "\nExample 2: Force Threads"
+puts "-" * 60
+puts
+
+pipeline_threads = SimpleFlow::Pipeline.new(concurrency: :threads) do
+  parallel do
+    step ->(result) {
+      puts "  [Thread-based] Task A running..."
+      sleep 0.05
+      result.with_context(:task_a, :done).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Thread-based] Task B running..."
+      sleep 0.05
+      result.with_context(:task_b, :done).continue(result.value)
+    }
+
+    step ->(result) {
+      puts "  [Thread-based] Task C running..."
+      sleep 0.05
+      result.with_context(:task_c, :done).continue(result.value)
+    }
+  end
+end
+
+puts "Pipeline concurrency setting: #{pipeline_threads.concurrency}"
+puts "Will use: Ruby Threads (even if async is available)"
+
+result = pipeline_threads.call(SimpleFlow::Result.new(nil))
+puts "Result context: #{result.context}"
+puts
+
+# Example 3: Force async (requires async gem)
+puts "\nExample 3: Force Async"
+puts "-" * 60
+puts
+
+if async_available
+  pipeline_async = SimpleFlow::Pipeline.new(concurrency: :async) do
+    step :validate, ->(result) {
+      puts "  [Async] Validating..."
+      result.continue(result.value)
+    }, depends_on: :none
+
+    step :fetch_a, ->(result) {
+      puts "  [Async] Fetching A..."
+      sleep 0.05
+      result.with_context(:a, :done).continue(result.value)
+    }, depends_on: [:validate]
+
+    step :fetch_b, ->(result) {
+      puts "  [Async] Fetching B..."
+      sleep 0.05
+      result.with_context(:b, :done).continue(result.value)
+    }, depends_on: [:validate]
+
+    step :merge, ->(result) {
+      puts "  [Async] Merging results..."
+      result.continue("Complete")
+    }, depends_on: [:fetch_a, :fetch_b]
+  end
+
+  puts "Pipeline concurrency setting: #{pipeline_async.concurrency}"
+  puts "Will use: Async (fiber-based concurrency)"
+
+  result2 = pipeline_async.call_parallel(SimpleFlow::Result.new(nil))
+  puts "Result: #{result2.value}"
+  puts "Context: #{result2.context}"
+else
+  puts "Cannot create async pipeline - async gem not available"
+  puts "Would raise: ArgumentError: Concurrency set to :async but async gem is not available"
+end
+puts
+
+# Example 4: Different pipelines, different concurrency
+puts "\nExample 4: Mixed Concurrency in Same Application"
+puts "-" * 60
+puts
+
+# Low-volume user pipeline - threads are simpler
+user_pipeline = SimpleFlow::Pipeline.new(concurrency: :threads) do
+  step :validate, ->(result) {
+    puts "  [User/Threads] Validating user..."
+    result.continue(result.value)
+  }, depends_on: :none
+
+  step :fetch_profile, ->(result) {
+    puts "  [User/Threads] Fetching profile..."
+    sleep 0.02
+    result.with_context(:profile, { name: "John" }).continue(result.value)
+  }, depends_on: [:validate]
+
+  step :fetch_settings, ->(result) {
+    puts "  [User/Threads] Fetching settings..."
+    sleep 0.02
+    result.with_context(:settings, { theme: "dark" }).continue(result.value)
+  }, depends_on: [:validate]
+end
+
+# High-volume batch pipeline - use async if available
+batch_concurrency = async_available ? :async : :threads
+batch_pipeline = SimpleFlow::Pipeline.new(concurrency: batch_concurrency) do
+  step :load, ->(result) {
+    puts "  [Batch/#{batch_concurrency.to_s.capitalize}] Loading batch..."
+    result.continue(result.value)
+  }, depends_on: :none
+
+  step :process_batch_1, ->(result) {
+    puts "  [Batch/#{batch_concurrency.to_s.capitalize}] Processing batch 1..."
+    sleep 0.02
+    result.with_context(:batch_1, :done).continue(result.value)
+  }, depends_on: [:load]
+
+  step :process_batch_2, ->(result) {
+    puts "  [Batch/#{batch_concurrency.to_s.capitalize}] Processing batch 2..."
+    sleep 0.02
+    result.with_context(:batch_2, :done).continue(result.value)
+  }, depends_on: [:load]
+end
+
+puts "User pipeline uses: #{user_pipeline.concurrency}"
+puts "Batch pipeline uses: #{batch_pipeline.concurrency}"
+puts
+
+puts "Running user pipeline..."
+user_result = user_pipeline.call_parallel(SimpleFlow::Result.new({ user_id: 123 }))
+puts "User result: #{user_result.context}"
+
+puts "\nRunning batch pipeline..."
+batch_result = batch_pipeline.call_parallel(SimpleFlow::Result.new({ batch_id: 456 }))
+puts "Batch result: #{batch_result.context}"
+puts
+
+# Example 5: Error handling for invalid concurrency
+puts "\nExample 5: Error Handling"
+puts "-" * 60
+puts
+
+puts "Valid options: :auto, :threads, :async"
+puts
+
+begin
+  invalid_pipeline = SimpleFlow::Pipeline.new(concurrency: :invalid) do
+    step ->(result) { result.continue(result.value) }
+  end
+rescue ArgumentError => e
+  puts "✓ Caught expected error for invalid concurrency:"
+  puts "  #{e.message}"
+end
+
+puts
+
+unless async_available
+  begin
+    async_pipeline = SimpleFlow::Pipeline.new(concurrency: :async) do
+      step ->(result) { result.continue(result.value) }
+    end
+  rescue ArgumentError => e
+    puts "✓ Caught expected error when async not available:"
+    puts "  #{e.message}"
+  end
+end
+
+puts
+
+# Example 6: Checking pipeline concurrency setting
+puts "\nExample 6: Inspecting Concurrency Settings"
+puts "-" * 60
+puts
+
+pipelines = [
+  SimpleFlow::Pipeline.new,                            # default
+  SimpleFlow::Pipeline.new(concurrency: :auto),       # explicit auto
+  SimpleFlow::Pipeline.new(concurrency: :threads),    # threads
+]
+
+if async_available
+  pipelines << SimpleFlow::Pipeline.new(concurrency: :async)  # async
+end
+
+pipelines.each_with_index do |pipeline, index|
+  puts "Pipeline #{index + 1}:"
+  puts "  Concurrency: #{pipeline.concurrency}"
+  puts "  Async available: #{pipeline.async_available?}"
+  puts
+end
+
+puts "=" * 60
+puts "Concurrency control examples completed!"
+puts "=" * 60
+puts
+puts "Key Takeaways:"
+puts "  • concurrency: :auto (default) - auto-detects best option"
+puts "  • concurrency: :threads - always uses Ruby threads"
+puts "  • concurrency: :async - requires async gem, uses fibers"
+puts "  • Different pipelines can use different concurrency models"
+puts "  • Choose based on your specific workload requirements"
+puts