User Guide

This handbook is the primary end-user guide for DTL. It is organized as a chaptered path from first use to production-scale operation.

Who should read this

• C++ developers adopting DTL for distributed and/or heterogeneous workloads

• teams integrating DTL into MPI/GPU pipelines

• users consuming C, Python, or Fortran bindings

Recommended reading order

1. Read chapters 1-3 to establish runtime and data model foundations.

2. Read chapters 4-7 to learn core usage patterns.

3. Read chapters 8-12 as needed for bindings, reliability, performance, and operations.

• 1. Mental Model and Core Concepts
  • What DTL is
  • Core ideas
  • Fundamental terms
  • First principles for users
  • Relationship to STL
  • Recommended next step
• 2. Installation and Build Workflows
  • Build prerequisites
  • Standard CMake configuration
  • Common build profiles
  • Feature flags to know
  • Installation and packaging notes
  • Verification checklist
  • Next step
• 3. Environment, Context, and Backends
  • Lifecycle model
  • Environment responsibilities
  • Context responsibilities
  • Backend-aware programming guidance
  • Single-rank and non-MPI mode
  • MPI/GPU domain composition
  • Operational best practices
  • Next step
  • Deep-dive reference
• 4. Distributed Containers
  • Container families
  • Core container properties
  • Constructing containers
  • Local data access
  • Structural operations
  • Container-specific notes
  • Safety and correctness checklist
  • Next step
  • Deep-dive reference
• 5. Views, Iteration, and Data Access
  • Why views matter
  • Local view
  • distributed_span for non-owning local windows
  • Global and segmented views
  • Remote reference (remote_ref)
  • Iteration guidance
  • Access pattern best practices
  • Common anti-patterns
  • Next step
  • Deep-dive reference
• 6. Policies and Execution Control
  • Policy system overview
  • Partition policies
  • Placement policies
  • Execution policies
  • Consistency policies
  • Error policies
  • Policy composition guidance
  • Validation checklist
  • Next step
  • Deep-dive reference
• 7. Algorithms, Collectives, and Remote Operations
  • Algorithm model
  • Local vs collective semantics
  • Collective operations
  • Remote and RPC-style operations
  • RMA and asynchronous requests
  • Correctness guidelines
  • Next step
  • Deep-dive reference
• 8. Language Bindings Overview
  • Supported bindings
  • Choosing a binding
  • C ABI usage model
  • Python usage model
  • Fortran usage model
  • Cross-language parity guidance
  • distributed_span mapping across bindings
  • Binding test expectations
  • Next step
  • Deep-dive reference
• 9. Error Handling and Reliability
  • Error model overview
  • C++ guidance
  • C ABI guidance
  • Python guidance
  • Reliability practices
  • Failure categories to handle explicitly
  • Operational recommendations
  • Next step
  • Deep-dive reference
• 10. Performance Tuning and Scaling
  • Performance mindset
  • High-impact levers
  • Partition and locality
  • Placement and memory movement
  • Algorithm-level optimization
  • Synchronization strategy
  • Benchmarking approach
  • Common scaling bottlenecks
  • Further reading
  • Deep-dive reference
• 11. Troubleshooting and Diagnostics
  • Build/configuration failures
  • Runtime capability mismatches
  • Collective hangs or deadlocks
  • Binding-specific issues
  • Diagnostics best practices
  • Additional resources
  • Deep-dive reference
• 12. Migration and Upgrade Guidance
  • Migration goals
  • Recommended migration process
  • Areas to verify during upgrades
  • Version alignment checks
  • Risk-managed rollout pattern
  • Migration references
  • Final pre-production checklist
  • Deep-dive reference
• 13. Runtime and Handle Model
  • Why this chapter exists
  • Runtime model
  • Handle model overview
  • C ABI handle contract
  • Python and Fortran handle behavior
  • Lifetime and ordering rules
  • Practical checklist
  • Related references

Quick jump links

• New to DTL: Chapter 1

• Building and installing: Chapter 2

• First distributed context: Chapter 3

• Core container and view usage (including distributed_span): Chapters 4-5

• Policy composition and algorithm behavior: Chapters 6-7

• Bindings and interop: Chapter 8

• Failure handling and recovery: Chapter 9

• Performance optimization: Chapter 10

• Runtime and handle semantics: Chapter 13

Legacy Deep-Dive References

These pages are retained as detailed topical references. The chaptered handbook above is the canonical path.

• Legacy Deep-Dive: Environment
• Legacy Deep-Dive: Containers
• Legacy Deep-Dive: Views
• Legacy Deep-Dive: Policies
• Legacy Deep-Dive: Algorithms
• Legacy Deep-Dive: Language Bindings
• Legacy Deep-Dive: Error Handling
• Legacy Deep-Dive: Performance Tuning
• Legacy Deep-Dive: Troubleshooting
• Legacy Deep-Dive: Migration (V1.0 to V1.5)