Stanford University logo SLAC National Accelerator Laboratory logo Los Alamos National Laboratory logo NVIDIA logo Winner of the R&D 100 Award


A Data-Centric Parallel Programming System



Legion API Tutorial

After completing the getting started guide this tutorial will show how to begin writing programs to the Legion C++ runtime API. The goal of the tutorial is not to describe all the Legion runtime calls, but rather to introduce to users how to write programs within the Legion framework. Consequently, the tutorial is not comprehensive, but when completed users should understand the methodology behind the API. Furthermore, these code examples are designed to clearly demonstrate the usage of API calls and should not be considered idiomatic of actual Legion code. Well designed Legion applications will extend the types in the API to construct higher levels of abstractions.

The tutorial is broken into ten examples which introduce concepts from the Legion programming model. Each example builds upon previous examples to gradually show how a complete Legion application is structured. The source code for each example can be found in the tutorial directory of the Legion repository. Users should build and run these examples while working through the tutorial.

  1. Hello World
  2. Tasks and Futures
  3. Index Space Tasks
  4. Hybrid Programming Model
  5. Logical Regions
  6. Physical Regions
  7. Privileges
  8. Partitioning
  9. Multiple Partitions
  10. Custom Mappers

Advanced Examples

In addition to the basic tutorial, we will be gradually adding more complete examples of programs written in Legion. As we add new programs they will be registered here along with a brief description of the features they encompass.

  • Circuit Simulation - This is the circuit example from our publications. The circuit simulation illustrates the use of reduction privileges as well as reduction-fold physical instances. We also cover how to run tasks on the GPU, a simple Legion design pattern, and an example of how Legion easily enables in-situ analysis of program data.
  • Explicit Ghost Regions - An illustration of how to use Legion to implement an explicit ghost regions algorithm. We cover how to perform inter-region copies and use phase barriers to encode producer-consumer relationships in a deferred execution environment. We also show how to employ acquire and release operations in conjunction with simultaneous coherence to safely manage explicit ghost regions.
  • Conjugate Gradient - An external project being developed by Los Alamos National Lab that illustrates how higher-level abstractions should be constructed on top of logical regions and the Legion programming model. In this particular case sparse matrix and vector abstractions are built on top of Legion as part of the development of a conjugate gradient solver.

Legion Manual and API Documentation

The Legion manual documents features of the Legion C++ runtime API in a systematic way, going beyond what is convered in the tutorials. This resource, along with C++ API documentation, are recommended reading for interested users wanting to dive deeper into the Legion programming model.

Debugging and Profiling

The following pages describe Legion’s debugging and profiling facilities, and how to use them.