fractor 0.1.6 → 0.1.8

data/docs/_reference/examples.adoc

@@ -0,0 +1,181 @@
+---
+layout: default
+title: Examples
+nav_order: 3
+---
+= Examples
+
+== Running a basic example
+
+. Install the gem as described in the link:../installation/[Installation] section.
+
+. Create a new Ruby file (e.g., `my_fractor_example.rb`) with your implementation:
++
+[source,ruby]
+----
+require 'fractor'
+
+# Define your Work class
+class MyWork < Fractor::Work
+  def to_s
+    "MyWork: #{@input}"
+  end
+end
+
+# Define your Worker class
+class MyWorker < Fractor::Worker
+  def process(work)
+    if work.input == 5
+      # Return a Fractor::WorkResult for errors
+      return Fractor::WorkResult.new(
+        error: "Error processing work #{work.input}",
+        work: work
+      )
+    end
+
+    calculated = work.input * 2
+    # Return a Fractor::WorkResult for success
+    Fractor::WorkResult.new(result: calculated, work: work)
+  end
+end
+
+# Create supervisor with a worker pool
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: MyWorker, num_workers: 2 }
+  ]
+)
+
+# Create Work objects
+work_items = (1..10).map { |i| MyWork.new(i) }
+
+# Add work items
+supervisor.add_work_items(work_items)
+
+# Run processing
+supervisor.run
+
+# Display results
+puts "Results: #{supervisor.results.results.map(&:result).join(', ')}"
+puts "Errors: #{supervisor.results.errors.map { |e| e.work.input }.join(', ')}"
+----
+
+. Run the example from your terminal:
++
+[source,sh]
+----
+ruby my_fractor_example.rb
+----
++
+You will see output showing Ractors starting, receiving work, processing it, and the final aggregated results, including any errors encountered. Press `Ctrl+C` during execution to test the graceful shutdown.
+
+== Examples by category
+
+Fractor includes comprehensive examples demonstrating various patterns and use cases:
+
+=== Pipeline mode examples
+
+For batch processing and one-time computations, see:
+
+* link:../guides/pipeline-mode.adoc#pipeline-mode-examples[Pipeline Mode Examples]
+  ** Simple example - Basic framework usage
+  ** Auto-detection example - Worker configuration
+  ** Hierarchical hasher - File chunking and parallel hashing
+  ** Multi-work type - Polymorphic workers
+  ** Pipeline processing - Multi-stage transformations
+  ** Producer/subscriber - Hierarchical processing
+  ** Scatter/gather - Task decomposition
+  ** Specialized workers - Domain-specific workers
+
+=== Continuous mode examples
+
+For long-running servers and stream processing, see:
+
+* link:../guides/continuous-mode.adoc#continuous-mode-examples[Continuous Mode Examples]
+  ** Plain socket implementation - Baseline comparison
+  ** Fractor-based chat server - Production-ready server with high-level primitives
+
+=== Workflow examples
+
+For complex data processing pipelines, see:
+
+* link:../features/workflows.adoc#workflow-examples[Workflow Examples]
+  ** Simple linear workflow - Sequential job pipeline
+  ** Fan-out workflow - Parallel job execution with aggregation
+  ** Conditional workflow - Runtime conditional execution
+  ** Simplified workflow - Reduced-boilerplate syntax
+  ** YAML workflows - Configuration-driven definitions
+  ** Builder API - Programmatic workflow construction
+
+=== Monitoring and analytics examples
+
+For production monitoring and error analysis, see:
+
+* link:../features/error-handling/[Error Handling] - Comprehensive error analytics
+  ** Error aggregation by category and job
+  ** Real-time error handlers and alerts
+  ** Trending error detection
+  ** Multiple export formats (text, Prometheus, JSON)
+  ** Critical error highlighting
+
+The error reporting example demonstrates:
+
+[source,ruby]
+----
+# Set up error reporter
+reporter = Fractor::ErrorReporter.new
+
+# Register critical error alerts
+reporter.on_error do |work_result, job_name|
+  if work_result.critical?
+    PagerDuty.alert(work_result, job_name)
+  end
+end
+
+# Record work results
+reporter.record(work_result, job_name: "process_data")
+
+# Generate reports
+puts reporter.formatted_report
+File.write("metrics.txt", reporter.to_prometheus)
+----
+
+See `examples/error_reporting.rb` for the complete example.
+
+== Example directory structure
+
+All examples are located in the `examples/` directory of the gem repository:
+
+[source]
+----
+examples/
+├── simple/                    # Basic usage
+├── auto_detection/            # Worker auto-detection
+├── hierarchical_hasher/       # File processing
+├── multi_work_type/           # Multiple work types
+├── pipeline_processing/       # Multi-stage pipelines
+├── producer_subscriber/       # Hierarchical processing
+├── scatter_gather/            # Task decomposition
+├── specialized_workers/       # Domain-specific workers
+├── continuous_chat_server/    # Plain socket server
+├── continuous_chat_fractor/   # Fractor-based server
+└── workflow/                  # Workflow examples
+    ├── simple_linear/
+    ├── fan_out/
+    ├── conditional/
+    └── simplified/
+----
+
+Each example directory contains:
+
+* Source code implementing the pattern
+* `README.adoc` with detailed explanation
+* RSpec tests demonstrating usage
+
+== Next steps
+
+* Start with link:../pages/getting-started/[Getting Started] for quick start guides
+* Learn about link:../guides/pipeline-mode/[Pipeline Mode] for batch processing
+* Learn about link:../guides/continuous-mode/[Continuous Mode] for long-running servers
+* Explore link:../features/workflows/[Workflows] for complex processing graphs
+* Understand link:../pages/core-concepts/[Core Concepts] of the framework

data/docs/_reference/index.adoc

@@ -0,0 +1,96 @@
+---
+layout: default
+title: Overview
+nav_order: 1
+---
+
+== Overview
+
+Comprehensive API documentation, design patterns, and advanced topics.
+
+The reference section provides in-depth technical documentation for advanced
+users and contributors. This includes complete API specifications, design
+patterns, performance optimization techniques, and production deployment
+guidelines.
+
+=== Available References
+
+==== API Documentation
+
+* *link:../api/[API Reference]* - Complete API documentation for all classes and methods
+// * *link:../configuration/[Configuration Options]* - All configuration parameters and their effects
+
+==== Design Patterns & Examples
+
+* *link:../examples/[Examples]* - Real-world use cases with complete code
+// * *link:../patterns/[Design Patterns]* - Common architectural patterns and best practices
+// * *link:../performance/[Performance Tuning]* - Optimization strategies and benchmarking
+
+==== Advanced Topics
+
+// * *link:../production/[Production Deployment]* - Guidelines for production environments
+// * *link:best-practices/[Best Practices]* - Recommendations from production usage
+* *link:../troubleshooting/[Troubleshooting]* - Common issues and solutions
+// * *link:../contributing/[Contributing]* - How to contribute to Fractor
+
+=== Who Should Use This Section
+
+The reference documentation is for:
+
+* *Advanced Users* - Looking to optimize or customize Fractor
+* *Library Developers* - Building on top of Fractor
+* *Contributors* - Understanding internals for contributions
+* *Production Engineers* - Deploying and maintaining Fractor in production
+
+=== Prerequisites
+
+Before diving into reference documentation, you should:
+
+* Complete the link:../../tutorials/[Tutorials] section
+* Understand link:../../core-concepts/[Core Concepts]
+* Have experience with production Ruby applications
+* Understand parallel processing fundamentals
+
+=== Quick Navigation
+
+==== By Use Case
+
+*I want to...*
+
+* *Optimize performance* → See link:../performance/[Performance Tuning]
+* *Handle production errors* → See link:best-practices/[Best Practices] and link:../troubleshooting/[Troubleshooting]
+* *Understand all options* → See link:../api/[API Reference] and link:configuration/[Configuration]
+* *Learn patterns* → See link:../patterns/[Design Patterns] and link:examples/[Examples]
+* *Deploy to production* → See link:../production/[Production Deployment]
+* *Contribute code* → See link:../contributing/[Contributing]
+
+==== By Experience Level
+
+*Advanced Users*
+
+. link:../performance/[Performance Tuning]
+. link:../patterns/[Design Patterns]
+. link:best-practices/[Best Practices]
+
+*Library Developers*
+
+. link:../api/[API Reference]
+. link:../examples/[Examples]
+. link:../contributing/[Contributing]
+
+*Production Engineers*
+
+. link:../production/[Production Deployment]
+. link:best-practices/[Best Practices]
+. link:../troubleshooting/[Troubleshooting]
+
+=== Related Resources
+
+* link:../tutorials/[Tutorials] - Beginner-friendly introductions
+* link:../guides/[Guides] - In-depth feature documentation
+* https://github.com/metanorma/fractor[GitHub Repository] - Source code and issues
+* https://rubygems.org/gems/fractor[RubyGems] - Gem releases
+
+=== Contributing to Documentation
+
+Found an error or want to improve the documentation? See link:../contributing/[Contributing] for guidelines on submitting documentation improvements.