ROUP

What is ROUP?

ROUP is an experimental parser for OpenMP directives, written in safe Rust with C and C++ APIs. Parse OpenMP pragmas like #pragma omp parallel for into structured data that your tools can analyze, transform, and process.

⚠️ Experimental Status: ROUP is under active development and not yet production-ready. APIs may change, and some OpenMP features are still being implemented. Use in research and experimental projects.

Perfect for:

• 🔧 Compiler research - Experiment with OpenMP parsing in compilers
• 🔍 Analysis prototypes - Build experimental linters and analyzers
• 🎓 Researchers - Study parallelization patterns and test new ideas
• 📚 Educators - Teaching tool for parallel programming concepts

Why ROUP?

🚀 Fast & Lightweight

• Microsecond parsing - Parse directives in ~500ns
• Zero-copy lexer - Minimal memory allocations
• No LLVM dependency - Standalone library, small binary size
• 16 FFI functions - Simple, focused C API

🛡️ Safe & Reliable

• 99.1% safe Rust - Memory safety guaranteed
• 352 passing tests - Comprehensive test coverage
• Fuzzing tested - Handles malformed input gracefully
• NULL-safe C API - Defensive checks at FFI boundary

📚 Comprehensive OpenMP Support

• 95 directives - From parallel to metadirective
• 91 clauses - Extensive OpenMP 3.0 through 6.0 coverage
• Version tracking - Know which OpenMP version introduced each feature
• Spec compliant - Follows official OpenMP specifications

🔌 Multi-Language APIs

Quick Example

Parse in 3 Lines (Rust)

use roup::parser::openmp;

let parser = openmp::parser();
let (_, directive) = parser.parse("#pragma omp parallel for num_threads(4)").unwrap();
// Access directive information
println!("Directive: {}", directive.name);  // Output: Directive: parallel for
println!("Found {} clauses", directive.clauses.len());  // Output: Found 1 clauses
// Iterate through clauses
for clause in &directive.clauses {
    println!("  Clause: {}", clause.name);  // Output:   Clause: num_threads
}

Parse in C

OmpDirective* dir = roup_parse("#pragma omp parallel for num_threads(4)");
printf("Clauses: %d\n", roup_directive_clause_count(dir));
roup_directive_free(dir);

Parse in C++ (with RAII)

roup::Directive dir("#pragma omp parallel for num_threads(4)");
std::cout << "Clauses: " << dir.clause_count() << "\n";
// Automatic cleanup!

Parse Fortran (Experimental)

! Free-form Fortran
directive_ptr = roup_parse_with_language("!$OMP PARALLEL PRIVATE(A)", &
                                          ROUP_LANG_FORTRAN_FREE)

See full examples →

Feature Highlights

🎯 Comprehensive Coverage

Full OpenMP Support Matrix →

🔍 Rich Clause Support

92+ clause types including:

Complete clause reference →

Architecture

┌──────────────────────────────────────┐
│  Your Application                    │
├──────────────────────────────────────┤
│  Language Bindings                   │
│  ├─ Rust API (native)                │
│  ├─ C API (16 functions)             │
│  └─ C++ API (RAII wrappers)          │
├──────────────────────────────────────┤
│  Parser Layer (99.1% safe Rust)      │
│  ├─ Directive Parser                 │
│  ├─ Clause Parser                    │
│  └─ Error Recovery                   │
├──────────────────────────────────────┤
│  Lexer (nom-based, zero-copy)        │
└──────────────────────────────────────┘

Design Principles:

• Safety first - Rust ownership prevents memory bugs
• Zero-copy - Parse directly from input string
• Minimal FFI - Only ~60 lines of unsafe code (0.9%)
• Extensible - Easy to add new directives/clauses

Learn more about the architecture →

Comparison

ROUP vs LLVM/Clang

Use ROUP when:

• ✅ You only need to parse OpenMP, not compile
• ✅ You want minimal dependencies
• ✅ You need fast integration into tools
• ✅ You value simplicity and safety

Use LLVM when:

• You need full C/C++ compilation
• You're building a complete compiler
• You need LLVM IR generation

ROUP vs Custom Parser

Verdict: Unless you have very specific needs, use ROUP.

Safety Guarantees

ROUP prioritizes safety without compromising usability:

Memory Safety

• ✅ No buffer overflows - Rust prevents at compile time
• ✅ No use-after-free - Ownership system enforces
• ✅ No double-free - Checked at FFI boundary
• ✅ No memory leaks - RAII and destructors
• ✅ No data races - Thread-safe parsing

API Safety

Rust API:

• 100% memory-safe by construction
• Impossible to trigger undefined behavior

C API:

• NULL checks before all pointer operations
• Returns safe defaults on error (-1, NULL)
• Validates UTF-8 encoding
• Documents all safety contracts

Testing

• 342 tests covering all features
• Fuzzing with random inputs
• Valgrind verified (no leaks)
• Thread sanitizer verified (no races)
• Address sanitizer verified (no memory errors)

Read the safety analysis →

Performance

Typical performance characteristics:

Scalability:

• ✅ Thread-safe - Parse from multiple threads
• ✅ Zero-copy - No string allocations during lexing
• ✅ Minimal allocations - ~3 allocations per directive
• ✅ Fast enough - Parsing is rarely the bottleneck

Performance details →

Getting Started

Choose your language:

[dependencies]
roup = "0.3"

cargo build --release

cargo build --release

Quick Start Guide →

Community

• GitHub: ouankou/roup
• Issues: Bug reports
• Discussions: Questions & ideas
• Contributing: How to contribute

License

ROUP is open source under the MIT License.

Copyright © 2024-2025 Anjia Wang

Next Steps

• 📖 Read the Getting Started guide
• 🦀 Try the Rust tutorial
• 🔧 Try the C tutorial
• 📚 Browse the API reference
• 🏗️ Learn the architecture
• ❓ Check the FAQ

Why ROUP?

For Compiler Developers

• Drop-in OpenMP/OpenACC parser component
• Well-tested, battle-hardened parsing logic
• Easy FFI integration from any language

For Tool Builders

• Analyze OpenMP code without a full compiler
• Build linters, formatters, and code analyzers
• Extract parallelization patterns from codebases

For Researchers

• Study directive usage patterns
• Prototype new directive extensions
• Educational tool for learning parallel programming

Quick Example

Rust

use roup::parser::openmp;

let parser = openmp::parser();
let input = "#pragma omp parallel for num_threads(4) private(i)";
match parser.parse(input) {
    Ok((_, directive)) => {
        println!("Directive: {:?}", directive.kind);
        println!("Clauses: {}", directive.clauses.len());
    }
    Err(e) => eprintln!("Parse error: {:?}", e),
}

C

#include <stdio.h>

// Forward declarations
typedef struct OmpDirective OmpDirective;
extern OmpDirective* roup_parse(const char* input);
extern int32_t roup_directive_clause_count(const OmpDirective* dir);
extern void roup_directive_free(OmpDirective* dir);

int main() {
    OmpDirective* dir = roup_parse("#pragma omp parallel for num_threads(4)");
    if (dir) {
        printf("Clauses: %d\n", roup_directive_clause_count(dir));
        roup_directive_free(dir);
    }
    return 0;
}

C++

#include <iostream>
#include <memory>

struct OmpDirective;
extern "C" {
    OmpDirective* roup_parse(const char* input);
    int32_t roup_directive_clause_count(const OmpDirective* dir);
    void roup_directive_free(OmpDirective* dir);
}

// RAII wrapper
class Directive {
    OmpDirective* ptr_;
public:
    explicit Directive(const char* input) : ptr_(roup_parse(input)) {}
    ~Directive() { if (ptr_) roup_directive_free(ptr_); }
    bool valid() const { return ptr_ != nullptr; }
    int clause_count() const { 
        return ptr_ ? roup_directive_clause_count(ptr_) : 0; 
    }
};

int main() {
    Directive dir("#pragma omp parallel for num_threads(4)");
    if (dir.valid()) {
        std::cout << "Clauses: " << dir.clause_count() << "\n";
    }
    return 0;
}

Architecture

ROUP uses a clean, modular architecture:

┌─────────────────────────────────────────┐
│         Application Layer               │
│  (Your compiler/tool/analyzer)          │
└─────────────────┬───────────────────────┘
                  │
      ┌───────────┼───────────┐
      │           │           │
      ▼           ▼           ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Rust API│ │  C API  │ │ C++ API │
│         │ │         │ │ (RAII)  │
└─────────┘ └─────────┘ └─────────┘
      │           │           │
      └───────────┼───────────┘
                  │
                  ▼
         ┌────────────────┐
         │  Core Parser   │
         │  (nom-based)   │
         └────────────────┘
                  │
      ┌───────────┼───────────┐
      ▼           ▼           ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│  Lexer  │ │Directive│ │ Clause  │
│         │ │ Parser  │ │ Parser  │
└─────────┘ └─────────┘ └─────────┘

Key Design Principles:

• Safe by default - Rust's ownership system prevents memory errors
• Zero-copy parsing - Uses string slices, not allocations
• Minimal unsafe - FFI boundary only, well-documented
• Extensible - Easy to add new directives and clauses

OpenMP Support

ROUP currently supports OpenMP 5.0+ with comprehensive coverage:

Supported Directives (15+)

• parallel - Parallel regions
• for - Worksharing loops
• sections, single - Worksharing constructs
• task, taskwait, taskgroup - Tasking
• target, teams, distribute - Device offloading
• barrier, critical, atomic - Synchronization
• metadirective - Dynamic selection
• And more...

Supported Clauses (50+)

• Data sharing: private, shared, firstprivate, lastprivate
• Parallelism control: num_threads, if, proc_bind
• Worksharing: schedule, collapse, nowait
• Reductions: reduction with 10+ operators (+, *, min, max, etc.)
• Device: map, device, defaultmap
• Dependencies: depend, in, out, inout
• And more...

See the OpenMP Support Matrix for the complete list.

Safety Guarantees

ROUP is built with safety as a core principle:

All unsafe code is:

• Documented with safety requirements
• NULL-checked before dereferencing
• Isolated to src/c_api.rs
• Tested with 355+ tests

Testing

ROUP has comprehensive test coverage:

• 239 doc tests - Examples in documentation are auto-tested
• 116 integration tests - Real-world usage scenarios
• 355 total tests - All passing, zero warnings
• Cross-platform - Tested on Linux, macOS, Windows

Test categories:

• ✅ Basic directives (parallel, for, task, teams, target)
• ✅ Complex features (reductions, metadirectives, nesting)
• ✅ Edge cases (comments, whitespace, error handling)
• ✅ Roundtrip parsing (parse → format → parse)
• ✅ FFI safety (C and C++ examples)

Getting Started

Want to experiment with ROUP? Check out our tutorials:

• C++ Tutorial - Build an experimental application with C++17
• Rust API Docs - Complete API reference

Or jump straight to the code:

• GitHub Repository
• Quick Start Guide

License

ROUP is open source under the MIT License.

Copyright © 2024-2025 Anjia Wang

Getting Started

Get up and running with ROUP in 5 minutes. This guide covers installation, basic usage, and your first OpenMP parse for Rust, C, and C++.

Installation

Prerequisites

• Rust 1.70+ (Install Rust)
• C/C++ Compiler: Clang 10+ or GCC 9+ (for C/C++ usage)

Build ROUP

git clone https://github.com/ouankou/roup.git
cd roup
cargo build --release

This creates the library at:

• Linux: target/release/libroup.so
• macOS: target/release/libroup.dylib
• Windows: target/release/roup.dll

Quick Start: Rust

1. Add Dependency

Add to your Cargo.toml:

[dependencies]
roup = "0.3"

Or use the git version:

[dependencies]
roup = { git = "https://github.com/ouankou/roup.git" }

2. Parse Your First Directive

use roup::parser::openmp::parse_openmp_directive;
use roup::lexer::Language;

fn main() {
    let input = "#pragma omp parallel for num_threads(4)";
    
    match parse_openmp_directive(input, Language::C) {
        Ok(directive) => {
            println!("✓ Successfully parsed: {:?}", directive.kind);
            println!("  Clauses: {}", directive.clauses.len());
            
            for clause in &directive.clauses {
                println!("  - {:?}", clause);
            }
        }
        Err(e) => {
            eprintln!("✗ Parse error: {}", e);
        }
    }
}

3. Run

cargo run

Output:

✓ Successfully parsed: ParallelFor
  Clauses: 1
  - NumThreads(Expr { value: "4", .. })

Next: See the Rust Tutorial for advanced usage.

Quick Start: C

1. Write Your Program

The C API uses direct pointers (malloc/free pattern):

#include <stdio.h>
#include <stdint.h>

// Forward declarations from libroup
typedef struct OmpDirective OmpDirective;

OmpDirective* roup_parse(const char* input);
int32_t roup_directive_clause_count(const OmpDirective* dir);
void roup_directive_free(OmpDirective* dir);

int main() {
    // Parse a directive
    OmpDirective* directive = roup_parse("#pragma omp parallel num_threads(4)");
    
    if (!directive) {
        fprintf(stderr, "Parse failed\n");
        return 1;
    }
    
    // Query clause count
    int32_t count = roup_directive_clause_count(directive);
    printf("Clause count: %d\n", count);
    
    // Clean up
    roup_directive_free(directive);
    
    return 0;
}

2. Compile

# Build ROUP library first
cargo build --release

# Compile your C program
clang example.c \
  -L./target/release \
  -lroup \
  -lpthread -ldl -lm \
  -Wl,-rpath,./target/release \
  -o example

On macOS:

clang example.c \
  -L./target/release \
  -lroup \
  -lpthread -ldl \
  -Wl,-rpath,@executable_path/../target/release \
  -o example

3. Run

./example

Output:

Clause count: 1

Next: See the C Tutorial for complete examples with iteration and error handling.

Quick Start: C++

1. Create Your Program

Modern C++17 with RAII wrappers:

#include <iostream>
#include <cstdint>

// Forward declarations from libroup C API
struct OmpDirective;
extern "C" {
    OmpDirective* roup_parse(const char* input);
    int32_t roup_directive_clause_count(const OmpDirective* dir);
    void roup_directive_free(OmpDirective* dir);
}

// Simple RAII wrapper
class Directive {
    OmpDirective* ptr_;
public:
    explicit Directive(const char* input) 
        : ptr_(roup_parse(input)) {}
    
    ~Directive() {
        if (ptr_) roup_directive_free(ptr_);
    }
    
    // Delete copy, allow move
    Directive(const Directive&) = delete;
    Directive& operator=(const Directive&) = delete;
    Directive(Directive&& other) noexcept 
        : ptr_(other.ptr_) {
        other.ptr_ = nullptr;
    }
    
    bool valid() const { 
        return ptr_ != nullptr; 
    }
    
    int clause_count() const {
        return ptr_ ? roup_directive_clause_count(ptr_) : 0;
    }
};

int main() {
    Directive dir("#pragma omp parallel for num_threads(4)");
    
    if (!dir.valid()) {
        std::cerr << "Parse failed\n";
        return 1;
    }
    
    std::cout << "Clause count: " << dir.clause_count() << "\n";
    
    return 0;
}  // Automatic cleanup via RAII

2. Compile

# Build ROUP library first
cargo build --release

# Compile your C++ program
clang++ -std=c++17 example.cpp \
  -L./target/release \
  -lroup \
  -lpthread -ldl -lm \
  -Wl,-rpath,./target/release \
  -o example

3. Run

./example

Output:

Clause count: 1

Next: See the C++ Tutorial for a complete real-world example.

What's Supported?

Directives (95 total)

✅ Parallelism: parallel, for, sections, single, master
✅ Tasking: task, taskwait, taskgroup, taskloop
✅ Device offloading: target, teams, distribute
✅ Synchronization: barrier, critical, atomic
✅ Advanced: metadirective, declare variant, loop

Clauses (91 total)

✅ Scheduling: schedule, collapse, ordered
✅ Data-sharing: private, shared, firstprivate, lastprivate
✅ Reductions: reduction(+|-|*|&|&&|min|max:vars)
✅ Device clauses: device, map, is_device_ptr
✅ Control: if, num_threads, default

For the complete support matrix, see OpenMP Support.

Troubleshooting

Library Not Found at Runtime

Linux:

export LD_LIBRARY_PATH=$PWD/target/release:$LD_LIBRARY_PATH
./example

Or use -Wl,-rpath during compilation (recommended):

clang example.c -L./target/release -lroup -lpthread -ldl -lm -Wl,-rpath,$PWD/target/release

macOS:

export DYLD_LIBRARY_PATH=$PWD/target/release:$DYLD_LIBRARY_PATH
./example

Parse Returns NULL

Check your OpenMP syntax:

// ✅ Valid
OmpDirective* dir = roup_parse("#pragma omp parallel");

// ✅ Valid - with clauses
dir = roup_parse("#pragma omp parallel num_threads(4)");

// ❌ Invalid - missing 'omp'
dir = roup_parse("#pragma parallel");  // Returns NULL

Always check for NULL:

OmpDirective* dir = roup_parse(input);
if (!dir) {
    fprintf(stderr, "Parse error\n");
    return 1;
}
// ... use dir ...
roup_directive_free(dir);

C++ Compilation Errors

Make sure you're using C++17:

# ✅ Correct
clang++ -std=c++17 example.cpp ...

# ❌ Wrong - C++11 lacks required features
clang++ -std=c++11 example.cpp ...

Next Steps

Learn More

• Rust Tutorial - Idiomatic Rust patterns (coming soon)
• C Tutorial - Complete C examples (coming soon)
• C++ Tutorial - Real-world application
• API Reference - Complete C/Rust API docs

Examples

• examples/c/ - 5 complete C examples
• examples/cpp/ - 3 complete C++ examples with RAII

Advanced Topics

• Error handling strategies
• Iterator patterns for clauses
• Thread safety considerations
• Performance optimization

Summary

Rust:

cargo add roup
# Write code, then:
cargo run

C:

cargo build --release
clang example.c -L./target/release -lroup -lpthread -ldl -lm -Wl,-rpath,./target/release
./example

C++:

cargo build --release
clang++ -std=c++17 example.cpp -L./target/release -lroup -lpthread -ldl -lm -Wl,-rpath,./target/release
./example

You're ready to experiment with OpenMP parsing! 🎉

Building Guide

This guide covers building ROUP and integrating it into your projects across different languages and platforms.

Quick Start

# Clone the repository
git clone https://github.com/ouankou/roup.git
cd roup

# Build the library (release mode, optimized)
cargo build --release

# Run tests to verify
cargo test

# Build is complete! Library at: target/release/libroup.{a,so,dylib,dll}

Next steps:

• Rust users: Add ROUP as a dependency (see below)
• C users: Link against libroup.a (see C Tutorial)
• C++ users: Use RAII wrappers (see C++ Tutorial)

Rust Integration

Option 1: Using crates.io (Recommended)

Add to your Cargo.toml:

[dependencies]
roup = "0.3"

Then use in your code:

use roup::parser::parse;

fn main() {
    let result = parse("#pragma omp parallel for");
    match result {
        Ok(directive) => println!("Parsed: {:?}", directive),
        Err(e) => eprintln!("Error: {}", e),
    }
}

Option 2: Using Git Dependency

[dependencies]
roup = { git = "https://github.com/ouankou/roup.git" }

Option 3: Local Development

[dependencies]
roup = { path = "../roup" }

Building Your Rust Project

# Standard cargo commands
cargo build           # Debug build
cargo build --release # Optimized build
cargo test            # Run tests
cargo doc --open      # Generate and view docs

See Rust Tutorial for complete usage examples.

C Integration

Prerequisites

• Rust toolchain (to build libroup)
• C compiler: GCC, Clang, or MSVC
• Build tools: Make or CMake (optional)

Step 1: Build the ROUP Library

cd /path/to/roup
cargo build --release

This creates:

• Linux: target/release/libroup.{a,so}
• macOS: target/release/libroup.{a,dylib}
• Windows: target/release/roup.{lib,dll}

Step 2: Create Header File

Create roup_ffi.h with function declarations (see C Tutorial for complete header).

Step 3: Compile Your C Program

Using GCC/Clang (Linux/macOS)

# Static linking
gcc -o myapp main.c \
    -I/path/to/roup_ffi.h \
    -L/path/to/roup/target/release \
    -lroup \
    -lpthread -ldl -lm

# Dynamic linking with rpath
gcc -o myapp main.c \
    -I/path/to/roup_ffi.h \
    -L/path/to/roup/target/release \
    -lroup \
    -Wl,-rpath,/path/to/roup/target/release \
    -lpthread -ldl -lm

Using CMake

cmake_minimum_required(VERSION 3.10)
project(MyApp C)

# Add ROUP library
add_library(roup STATIC IMPORTED)
set_target_properties(roup PROPERTIES
    IMPORTED_LOCATION "/path/to/roup/target/release/libroup.a"
)

# Create executable
add_executable(myapp main.c)
target_include_directories(myapp PRIVATE "/path/to/roup_ffi.h")
target_link_libraries(myapp roup pthread dl m)

Using MSVC (Windows)

REM Build ROUP library first
cargo build --release

REM Compile C program
cl.exe main.c /I"C:\path\to\roup" ^
    /link "C:\path\to\roup\target\release\roup.lib" ^
    ws2_32.lib userenv.lib

Step 4: Run Your Program

# If using static linking
./myapp

# If using dynamic linking without rpath
LD_LIBRARY_PATH=/path/to/roup/target/release ./myapp

# Windows
set PATH=C:\path\to\roup\target\release;%PATH%
myapp.exe

Complete Example

See examples/c/tutorial_basic.c for a full working example with build instructions.

C++ Integration

C++ programs use the same C API with optional RAII wrappers for automatic memory management.

Step 1: Build ROUP Library

cargo build --release

Step 2: Create RAII Wrappers

See C++ Tutorial - Step 2 for complete wrapper code.

Step 3: Compile with C++17

# Using g++
g++ -o myapp main.cpp \
    -I/path/to/roup_ffi.h \
    -I/path/to/roup_wrapper.hpp \
    -L/path/to/roup/target/release \
    -lroup \
    -std=c++17 \
    -lpthread -ldl -lm

# Using Clang++
clang++ -o myapp main.cpp \
    -I/path/to/roup_ffi.h \
    -I/path/to/roup_wrapper.hpp \
    -L/path/to/roup/target/release \
    -lroup \
    -std=c++17 \
    -lpthread -ldl -lm

CMake for C++

cmake_minimum_required(VERSION 3.10)
project(MyApp CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_library(roup STATIC IMPORTED)
set_target_properties(roup PROPERTIES
    IMPORTED_LOCATION "/path/to/roup/target/release/libroup.a"
)

add_executable(myapp main.cpp)
target_include_directories(myapp PRIVATE 
    "/path/to/roup_ffi.h"
    "/path/to/roup_wrapper.hpp"
)
target_link_libraries(myapp roup pthread dl m)

Platform-Specific Notes

Linux

Ubuntu/Debian

# Install build tools
sudo apt-get update
sudo apt-get install build-essential curl git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build ROUP
cargo build --release

Fedora/RHEL

# Install build tools
sudo dnf install gcc git

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build ROUP
cargo build --release

Library location: target/release/libroup.{a,so}

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build ROUP
cargo build --release

Library location: target/release/libroup.{a,dylib}

Note: On macOS, the dynamic library extension is .dylib, not .so.

Windows

Using Rust with MSVC

# Install Rust (uses MSVC toolchain by default on Windows)
# Download from: https://rustup.rs/

# Install Visual Studio Build Tools
# Download from: https://visualstudio.microsoft.com/downloads/

# Build ROUP
cargo build --release

Library location: target\release\roup.{lib,dll}

Using Rust with GNU (MinGW)

# Install MSYS2 from https://www.msys2.org/
# Then in MSYS2 terminal:

# Install MinGW toolchain
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-rust

# Build ROUP
cargo build --release

WSL (Recommended for C/C++)

Windows Subsystem for Linux provides a full Linux environment:

# In WSL (Ubuntu)
sudo apt-get install build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo build --release

Build Configurations

Debug Build (Development)

cargo build

# Output: target/debug/libroup.{a,so}
# Features: Debug symbols, assertions, slower but better errors

Release Build (Production)

cargo build --release

# Output: target/release/libroup.{a,so}
# Features: Optimized, no debug symbols, faster execution

Release with Debug Info

cargo build --release --config profile.release.debug=true

# Output: target/release/libroup.{a,so}
# Features: Optimized but with debug symbols for profiling

Custom Features

# Build with all features
cargo build --all-features

# Build with specific feature
cargo build --features "serde"

# Build without default features
cargo build --no-default-features

Testing

Run All Tests

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_parallel_directive

# Run tests for specific module
cargo test parser::

Run Examples

# List available examples
cargo run --example

# Run specific example (if any exist)
cargo run --example parse_simple

Benchmarks

# If benchmarks are available
cargo bench

Troubleshooting

"linker cc not found"

Problem: No C compiler installed.

Solution:

# Linux
sudo apt-get install build-essential

# macOS
xcode-select --install

# Windows
# Install Visual Studio Build Tools

"cannot find -lroup"

Problem: Linker can't find the ROUP library.

Solution:

# Verify library exists
ls -lh target/release/libroup.*

# Rebuild if needed
cargo build --release

# Check linker path
gcc ... -L$(pwd)/target/release -lroup

"error while loading shared libraries: libroup.so"

Problem: Runtime can't find dynamic library.

Solution 1 - rpath:

gcc ... -Wl,-rpath,/path/to/roup/target/release

Solution 2 - LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=/path/to/roup/target/release:$LD_LIBRARY_PATH
./myapp

Solution 3 - Install system-wide:

sudo cp target/release/libroup.so /usr/local/lib/
sudo ldconfig

Rust Version Too Old

Problem: Compilation fails with version error.

Solution:

# Update Rust toolchain
rustup update stable

# Verify version
rustc --version
# Ensure your Rust version is at least 1.70.0

Windows: "VCRUNTIME140.dll missing"

Problem: Missing Visual C++ runtime.

Solution: Download and install Visual C++ Redistributable

Build Performance Tips

Faster Incremental Builds

# Use sccache for caching
cargo install sccache
export RUSTC_WRAPPER=sccache

# Use faster linker (Linux)
sudo apt-get install lld
export RUSTFLAGS="-C link-arg=-fuse-ld=lld"

Parallel Builds

# Use all CPU cores (default)
cargo build -j $(nproc)

# Limit parallel jobs
cargo build -j 4

Reduce Binary Size

# Add to Cargo.toml
[profile.release]
opt-level = "z"     # Optimize for size
lto = true          # Link-time optimization
codegen-units = 1   # Better optimization
strip = true        # Remove debug symbols

Cross-Compilation

Linux to Windows

# Install target
rustup target add x86_64-pc-windows-gnu

# Install MinGW
sudo apt-get install mingw-w64

# Build
cargo build --release --target x86_64-pc-windows-gnu

macOS to Linux

# Install target
rustup target add x86_64-unknown-linux-gnu

# Build (requires cross-compilation setup)
cargo build --release --target x86_64-unknown-linux-gnu

For more complex cross-compilation, consider cross:

cargo install cross
cross build --release --target x86_64-unknown-linux-gnu

IDE Setup

Visual Studio Code

Recommended extensions:

• rust-analyzer - Language server
• CodeLLDB - Debugger
• crates - Dependency management

CLion / IntelliJ IDEA

Install the Rust plugin from JetBrains marketplace.

Vim/Neovim

Use rust-analyzer with your LSP client (coc.nvim, nvim-lspconfig, etc.)

Next Steps

After building successfully:

• Rust developers: See Rust Tutorial
• C developers: See C Tutorial
• C++ developers: See C++ Tutorial
• API Reference: See API Reference

Getting Help

• Build issues: Check GitHub Issues
• Questions: See FAQ
• Examples: Browse examples/ directory
• Documentation: Read docs/ directory

Rust Tutorial

Learn idiomatic Rust patterns for parsing and querying OpenMP directives with ROUP.

Overview

This tutorial covers:

1. Basic Parsing - Parse your first directive
2. Error Handling - Robust error handling patterns
3. Querying Directives - Extract directive information
4. Working with Clauses - Iterate and pattern match clauses
5. Advanced Patterns - Real-world usage patterns
6. Testing - Writing tests for your parser integration

Basic Parsing

Your First Parse

use roup::parser::openmp::parse_openmp_directive;
use roup::lexer::Language;

fn main() {
    let input = "#pragma omp parallel";
    
    match parse_openmp_directive(input, Language::C) {
        Ok(directive) => {
            println!("Successfully parsed: {:?}", directive.kind);
        }
        Err(e) => {
            eprintln!("Parse error: {}", e);
        }
    }
}

Parse with Clauses

use roup::parser::openmp::parse_openmp_directive;
use roup::lexer::Language;

fn main() {
    let input = "#pragma omp parallel for num_threads(4) private(x, y)";
    
    match parse_openmp_directive(input, Language::C) {
        Ok(directive) => {
            println!("Directive: {:?}", directive.kind);
            println!("Clauses: {}", directive.clauses.len());
            
            for (i, clause) in directive.clauses.iter().enumerate() {
                println!("  Clause {}: {:?}", i + 1, clause);
            }
        }
        Err(e) => {
            eprintln!("Failed to parse: {}", e);
        }
    }
}

Output:

Directive: ParallelFor
Clauses: 2
  Clause 1: NumThreads(Expr { value: "4", .. })
  Clause 2: Private { items: ["x", "y"], .. }

Error Handling

Basic Error Handling

use roup::parser::openmp::parse_openmp_directive;
use roup::lexer::Language;

fn parse_directive(input: &str) -> Result<(), Box<dyn std::error::Error>> {
    let directive = parse_openmp_directive(input, Language::C)?;
    
    println!("Parsed: {:?}", directive.kind);
    println!("Location: line {}, column {}", 
             directive.location.line, 
             directive.location.column);
    
    Ok(())
}

fn main() {
    let inputs = vec![
        "#pragma omp parallel",
        "#pragma omp for schedule(static)",
        "#pragma omp invalid",  // This will fail
    ];
    
    for input in inputs {
        match parse_directive(input) {
            Ok(()) => println!("✓ Success: {}", input),
            Err(e) => eprintln!("✗ Error: {} - {}", input, e),
        }
    }
}

Custom Error Type

use roup::parser::openmp::parse_openmp_directive;
use roup::lexer::Language;
use std::fmt;

#[derive(Debug)]
enum OpenMPError {
    ParseError(String),
    UnsupportedDirective(String),
    MissingRequiredClause(String),
}

impl fmt::Display for OpenMPError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            OpenMPError::ParseError(msg) => write!(f, "Parse error: {}", msg),
            OpenMPError::UnsupportedDirective(kind) => {
                write!(f, "Unsupported directive: {}", kind)
            }
            OpenMPError::MissingRequiredClause(clause) => {
                write!(f, "Missing required clause: {}", clause)
            }
        }
    }
}

impl std::error::Error for OpenMPError {}

fn validate_parallel_directive(input: &str) -> Result<(), OpenMPError> {
    let directive = parse_openmp_directive(input, Language::C)
        .map_err(|e| OpenMPError::ParseError(e.to_string()))?;
    
    if !directive.kind.is_parallel() {
        return Err(OpenMPError::UnsupportedDirective(
            format!("{:?}", directive.kind)
        ));
    }
    
    // Check for required clauses (example: must have num_threads)
    let has_num_threads = directive.clauses.iter()
        .any(|c| c.is_num_threads());
    
    if !has_num_threads {
        return Err(OpenMPError::MissingRequiredClause("num_threads".into()));
    }
    
    Ok(())
}

fn main() {
    match validate_parallel_directive("#pragma omp parallel num_threads(4)") {
        Ok(()) => println!("✓ Valid parallel directive"),
        Err(e) => eprintln!("✗ {}", e),
    }
}

Querying Directives

Check Directive Kind

use roup::parser::openmp::parse_openmp_directive;
use roup::ir::DirectiveKind;
use roup::lexer::Language;

fn main() {
    let input = "#pragma omp parallel for";
    let directive = parse_openmp_directive(input, Language::C).unwrap();
    
    // Pattern match on kind
    match directive.kind {
        DirectiveKind::Parallel => println!("This is a parallel directive"),
        DirectiveKind::For => println!("This is a for directive"),
        DirectiveKind::ParallelFor => println!("This is a combined parallel for"),
        DirectiveKind::Target => println!("This is a target directive"),
        _ => println!("Other directive type"),
    }
    
    // Or use helper methods
    if directive.kind.is_parallel() {
        println!("Contains parallel semantics");
    }
    
    if directive.kind.is_worksharing() {
        println!("Is a worksharing construct");
    }
}

Extract Source Location

use roup::parser::openmp::parse_openmp_directive;
use roup::lexer::Language;

fn main() {
    let input = "#pragma omp parallel";
    let directive = parse_openmp_directive(input, Language::C).unwrap();
    
    println!("Directive found at:");
    println!("  Line: {}", directive.location.line);
    println!("  Column: {}", directive.location.column);
    println!("  Language: {:?}", directive.language);
}

Working with Clauses

Iterate Over Clauses

use roup::parser::openmp::parse_openmp_directive;
use roup::lexer::Language;

fn main() {
    let input = "#pragma omp parallel num_threads(8) default(shared) private(x)";
    let directive = parse_openmp_directive(input, Language::C).unwrap();
    
    println!("Found {} clauses:", directive.clauses.len());
    
    for clause in &directive.clauses {
        println!("  - {:?}", clause);
    }
}

Pattern Match on Clauses

use roup::parser::openmp::parse_openmp_directive;
use roup::ir::ClauseData;
use roup::lexer::Language;

fn main() {
    let input = "#pragma omp parallel num_threads(4) default(shared) private(x, y)";
    let directive = parse_openmp_directive(input, Language::C).unwrap();
    
    for clause in &directive.clauses {
        match clause {
            ClauseData::NumThreads(expr) => {
                println!("Thread count: {}", expr.value);
            }
            ClauseData::Default(kind) => {
                println!("Default sharing: {:?}", kind);
            }
            ClauseData::Private { items, .. } => {
                println!("Private variables: {:?}", items);
            }
            ClauseData::Shared { items, .. } => {
                println!("Shared variables: {:?}", items);
            }
            ClauseData::Reduction { operator, items, .. } => {
                println!("Reduction: {:?} on {:?}", operator, items);
            }
            _ => {
                println!("Other clause: {:?}", clause);
            }
        }
    }
}

Find Specific Clauses

use roup::parser::openmp::parse_openmp_directive;
use roup::ir::ClauseData;
use roup::lexer::Language;

fn get_thread_count(input: &str) -> Option<String> {
    let directive = parse_openmp_directive(input, Language::C).ok()?;
    
    directive.clauses.iter()
        .find_map(|clause| {
            if let ClauseData::NumThreads(expr) = clause {
                Some(expr.value.to_string())
            } else {
                None
            }
        })
}

fn get_private_vars(input: &str) -> Vec<String> {
    let directive = parse_openmp_directive(input, Language::C)
        .ok()
        .unwrap_or_default();
    
    directive.clauses.iter()
        .filter_map(|clause| {
            if let ClauseData::Private { items, .. } = clause {
                Some(items.iter().map(|s| s.to_string()).collect())
            } else {
                None
            }
        })
        .flatten()
        .collect()
}

fn main() {
    let input = "#pragma omp parallel num_threads(8) private(x, y, z)";
    
    if let Some(count) = get_thread_count(input) {
        println!("Thread count: {}", count);
    }
    
    let vars = get_private_vars(input);
    println!("Private variables: {:?}", vars);
}

Output:

Thread count: 8
Private variables: ["x", "y", "z"]

Advanced Patterns

Parse Multiple Directives

use roup::parser::openmp::parse_openmp_directive;
use roup::ir::DirectiveIR;
use roup::lexer::Language;

fn parse_file_directives(source: &str) -> Vec<DirectiveIR> {
    source.lines()
        .filter(|line| line.trim().starts_with("#pragma omp"))
        .filter_map(|line| {
            parse_openmp_directive(line, Language::C).ok()
        })
        .collect()
}

fn main() {
    let source = r#"
    #pragma omp parallel num_threads(4)
    for (int i = 0; i < n; i++) {
        #pragma omp task
        process(i);
    }
    #pragma omp taskwait
    "#;
    
    let directives = parse_file_directives(source);
    
    println!("Found {} OpenMP directives:", directives.len());
    for (i, dir) in directives.iter().enumerate() {
        println!("  {}. {:?} at line {}", 
                 i + 1, dir.kind, dir.location.line);
    }
}

Directive Analysis

use roup::parser::openmp::parse_openmp_directive;
use roup::ir::{DirectiveIR, ClauseData};
use roup::lexer::Language;

struct DirectiveStats {
    total_clauses: usize,
    has_data_sharing: bool,
    has_scheduling: bool,
    has_reduction: bool,
    thread_count: Option<String>,
}

impl DirectiveStats {
    fn analyze(directive: &DirectiveIR) -> Self {
        let total_clauses = directive.clauses.len();
        
        let mut has_data_sharing = false;
        let mut has_scheduling = false;
        let mut has_reduction = false;
        let mut thread_count = None;
        
        for clause in &directive.clauses {
            match clause {
                ClauseData::Private { .. } | 
                ClauseData::Shared { .. } |
                ClauseData::Firstprivate { .. } |
                ClauseData::Lastprivate { .. } => {
                    has_data_sharing = true;
                }
                ClauseData::Schedule { .. } => {
                    has_scheduling = true;
                }
                ClauseData::Reduction { .. } => {
                    has_reduction = true;
                }
                ClauseData::NumThreads(expr) => {
                    thread_count = Some(expr.value.to_string());
                }
                _ => {}
            }
        }
        
        Self {
            total_clauses,
            has_data_sharing,
            has_scheduling,
            has_reduction,
            thread_count,
        }
    }
}

fn main() {
    let input = "#pragma omp parallel for num_threads(4) \
                 schedule(static) private(x) reduction(+:sum)";
    
    let directive = parse_openmp_directive(input, Language::C).unwrap();
    let stats = DirectiveStats::analyze(&directive);
    
    println!("Directive Analysis:");
    println!("  Total clauses: {}", stats.total_clauses);
    println!("  Has data-sharing: {}", stats.has_data_sharing);
    println!("  Has scheduling: {}", stats.has_scheduling);
    println!("  Has reduction: {}", stats.has_reduction);
    if let Some(count) = stats.thread_count {
        println!("  Thread count: {}", count);
    }
}

Output:

Directive Analysis:
  Total clauses: 4
  Has data-sharing: true
  Has scheduling: true
  Has reduction: true
  Thread count: 4

Building a Directive Validator

use roup::parser::openmp::parse_openmp_directive;
use roup::ir::{DirectiveIR, DirectiveKind, ClauseData};
use roup::lexer::Language;

struct ValidationRule {
    name: &'static str,
    check: fn(&DirectiveIR) -> bool,
}

fn validate_directive(directive: &DirectiveIR, rules: &[ValidationRule]) -> Vec<String> {
    rules.iter()
        .filter(|rule| !(rule.check)(directive))
        .map(|rule| rule.name.to_string())
        .collect()
}

fn main() {
    let rules = vec![
        ValidationRule {
            name: "Parallel regions should specify thread count",
            check: |dir| {
                !dir.kind.is_parallel() || 
                dir.clauses.iter().any(|c| matches!(c, ClauseData::NumThreads(_)))
            },
        },
        ValidationRule {
            name: "For loops with reduction should have schedule clause",
            check: |dir| {
                let has_reduction = dir.clauses.iter()
                    .any(|c| matches!(c, ClauseData::Reduction { .. }));
                let has_schedule = dir.clauses.iter()
                    .any(|c| matches!(c, ClauseData::Schedule { .. }));
                
                !has_reduction || has_schedule
            },
        },
    ];
    
    let input = "#pragma omp parallel";  // Missing num_threads
    let directive = parse_openmp_directive(input, Language::C).unwrap();
    
    let violations = validate_directive(&directive, &rules);
    
    if violations.is_empty() {
        println!("✓ All validation rules passed");
    } else {
        println!("✗ Validation warnings:");
        for violation in violations {
            println!("  - {}", violation);
        }
    }
}

Testing

Unit Testing

#[cfg(test)]
mod tests {
    use roup::parser::openmp::parse_openmp_directive;
    use roup::ir::DirectiveKind;
    use roup::lexer::Language;
    
    #[test]
    fn test_parse_parallel() {
        let input = "#pragma omp parallel";
        let result = parse_openmp_directive(input, Language::C);
        
        assert!(result.is_ok());
        let directive = result.unwrap();
        assert_eq!(directive.kind, DirectiveKind::Parallel);
        assert_eq!(directive.clauses.len(), 0);
    }
    
    #[test]
    fn test_parse_with_clauses() {
        let input = "#pragma omp parallel num_threads(4)";
        let directive = parse_openmp_directive(input, Language::C).unwrap();
        
        assert_eq!(directive.kind, DirectiveKind::Parallel);
        assert_eq!(directive.clauses.len(), 1);
    }
    
    #[test]
    fn test_invalid_directive() {
        let input = "#pragma omp invalid_directive";
        let result = parse_openmp_directive(input, Language::C);
        
        assert!(result.is_err());
    }
    
    #[test]
    fn test_fortran_syntax() {
        let input = "!$omp parallel";
        let result = parse_openmp_directive(input, Language::Fortran);
        
        assert!(result.is_ok());
        let directive = result.unwrap();
        assert_eq!(directive.kind, DirectiveKind::Parallel);
    }
}

Integration Testing

#[cfg(test)]
mod integration_tests {
    use roup::parser::openmp::parse_openmp_directive;
    use roup::ir::ClauseData;
    use roup::lexer::Language;
    
    #[test]
    fn test_complete_parsing_pipeline() {
        let inputs = vec![
            "#pragma omp parallel",
            "#pragma omp for schedule(static)",
            "#pragma omp parallel for num_threads(8) private(x)",
            "#pragma omp task depend(in: x) priority(10)",
        ];
        
        for input in inputs {
            let result = parse_openmp_directive(input, Language::C);
            assert!(result.is_ok(), "Failed to parse: {}", input);
            
            let directive = result.unwrap();
            assert!(directive.kind.is_valid());
            
            // Verify round-trip
            let output = directive.to_string();
            assert!(!output.is_empty());
        }
    }
    
    #[test]
    fn test_clause_extraction() {
        let input = "#pragma omp parallel for \
                     num_threads(4) \
                     schedule(dynamic, 100) \
                     private(i, j) \
                     reduction(+:sum)";
        
        let directive = parse_openmp_directive(input, Language::C).unwrap();
        
        // Count clause types
        let mut num_threads_count = 0;
        let mut schedule_count = 0;
        let mut private_count = 0;
        let mut reduction_count = 0;
        
        for clause in &directive.clauses {
            match clause {
                ClauseData::NumThreads(_) => num_threads_count += 1,
                ClauseData::Schedule { .. } => schedule_count += 1,
                ClauseData::Private { .. } => private_count += 1,
                ClauseData::Reduction { .. } => reduction_count += 1,
                _ => {}
            }
        }
        
        assert_eq!(num_threads_count, 1);
        assert_eq!(schedule_count, 1);
        assert_eq!(private_count, 1);
        assert_eq!(reduction_count, 1);
    }
}

Best Practices

1. Always Handle Errors

// ❌ Bad - unwrap can panic
let directive = parse_openmp_directive(input, Language::C).unwrap();

// ✅ Good - explicit error handling
match parse_openmp_directive(input, Language::C) {
    Ok(directive) => { /* use directive */ }
    Err(e) => { /* handle error */ }
}

2. Use Pattern Matching

// ❌ Bad - lots of if-let chains
for clause in &directive.clauses {
    if let ClauseData::NumThreads(expr) = clause {
        // ...
    } else if let ClauseData::Private { items, .. } = clause {
        // ...
    }
}

// ✅ Good - clean match expression
for clause in &directive.clauses {
    match clause {
        ClauseData::NumThreads(expr) => { /* ... */ }
        ClauseData::Private { items, .. } => { /* ... */ }
        _ => {}
    }
}

3. Leverage Iterator Combinators

// ❌ Bad - manual iteration
let mut has_reduction = false;
for clause in &directive.clauses {
    if matches!(clause, ClauseData::Reduction { .. }) {
        has_reduction = true;
        break;
    }
}

// ✅ Good - iterator method
let has_reduction = directive.clauses.iter()
    .any(|c| matches!(c, ClauseData::Reduction { .. }));

4. Create Helper Functions

// Reusable helper
fn has_clause<F>(directive: &DirectiveIR, predicate: F) -> bool
where
    F: Fn(&ClauseData) -> bool,
{
    directive.clauses.iter().any(predicate)
}

// Usage
if has_clause(&directive, |c| matches!(c, ClauseData::NumThreads(_))) {
    println!("Has num_threads clause");
}

Next Steps

• C Tutorial - Learn the C FFI API
• C++ Tutorial - Build a real-world application
• API Reference - Complete Rust API documentation
• Examples - Check out tests/ directory for 355+ test cases

Summary

Key Takeaways:

1. Use parse_openmp_directive() for parsing
2. Handle errors with Result types
3. Pattern match on DirectiveKind and ClauseData
4. Use iterators for clause analysis
5. Write tests for your integration code

Common Patterns:

// Parse
let directive = parse_openmp_directive(input, Language::C)?;

// Check kind
if directive.kind.is_parallel() { /* ... */ }

// Find clause
let num_threads = directive.clauses.iter()
    .find_map(|c| match c {
        ClauseData::NumThreads(expr) => Some(expr.value.clone()),
        _ => None,
    });

// Analyze all clauses
for clause in &directive.clauses {
    match clause {
        ClauseData::Private { items, .. } => { /* ... */ }
        ClauseData::Shared { items, .. } => { /* ... */ }
        _ => {}
    }
}

Happy parsing! 🦀

C Tutorial

This tutorial demonstrates how to use ROUP's minimal unsafe pointer-based C API for parsing OpenMP directives. The API uses direct C pointers following standard malloc/free patterns familiar to C programmers.

API Design: Direct pointers (*mut OmpDirective, *mut OmpClause) with manual memory management. No global state, no handles.

Source: src/c_api.rs - 16 FFI functions, ~60 lines of unsafe code

Prerequisites

Before starting, ensure you have:

• C compiler (GCC, Clang, or MSVC)
• ROUP library compiled (see Building Guide)
• Basic understanding of malloc/free patterns

Example code: See examples/c/tutorial_basic.c for a complete working example.

Step 1: Setup and Compilation

Project Structure

my-project/
├── src/
│   └── main.c
├── include/
│   └── roup_ffi.h      # Forward declarations
└── libroup.a            # Built from cargo build

Forward Declarations

Create include/roup_ffi.h with the C API declarations:

#ifndef ROUP_FFI_H
#define ROUP_FFI_H

#include <stdint.h>

// Opaque types (defined in Rust)
typedef struct OmpDirective OmpDirective;
typedef struct OmpClause OmpClause;
typedef struct OmpClauseIterator OmpClauseIterator;
typedef struct OmpStringList OmpStringList;

// Lifecycle functions
extern OmpDirective* roup_parse(const char* input);
extern void roup_directive_free(OmpDirective* directive);
extern void roup_clause_free(OmpClause* clause);

// Directive queries
extern int32_t roup_directive_kind(const OmpDirective* directive);
extern int32_t roup_directive_clause_count(const OmpDirective* directive);
extern OmpClauseIterator* roup_directive_clauses_iter(const OmpDirective* directive);

// Iterator functions
extern int32_t roup_clause_iterator_next(OmpClauseIterator* iter, OmpClause** out);
extern void roup_clause_iterator_free(OmpClauseIterator* iter);

// Clause queries
extern int32_t roup_clause_kind(const OmpClause* clause);
extern int32_t roup_clause_schedule_kind(const OmpClause* clause);
extern int32_t roup_clause_reduction_operator(const OmpClause* clause);
extern int32_t roup_clause_default_data_sharing(const OmpClause* clause);

// Variable lists
extern OmpStringList* roup_clause_variables(const OmpClause* clause);
extern int32_t roup_string_list_len(const OmpStringList* list);
extern const char* roup_string_list_get(const OmpStringList* list, int32_t index);
extern void roup_string_list_free(OmpStringList* list);

#endif // ROUP_FFI_H

Compilation

Option 1: Using GCC/Clang

# Build ROUP library
cargo build --release

# Compile C program
gcc -o my_app src/main.c \
    -I include \
    -L target/release \
    -lroup \
    -lpthread -ldl -lm

Option 2: Using CMake

cmake_minimum_required(VERSION 3.10)
project(roup_example C)

add_executable(my_app src/main.c)
target_include_directories(my_app PRIVATE include)
target_link_libraries(my_app ${CMAKE_SOURCE_DIR}/target/release/libroup.a pthread dl m)

Step 2: Parse a Simple Directive

Let's start with the most basic operation: parsing a simple directive.

#include <stdio.h>
#include "roup_ffi.h"

int main(void) {
    const char* input = "#pragma omp parallel";
    
    // Parse the directive
    OmpDirective* dir = roup_parse(input);
    
    // Check for errors (NULL = parse failed)
    if (!dir) {
        fprintf(stderr, "Parse failed!\n");
        return 1;
    }
    
    printf("✅ Parse succeeded!\n");
    
    // IMPORTANT: Free the directive
    roup_directive_free(dir);
    
    return 0;
}

Key Points:

• roup_parse() returns a pointer or NULL on error
• Always check for NULL before using the directive
• Always call roup_directive_free() to prevent memory leaks

Step 3: Query Directive Properties

After parsing, you can query the directive's properties:

#include <stdio.h>
#include "roup_ffi.h"

int main(void) {
    const char* input = "#pragma omp parallel for num_threads(4)";
    
    OmpDirective* dir = roup_parse(input);
    if (!dir) {
        return 1;
    }
    
    // Query directive properties
    int32_t kind = roup_directive_kind(dir);
    int32_t clause_count = roup_directive_clause_count(dir);
    
    printf("Directive kind: %d\n", kind);
    printf("Clause count: %d\n", clause_count);
    
    roup_directive_free(dir);
    return 0;
}

Output:

Directive kind: 28
Clause count: 1

Note: Directive kind is an integer from the parser's internal registry. For practical use, you typically care more about the clauses than the exact directive kind. The kind value comes from the order in which directives were registered in src/parser/openmp.rs - these internal IDs are not part of the stable API and may change between versions.

Step 4: Iterate Through Clauses

To access individual clauses, use the iterator pattern:

#include <stdio.h>
#include "roup_ffi.h"

const char* clause_name(int32_t kind) {
    switch(kind) {
        case 0: return "num_threads";
        case 1: return "if";
        case 2: return "private";
        case 3: return "shared";
        case 6: return "reduction";
        case 7: return "schedule";
        case 10: return "nowait";
        default: return "unknown";
    }
}

int main(void) {
    const char* input = "#pragma omp parallel num_threads(8) default(shared) nowait";
    
    OmpDirective* dir = roup_parse(input);
    if (!dir) return 1;
    
    // Create iterator
    OmpClauseIterator* iter = roup_directive_clauses_iter(dir);
    if (!iter) {
        roup_directive_free(dir);
        return 1;
    }
    
    // Iterate through clauses
    printf("Clauses:\n");
    OmpClause* clause;
    while (roup_clause_iterator_next(iter, &clause)) {
        int32_t kind = roup_clause_kind(clause);
        printf("  - %s (kind=%d)\n", clause_name(kind), kind);
    }
    
    // Cleanup
    roup_clause_iterator_free(iter);
    roup_directive_free(dir);
    
    return 0;
}

Output:

Clauses:
  - num_threads (kind=0)
  - default (kind=11)
  - nowait (kind=10)

Key Points:

• roup_clause_iterator_next() returns 1 if clause available, 0 when done
• Write the clause pointer to out parameter
• Always free the iterator with roup_clause_iterator_free()

Step 5: Query Clause-Specific Data

Different clause types have different data. Use type-specific query functions:

Schedule Clause

OmpClause* clause = /* ... get clause ... */;
if (roup_clause_kind(clause) == 7) {  // SCHEDULE
    int32_t sched = roup_clause_schedule_kind(clause);
    const char* names[] = {"static", "dynamic", "guided", "auto", "runtime"};
    printf("Schedule: %s\n", names[sched]);
}

Reduction Clause

if (roup_clause_kind(clause) == 6) {  // REDUCTION
    int32_t op = roup_clause_reduction_operator(clause);
    const char* ops[] = {"+", "-", "*", "&", "|", "^", "&&", "||", "min", "max"};
    printf("Reduction operator: %s\n", ops[op]);
}

Default Clause

if (roup_clause_kind(clause) == 11) {  // DEFAULT
    int32_t def = roup_clause_default_data_sharing(clause);
    printf("Default: %s\n", def == 0 ? "shared" : "none");
}

Complete Example

#include <stdio.h>
#include "roup_ffi.h"

int main(void) {
    const char* input = "#pragma omp parallel for schedule(static, 10) reduction(+:sum)";
    
    OmpDirective* dir = roup_parse(input);
    if (!dir) return 1;
    
    OmpClauseIterator* iter = roup_directive_clauses_iter(dir);
    if (!iter) {
        roup_directive_free(dir);
        return 1;
    }
    
    OmpClause* clause;
    while (roup_clause_iterator_next(iter, &clause)) {
        int32_t kind = roup_clause_kind(clause);
        
        if (kind == 7) {  // SCHEDULE
            int32_t sched = roup_clause_schedule_kind(clause);
            const char* names[] = {"static", "dynamic", "guided", "auto", "runtime"};
            printf("Schedule: %s\n", names[sched]);
        }
        else if (kind == 6) {  // REDUCTION
            int32_t op = roup_clause_reduction_operator(clause);
            const char* ops[] = {"+", "-", "*", "&", "|", "^", "&&", "||", "min", "max"};
            printf("Reduction: %s\n", ops[op]);
        }
    }
    
    roup_clause_iterator_free(iter);
    roup_directive_free(dir);
    
    return 0;
}

Output:

Schedule: static
Reduction: +

Step 6: Access Variable Lists

Clauses like private(x, y, z) contain lists of variables:

#include <stdio.h>
#include "roup_ffi.h"

int main(void) {
    const char* input = "#pragma omp parallel private(x, y, z) shared(a, b)";
    
    OmpDirective* dir = roup_parse(input);
    if (!dir) return 1;
    
    OmpClauseIterator* iter = roup_directive_clauses_iter(dir);
    if (!iter) {
        roup_directive_free(dir);
        return 1;
    }
    
    OmpClause* clause;
    while (roup_clause_iterator_next(iter, &clause)) {
        int32_t kind = roup_clause_kind(clause);
        
        // Get variable list
        OmpStringList* vars = roup_clause_variables(clause);
        if (vars) {
            int32_t len = roup_string_list_len(vars);
            
            const char* kind_name = (kind == 2) ? "private" : "shared";
            printf("%s variables: ", kind_name);
            
            for (int32_t i = 0; i < len; i++) {
                const char* var = roup_string_list_get(vars, i);
                printf("%s%s", var, (i < len - 1) ? ", " : "");
            }
            printf("\n");
            
            roup_string_list_free(vars);
        }
    }
    
    roup_clause_iterator_free(iter);
    roup_directive_free(dir);
    
    return 0;
}

Output:

private variables: x, y, z
shared variables: a, b

Key Points:

• roup_clause_variables() returns a OmpStringList* or NULL
• Use roup_string_list_len() to get the count
• Use roup_string_list_get(list, index) to access individual strings
• Always call roup_string_list_free() when done

Step 7: Error Handling

Robust error handling is crucial. The API returns NULL on failure:

#include <stdio.h>
#include "roup_ffi.h"

int main(void) {
    // Test 1: Invalid syntax
    const char* invalid = "#pragma omp INVALID_DIRECTIVE";
    OmpDirective* dir1 = roup_parse(invalid);
    if (!dir1) {
        printf("✓ Invalid syntax correctly rejected\n");
    }
    
    // Test 2: NULL input
    OmpDirective* dir2 = roup_parse(NULL);
    if (!dir2) {
        printf("✓ NULL input correctly rejected\n");
    }
    
    // Test 3: Empty string
    OmpDirective* dir3 = roup_parse("");
    if (!dir3) {
        printf("✓ Empty string correctly rejected\n");
    }
    
    // Test 4: Querying NULL
    int32_t kind = roup_directive_kind(NULL);
    printf("roup_directive_kind(NULL) = %d\n", kind);  // Returns -1
    
    return 0;
}

Error Handling Guidelines:

1. Always check roup_parse() return value for NULL
2. Check roup_directive_clauses_iter() for NULL
3. Query functions return -1 or safe defaults for NULL inputs
4. Free resources even in error paths (if allocated)

Step 8: Complete Example

Here's a complete program that demonstrates all concepts:

#include <stdio.h>
#include <stdlib.h>
#include "roup_ffi.h"

void print_clause_details(OmpClause* clause) {
    int32_t kind = roup_clause_kind(clause);
    
    switch(kind) {
        case 0:
            printf("  - num_threads\n");
            break;
        case 2: {
            printf("  - private(");
            OmpStringList* vars = roup_clause_variables(clause);
            if (vars) {
                int32_t len = roup_string_list_len(vars);
                for (int32_t i = 0; i < len; i++) {
                    printf("%s%s", roup_string_list_get(vars, i), 
                           (i < len - 1) ? ", " : "");
                }
                roup_string_list_free(vars);
            }
            printf(")\n");
            break;
        }
        case 6: {
            printf("  - reduction(");
            int32_t op = roup_clause_reduction_operator(clause);
            const char* ops[] = {"+", "-", "*", "&", "|", "^", "&&", "||", "min", "max"};
            if (op >= 0 && op < 10) {
                printf("%s", ops[op]);
            }
            printf(":...)\n");
            break;
        }
        case 7: {
            printf("  - schedule(");
            int32_t sched = roup_clause_schedule_kind(clause);
            const char* names[] = {"static", "dynamic", "guided", "auto", "runtime"};
            if (sched >= 0 && sched < 5) {
                printf("%s", names[sched]);
            }
            printf(")\n");
            break;
        }
        case 10:
            printf("  - nowait\n");
            break;
        case 11:
            printf("  - default(%s)\n", 
                   roup_clause_default_data_sharing(clause) == 0 ? "shared" : "none");
            break;
        default:
            printf("  - unknown (kind=%d)\n", kind);
            break;
    }
}

int main(void) {
    const char* test_cases[] = {
        "#pragma omp parallel",
        "#pragma omp parallel for num_threads(4) private(i, j)",
        "#pragma omp parallel for schedule(static, 100) reduction(+:sum)",
        "#pragma omp task default(shared) nowait",
        NULL
    };
    
    for (int i = 0; test_cases[i] != NULL; i++) {
        printf("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
        printf("Input: %s\n", test_cases[i]);
        printf("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
        
        OmpDirective* dir = roup_parse(test_cases[i]);
        if (!dir) {
            printf("❌ Parse failed!\n");
            continue;
        }
        
        int32_t clause_count = roup_directive_clause_count(dir);
        printf("Clauses: %d\n", clause_count);
        
        if (clause_count > 0) {
            OmpClauseIterator* iter = roup_directive_clauses_iter(dir);
            if (iter) {
                OmpClause* clause;
                while (roup_clause_iterator_next(iter, &clause)) {
                    print_clause_details(clause);
                }
                roup_clause_iterator_free(iter);
            }
        }
        
        roup_directive_free(dir);
    }
    
    printf("\n✅ All tests completed!\n\n");
    return 0;
}

Clause Kind Reference

The C API supports 12 common clause types:

Schedule Kinds (for clause kind 7):

• 0 = static
• 1 = dynamic
• 2 = guided
• 3 = auto
• 4 = runtime

Reduction Operators (for clause kind 6):

• 0 = +, 1 = -, 2 = *
• 3 = &, 4 = |, 5 = ^
• 6 = &&, 7 = ||
• 8 = min, 9 = max

Default Kinds (for clause kind 11):

• 0 = shared
• 1 = none
• 2 = private
• 3 = firstprivate

Memory Management Checklist

✅ DO:

• Call roup_directive_free() for every successful roup_parse()
• Call roup_clause_iterator_free() for every roup_directive_clauses_iter()
• Call roup_string_list_free() for every roup_clause_variables()
• Check for NULL returns before using pointers

❌ DON'T:

• Call roup_clause_free() on clauses from iterators (owned by directive)
• Access freed pointers (use-after-free)
• Forget to free in error paths
• Assume parse always succeeds

Performance Tips

1. Reuse parsed directives - Don't reparse the same string repeatedly
2. Minimize FFI crossings - Batch operations when possible
3. Avoid unnecessary iteration - If you only need clause count, don't iterate
4. Use local variables - Cache query results instead of calling repeatedly

Example (inefficient):

// BAD: Queries kind multiple times
for (int i = 0; i < count; i++) {
    if (roup_clause_kind(clause) == 2) {
        process_private(roup_clause_kind(clause));
    }
}

Example (efficient):

// GOOD: Cache the kind
int32_t kind = roup_clause_kind(clause);
if (kind == 2) {
    process_private(kind);
}

Next Steps

Now that you understand the C API basics:

1. Build the example - Compile and run examples/c/tutorial_basic.c
2. Explore directives - See OpenMP Support for all 120+ directives
3. Advanced usage - Check API Reference for complete function details
4. C++ wrappers - Read C++ Tutorial for RAII wrappers

Full Example Code: examples/c/tutorial_basic.c (433 lines with detailed comments)

Troubleshooting

Linker Errors

Problem: undefined reference to roup_parse

Solution: Link against the ROUP static library:

gcc ... -L target/release -lroup -lpthread -ldl -lm

Parse Always Returns NULL

Problem: All parses fail, even valid input

Solution:

• Check that the library was built correctly (cargo build --release)
• Verify the input string is valid OpenMP syntax
• Ensure the string is null-terminated
• Try the examples first to verify the library works

Memory Leaks

Problem: Valgrind reports memory leaks

Solution:

• Ensure every roup_parse() has a matching roup_directive_free()
• Ensure every roup_directive_clauses_iter() has a matching roup_clause_iterator_free()
• Ensure every roup_clause_variables() has a matching roup_string_list_free()

Segmentation Fault

Problem: Program crashes with segfault

Solution:

• Check for NULL before dereferencing pointers
• Don't access freed pointers
• Don't call roup_clause_free() on clauses from iterators

Questions? Check the FAQ or open an issue on GitHub.

C++ Tutorial: Building a Real Application

This tutorial shows how to integrate ROUP into a real C++ application using modern C++17 features.

We'll build an OpenMP pragma analyzer - a tool that reads C/C++ source files, extracts OpenMP directives, and reports statistics.

What You'll Build

A command-line tool that:

1. Reads source files line-by-line
2. Detects OpenMP pragmas
3. Parses them using ROUP
4. Reports directive types and clause counts
5. Provides summary statistics

Example output:

$ ./omp_analyzer mycode.c
Found 5 OpenMP directives:
  Line 10: parallel (3 clauses)
  Line 25: for (2 clauses)
  Line 42: parallel for (4 clauses)
  Line 68: task (1 clause)
  Line 95: barrier (0 clauses)

Summary:
  Total directives: 5
  Total clauses: 10
  Most common: parallel (2 occurrences)

Prerequisites

• C++ Compiler: clang++ or g++ with C++17 support
• ROUP Library: Built and installed (see below)
• System: Linux, macOS, or Windows with WSL

Building ROUP

git clone https://github.com/ouankou/roup.git
cd roup
cargo build --release

# Library is now at: target/release/libroup.so (Linux)
#                or: target/release/libroup.dylib (macOS)

Step 1: Understanding the ROUP C API

ROUP exports a minimal C API with 16 functions. Here are the key ones for our tool:

Lifecycle Functions

// Parse an OpenMP directive string
OmpDirective* roup_parse(const char* input);

// Free the parsed directive
void roup_directive_free(OmpDirective* directive);

Query Functions

// Get directive type (0=parallel, 1=for, 4=task, etc.)
int32_t roup_directive_kind(const OmpDirective* directive);

// Get number of clauses
int32_t roup_directive_clause_count(const OmpDirective* directive);

// Create iterator for clauses
OmpClauseIterator* roup_directive_clauses_iter(const OmpDirective* directive);

// Get next clause (returns 1 if available, 0 if done)
int32_t roup_clause_iterator_next(OmpClauseIterator* iter, OmpClause** out);

// Get clause type (0=num_threads, 2=private, 6=reduction, etc.)
int32_t roup_clause_kind(const OmpClause* clause);

// Free iterator
void roup_clause_iterator_free(OmpClauseIterator* iter);

Step 2: Create RAII Wrappers (Modern C++)

Instead of manual memory management, let's use RAII (Resource Acquisition Is Initialization) to automatically clean up resources.

Create roup_wrapper.hpp:

#pragma once
#include <cstdint>
#include <memory>
#include <string>
#include <vector>
#include <optional>

// Forward declarations of opaque C types
struct OmpDirective;
struct OmpClause;
struct OmpClauseIterator;

// C API declarations
extern "C" {
    OmpDirective* roup_parse(const char* input);
    void roup_directive_free(OmpDirective* directive);
    int32_t roup_directive_kind(const OmpDirective* directive);
    int32_t roup_directive_clause_count(const OmpDirective* directive);
    OmpClauseIterator* roup_directive_clauses_iter(const OmpDirective* directive);
    int32_t roup_clause_iterator_next(OmpClauseIterator* iter, OmpClause** out);
    void roup_clause_iterator_free(OmpClauseIterator* iter);
    int32_t roup_clause_kind(const OmpClause* clause);
}

namespace roup {

// RAII wrapper for OmpDirective
class Directive {
private:
    OmpDirective* ptr_;

public:
    // Constructor: parse directive
    explicit Directive(const std::string& input) 
        : ptr_(roup_parse(input.c_str())) {}
    
    // Destructor: automatic cleanup
    ~Directive() {
        if (ptr_) {
            roup_directive_free(ptr_);
        }
    }
    
    // Delete copy (move-only type)
    Directive(const Directive&) = delete;
    Directive& operator=(const Directive&) = delete;
    
    // Move constructor
    Directive(Directive&& other) noexcept : ptr_(other.ptr_) {
        other.ptr_ = nullptr;
    }
    
    // Move assignment
    Directive& operator=(Directive&& other) noexcept {
        if (this != &other) {
            if (ptr_) roup_directive_free(ptr_);
            ptr_ = other.ptr_;
            other.ptr_ = nullptr;
        }
        return *this;
    }
    
    // Check if parse succeeded
    bool valid() const { return ptr_ != nullptr; }
    explicit operator bool() const { return valid(); }
    
    // Get directive kind
    int32_t kind() const {
        return ptr_ ? roup_directive_kind(ptr_) : -1;
    }
    
    // Get clause count
    int32_t clause_count() const {
        return ptr_ ? roup_directive_clause_count(ptr_) : 0;
    }
    
    // Get raw pointer (for advanced usage)
    OmpDirective* get() const { return ptr_; }
};

// RAII wrapper for OmpClauseIterator
class ClauseIterator {
private:
    OmpClauseIterator* iter_;
    
public:
    explicit ClauseIterator(const Directive& directive)
        : iter_(directive.valid() ? roup_directive_clauses_iter(directive.get()) : nullptr) {}
    
    ~ClauseIterator() {
        if (iter_) {
            roup_clause_iterator_free(iter_);
        }
    }
    
    // Delete copy
    ClauseIterator(const ClauseIterator&) = delete;
    ClauseIterator& operator=(const ClauseIterator&) = delete;
    
    // Get next clause kind (returns std::optional)
    std::optional<int32_t> next() {
        if (!iter_) return std::nullopt;
        
        OmpClause* clause = nullptr;
        if (roup_clause_iterator_next(iter_, &clause) == 1) {
            return roup_clause_kind(clause);
            // Note: Don't free clause - owned by directive
        }
        return std::nullopt;
    }
};

// Helper: Convert directive kind to name
inline const char* directive_kind_name(int32_t kind) {
    switch (kind) {
        case 0: return "parallel";
        case 1: return "for";
        case 2: return "sections";
        case 3: return "single";
        case 4: return "task";
        case 5: return "master";
        case 6: return "critical";
        case 7: return "barrier";
        case 8: return "taskwait";
        case 9: return "taskgroup";
        case 10: return "atomic";
        case 11: return "flush";
        case 12: return "ordered";
        case 13: return "target";
        case 14: return "teams";
        case 15: return "distribute";
        case 16: return "metadirective";
        default: return "unknown";
    }
}

// Helper: Convert clause kind to name
inline const char* clause_kind_name(int32_t kind) {
    switch (kind) {
        case 0: return "num_threads";
        case 1: return "if";
        case 2: return "private";
        case 3: return "shared";
        case 4: return "firstprivate";
        case 5: return "lastprivate";
        case 6: return "reduction";
        case 7: return "schedule";
        case 8: return "collapse";
        case 9: return "ordered";
        case 10: return "nowait";
        case 11: return "default";
        default: return "unknown";
    }
}

} // namespace roup

Key RAII benefits:

• ✅ Automatic cleanup - No need to call _free() functions
• ✅ Exception safe - Resources freed even if exceptions thrown
• ✅ Move semantics - Efficient transfer of ownership
• ✅ Modern C++ - Uses std::optional, deleted copy constructors

Step 3: Build the Analyzer Tool

Create omp_analyzer.cpp:

#include "roup_wrapper.hpp"
#include <iostream>
#include <fstream>
#include <string>
#include <map>
#include <vector>
#include <algorithm>

struct DirectiveInfo {
    int line_number;
    std::string directive_name;
    int clause_count;
    std::vector<std::string> clause_names;
};

class OMPAnalyzer {
private:
    std::vector<DirectiveInfo> directives_;
    std::map<std::string, int> directive_counts_;
    
public:
    // Analyze a single line for OpenMP pragmas
    void analyze_line(const std::string& line, int line_number) {
        // Check if line contains OpenMP pragma
        if (line.find("#pragma omp") == std::string::npos) {
            return;
        }
        
        // Parse the directive
        roup::Directive directive(line);
        if (!directive) {
            std::cerr << "Warning: Failed to parse line " << line_number 
                      << ": " << line << std::endl;
            return;
        }
        
        // Extract directive info
        DirectiveInfo info;
        info.line_number = line_number;
        info.directive_name = roup::directive_kind_name(directive.kind());
        info.clause_count = directive.clause_count();
        
        // Extract clause names
        roup::ClauseIterator iter(directive);
        while (auto clause_kind = iter.next()) {
            info.clause_names.push_back(roup::clause_kind_name(*clause_kind));
        }
        
        directives_.push_back(info);
        directive_counts_[info.directive_name]++;
    }
    
    // Analyze entire file
    bool analyze_file(const std::string& filename) {
        std::ifstream file(filename);
        if (!file) {
            std::cerr << "Error: Cannot open file: " << filename << std::endl;
            return false;
        }
        
        std::string line;
        int line_number = 0;
        
        while (std::getline(file, line)) {
            line_number++;
            analyze_line(line, line_number);
        }
        
        return true;
    }
    
    // Print detailed report
    void print_report() const {
        if (directives_.empty()) {
            std::cout << "No OpenMP directives found." << std::endl;
            return;
        }
        
        std::cout << "\nFound " << directives_.size() 
                  << " OpenMP directive(s):\n" << std::endl;
        
        for (const auto& info : directives_) {
            std::cout << "  Line " << info.line_number << ": "
                      << info.directive_name << " ("
                      << info.clause_count << " clause"
                      << (info.clause_count != 1 ? "s" : "") << ")";
            
            if (!info.clause_names.empty()) {
                std::cout << " [";
                for (size_t i = 0; i < info.clause_names.size(); ++i) {
                    if (i > 0) std::cout << ", ";
                    std::cout << info.clause_names[i];
                }
                std::cout << "]";
            }
            std::cout << std::endl;
        }
        
        print_summary();
    }
    
    // Print summary statistics
    void print_summary() const {
        int total_clauses = 0;
        for (const auto& info : directives_) {
            total_clauses += info.clause_count;
        }
        
        std::cout << "\nSummary:" << std::endl;
        std::cout << "  Total directives: " << directives_.size() << std::endl;
        std::cout << "  Total clauses: " << total_clauses << std::endl;
        
        // Find most common directive
        auto max_elem = std::max_element(
            directive_counts_.begin(), 
            directive_counts_.end(),
            [](const auto& a, const auto& b) { return a.second < b.second; }
        );
        
        if (max_elem != directive_counts_.end()) {
            std::cout << "  Most common: " << max_elem->first 
                      << " (" << max_elem->second << " occurrence"
                      << (max_elem->second != 1 ? "s" : "") << ")" << std::endl;
        }
        
        // Print directive type breakdown
        if (directive_counts_.size() > 1) {
            std::cout << "\nDirective breakdown:" << std::endl;
            for (const auto& [name, count] : directive_counts_) {
                std::cout << "  " << name << ": " << count << std::endl;
            }
        }
    }
};

int main(int argc, char* argv[]) {
    if (argc < 2) {
        std::cerr << "Usage: " << argv[0] << " <source-file>" << std::endl;
        std::cerr << "Example: " << argv[0] << " mycode.c" << std::endl;
        return 1;
    }
    
    OMPAnalyzer analyzer;
    
    if (!analyzer.analyze_file(argv[1])) {
        return 1;
    }
    
    analyzer.print_report();
    return 0;
}
```text

---

## Step 4: Build and Run

### Compilation

```bash
# Build ROUP library first
cd roup
cargo build --release

# Build the analyzer
clang++ -std=c++17 omp_analyzer.cpp \
    -L./target/release -lroup \
    -Wl,-rpath,./target/release \
    -o omp_analyzer

# Or with g++:
g++ -std=c++17 omp_analyzer.cpp \
    -L./target/release -lroup \
    -Wl,-rpath,./target/release \
    -o omp_analyzer

Test with Sample File

Create test.c:

#include <stdio.h>

int main() {
    int n = 1000;
    int sum = 0;
    
    #pragma omp parallel for reduction(+:sum) num_threads(4)
    for (int i = 0; i < n; i++) {
        sum += i;
    }
    
    #pragma omp parallel
    {
        #pragma omp single
        {
            printf("Hello from thread\\n");
        }
    }
    
    #pragma omp task depend(in: sum)
    printf("Sum: %d\\n", sum);
    
    #pragma omp barrier
    
    return 0;
}

Run the Analyzer

$ ./omp_analyzer test.c

Found 5 OpenMP directive(s):

  Line 7: for (3 clauses) [reduction, num_threads]
  Line 11: parallel (0 clauses)
  Line 13: single (0 clauses)
  Line 19: task (1 clause) [depend]
  Line 22: barrier (0 clauses)

Summary:
  Total directives: 5
  Total clauses: 4
  Most common: parallel (1 occurrence)

Directive breakdown:
  barrier: 1
  for: 1
  parallel: 1
  single: 1
  task: 1

Step 5: Advanced Features

5.1 Extract Variable Names from Clauses

Some clauses (like private, shared) contain variable lists. To access them:

// In C API (add to roup_wrapper.hpp):
extern "C" {
    OmpStringList* roup_clause_variables(const OmpClause* clause);
    int32_t roup_string_list_len(const OmpStringList* list);
    const char* roup_string_list_get(const OmpStringList* list, int32_t index);
    void roup_string_list_free(OmpStringList* list);
}

// RAII wrapper for string list
class StringList {
private:
    OmpStringList* list_;
    
public:
    explicit StringList(OmpStringList* list) : list_(list) {}
    
    ~StringList() {
        if (list_) roup_string_list_free(list_);
    }
    
    int32_t size() const {
        return list_ ? roup_string_list_len(list_) : 0;
    }
    
    std::string get(int32_t index) const {
        if (!list_ || index >= size()) return "";
        return roup_string_list_get(list_, index);
    }
    
    std::vector<std::string> to_vector() const {
        std::vector<std::string> result;
        for (int32_t i = 0; i < size(); ++i) {
            result.push_back(get(i));
        }
        return result;
    }
};
```text

### 5.2 Handle Parse Errors Gracefully

```cpp
std::optional<DirectiveInfo> parse_directive(const std::string& line) {
    roup::Directive directive(line);
    if (!directive) {
        return std::nullopt;  // Parse failed
    }
    
    DirectiveInfo info;
    info.directive_name = roup::directive_kind_name(directive.kind());
    info.clause_count = directive.clause_count();
    
    return info;
}

5.3 Process Multiple Files

void analyze_project(const std::vector<std::string>& files) {
    OMPAnalyzer combined;
    
    for (const auto& file : files) {
        OMPAnalyzer file_analyzer;
        if (file_analyzer.analyze_file(file)) {
            std::cout << "\n=== " << file << " ===" << std::endl;
            file_analyzer.print_report();
        }
    }
}

Real-World Use Cases

1. OpenMP Linter

Check for common mistakes:

• parallel for without private on loop variable
• reduction with unsupported operators
• Missing nowait opportunities

2. Code Modernization Tool

• Convert OpenMP 3.x → 5.x syntax
• Suggest modern alternatives (e.g., taskloop instead of manual tasks)

3. Performance Analyzer

• Count parallelization opportunities
• Identify nested parallel regions (potential over-subscription)
• Find synchronization hotspots

4. IDE Integration

• Syntax highlighting for OpenMP pragmas
• Auto-completion for clause names
• Quick documentation lookup

Performance Considerations

ROUP is fast:

• Parsing a typical directive: ~1-5 microseconds
• Zero-copy design: Uses string slices, not allocations
• Suitable for real-time IDE integration

Benchmark (on typical code):

File size: 10,000 lines
OpenMP directives: 500
Total parse time: ~2.5 milliseconds
Throughput: ~200,000 directives/second

Troubleshooting

Issue: undefined reference to roup_parse

Solution: Make sure library path is correct:

clang++ ... -L./target/release -lroup -Wl,-rpath,./target/release

Issue: error while loading shared libraries: libroup.so

Solution: Set LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS):

export LD_LIBRARY_PATH=./target/release:$LD_LIBRARY_PATH

Issue: Parse failures on valid pragmas

Cause: ROUP currently supports C/C++ syntax (#pragma omp), not Fortran (!$omp).

Solution: Ensure input starts with #pragma omp.

Next Steps

• Explore the Rust API - See API Reference
• Check out more examples - GitHub repository
• Contribute - Report issues or submit PRs!

Complete Example Code

All code from this tutorial is available at:

• examples/cpp/roup_wrapper.hpp - RAII wrappers
• examples/cpp/omp_analyzer.cpp - Full analyzer tool

Clone and try:

git clone https://github.com/ouankou/roup.git
cd roup/examples/cpp
make  # Builds all examples
./omp_analyzer ../../tests/data/sample.c

Happy parsing! 🚀

Fortran Tutorial

This tutorial demonstrates how to use ROUP to parse OpenMP directives in Fortran code.

🚧 Experimental Status

Fortran support in ROUP is currently experimental. Features may change as development progresses.

Introduction

ROUP supports parsing OpenMP directives from Fortran source code in both free-form and fixed-form formats. This enables Fortran developers to:

• Parse OpenMP directives from Fortran source
• Validate directive syntax
• Extract clause information
• Build tools for Fortran+OpenMP code analysis

Fortran Directive Formats

Free-Form (Modern Fortran)

Free-form Fortran uses the !$OMP sentinel (case-insensitive):

!$OMP PARALLEL PRIVATE(A, B) NUM_THREADS(4)
!$OMP END PARALLEL

!$omp parallel do private(i) reduction(+:sum)
!$OMP END PARALLEL DO

Fixed-Form (Fortran 77)

Fixed-form Fortran uses !$OMP or C$OMP sentinels in columns 1-6:

C$OMP PARALLEL PRIVATE(X, Y)
!$OMP DO SCHEDULE(STATIC, 10)
C$OMP END DO
C$OMP END PARALLEL

Fortran-Specific Directives

ROUP supports Fortran-specific directive syntax, including the Fortran DO construct which is equivalent to C/C++ FOR:

DO Directive (Fortran)

!$OMP DO PRIVATE(I) SCHEDULE(STATIC)
    do i = 1, n
        ! Loop body
    end do
!$OMP END DO

PARALLEL DO (Fortran)

!$OMP PARALLEL DO PRIVATE(I) REDUCTION(+:SUM)
    do i = 1, n
        sum = sum + a(i)
    end do
!$OMP END PARALLEL DO

Note: ROUP recognizes both Fortran syntax (DO) and C syntax (FOR) for compatibility:

• !$OMP DO → Fortran-specific (preferred for Fortran code)
• !$OMP FOR → C/C++ syntax (also works in Fortran mode)
• !$OMP PARALLEL DO → Fortran-specific
• !$OMP PARALLEL FOR → C/C++ syntax (also works in Fortran mode)

Language Constants

ROUP provides language format constants for Fortran parsing:

#define ROUP_LANG_C                0  // C/C++ (#pragma omp)
#define ROUP_LANG_FORTRAN_FREE     1  // Fortran free-form (!$OMP)
#define ROUP_LANG_FORTRAN_FIXED    2  // Fortran fixed-form (!$OMP or C$OMP)

Using the Rust API

Parsing Fortran Directives

use roup::lexer::Language;
use roup::parser::openmp;

// Create parser with Fortran free-form support
let parser = openmp::parser().with_language(Language::FortranFree);

// Parse a Fortran OpenMP directive
let input = "!$OMP PARALLEL PRIVATE(A, B) NUM_THREADS(4)";
let (rest, directive) = parser.parse(input).expect("parsing should succeed");

println!("Directive: {}", directive.name);
println!("Clauses: {}", directive.clauses.len());

Supported Language Formats

use roup::lexer::Language;

// C/C++ format (default)
let c_parser = openmp::parser().with_language(Language::C);

// Fortran free-form
let fortran_free = openmp::parser().with_language(Language::FortranFree);

// Fortran fixed-form
let fortran_fixed = openmp::parser().with_language(Language::FortranFixed);

Using the C API from Fortran

Setting Up Fortran-C Interoperability

Create an interface module for ROUP C API:

module roup_interface
    use iso_c_binding
    implicit none
    
    ! Language constants
    integer(c_int), parameter :: ROUP_LANG_FORTRAN_FREE = 1
    integer(c_int), parameter :: ROUP_LANG_FORTRAN_FIXED = 2
    
    interface
        ! Parse with language specification
        function roup_parse_with_language(input, language) &
            bind(C, name="roup_parse_with_language")
            use iso_c_binding
            type(c_ptr), value :: input
            integer(c_int), value :: language
            type(c_ptr) :: roup_parse_with_language
        end function roup_parse_with_language
        
        ! Free directive
        subroutine roup_directive_free(directive) &
            bind(C, name="roup_directive_free")
            use iso_c_binding
            type(c_ptr), value :: directive
        end subroutine roup_directive_free
        
        ! Get directive name
        function roup_directive_name(directive) &
            bind(C, name="roup_directive_name")
            use iso_c_binding
            type(c_ptr), value :: directive
            type(c_ptr) :: roup_directive_name
        end function roup_directive_name
        
        ! Get clause count
        function roup_directive_clause_count(directive) &
            bind(C, name="roup_directive_clause_count")
            use iso_c_binding
            type(c_ptr), value :: directive
            integer(c_size_t) :: roup_directive_clause_count
        end function roup_directive_clause_count
    end interface
end module roup_interface

Parsing Fortran Directives from Fortran

program parse_example
    use iso_c_binding
    use roup_interface
    implicit none
    
    type(c_ptr) :: directive_ptr, name_ptr
    character(len=100) :: input = "!$OMP PARALLEL PRIVATE(X)"
    character(kind=c_char), dimension(:), allocatable :: c_input
    integer :: i, n
    
    ! Convert Fortran string to C string
    n = len_trim(input)
    allocate(c_input(n+1))
    do i = 1, n
        c_input(i) = input(i:i)
    end do
    c_input(n+1) = c_null_char
    
    ! Parse directive
    directive_ptr = roup_parse_with_language(c_loc(c_input), &
                                              ROUP_LANG_FORTRAN_FREE)
    
    if (c_associated(directive_ptr)) then
        ! Get directive information
        name_ptr = roup_directive_name(directive_ptr)
        ! ... process name_ptr ...
        
        ! Clean up
        call roup_directive_free(directive_ptr)
    else
        print *, "Parse error"
    end if
    
    deallocate(c_input)
end program parse_example

Case Insensitivity

Fortran is case-insensitive, and ROUP respects this:

! All of these are equivalent
!$OMP PARALLEL PRIVATE(X)
!$omp parallel private(x)
!$Omp Parallel Private(X)

ROUP normalizes Fortran identifiers to lowercase internally while preserving the original case in the parsed output.

Common Fortran OpenMP Constructs

Parallel Regions

!$OMP PARALLEL PRIVATE(TID) SHARED(N)
    ! Parallel code
!$OMP END PARALLEL

Work-Sharing Constructs

In Fortran, use DO instead of C's for:

!$OMP DO PRIVATE(I) SCHEDULE(STATIC, 10)
    do i = 1, n
        ! Loop body
    end do
!$OMP END DO

Or combined:

!$OMP PARALLEL DO PRIVATE(I,J) REDUCTION(+:SUM)
    do i = 1, n
        sum = sum + array(i)
    end do
!$OMP END PARALLEL DO

Array Sections

Fortran array sections use different syntax than C:

!$OMP PARALLEL PRIVATE(A(1:N), B(:,1:M))
    ! Work with array sections
!$OMP END PARALLEL

Common Blocks

Fortran's THREADPRIVATE can apply to common blocks:

      COMMON /MYDATA/ X, Y, Z
!$OMP THREADPRIVATE(/MYDATA/)

Examples

See the examples/fortran/ directory for complete working examples:

• basic_parse.f90: Simple Fortran directive examples
• tutorial_basic.f90: Full C API integration tutorial

Building Fortran Programs with ROUP

Using gfortran

# Compile Fortran code
gfortran -c my_program.f90

# Link with ROUP library
gcc my_program.o -L/path/to/roup/target/release -lroup -o my_program

# Run (set LD_LIBRARY_PATH)
LD_LIBRARY_PATH=/path/to/roup/target/release ./my_program

Makefile Example

FC = gfortran
ROUP_LIB = -L../../target/release -lroup -Wl,-rpath,../../target/release

my_program: my_program.f90
	$(FC) -o $@ $< $(ROUP_LIB)

Known Limitations

⚠️ Current limitations in experimental Fortran support:

1. Continuation Syntax Requirements: Multi-line directives must use standard continuation markers

   • Fortran: Terminate continued lines with & and optionally repeat the sentinel on the next line
   • C/C++: Place a trailing \ at the end of each continued line
   • See Line Continuations for canonical examples across languages

2. End Directives: !$OMP END PARALLEL and similar end directives may not parse correctly

3. Array Sections: Complex array section syntax may have issues

4. Fixed-Form Column Rules: Strict column 1-6 sentinel placement not enforced

5. Fortran-Specific Directives: Some Fortran-only directives (e.g., WORKSHARE) may not be registered

Troubleshooting

Parse Errors

If parsing fails:

1. Check sentinel format: Use !$OMP for free-form or !$OMP/C$OMP for fixed-form
2. Verify case: While case-insensitive, ensure proper formatting
3. Check whitespace: Ensure proper spacing after sentinel
4. Use correct language mode: Specify ROUP_LANG_FORTRAN_FREE or ROUP_LANG_FORTRAN_FIXED

Directive Not Found

Some directives may not be in the registry. Check:

• Is the directive name correct? (Fortran supports both DO and FOR syntax)
• Is it a composite directive? (Use PARALLEL DO not PARALLEL + DO)

API Reference

See:

• C Tutorial - C API documentation
• API Reference - Complete API listing
• Architecture - Parser internals

Contributing

Fortran support is under active development. Contributions welcome:

• Test with real Fortran+OpenMP code
• Report parsing issues
• Add more Fortran-specific test cases
• Improve documentation

Further Reading

• OpenMP 5.2 Specification - Official OpenMP standard
• Fortran OpenMP Documentation - GCC Fortran OpenMP guide
• ISO C Binding - Fortran-C interop guide

ompparser Compatibility Layer

⚠️ Experimental Feature - This compatibility layer is under active development.

ROUP provides a drop-in compatibility layer for projects using ompparser, allowing you to switch to ROUP's expected-to-be faster, safer Rust-based parser without changing your code.

What is it?

A compatibility layer that provides:

• Same API as ompparser - no code changes needed
• Drop-in replacement via libompparser.so
• ROUP backend - expected-to-be faster, safer parsing in Rust
• Reuses ompparser methods - toString(), generateDOT(), etc. (zero duplication)

Quick Start

One-Command Build

cd compat/ompparser
./build.sh

The script will:

1. Check prerequisites (git, cmake, gcc, cargo)
2. Initialize ompparser submodule
3. Build ROUP core library
4. Build libompparser.so (size varies by build configuration)
5. Run all 46 tests

Manual Build

# 1. Initialize ompparser submodule
git submodule update --init --recursive

# 2. Build ROUP core
cd /path/to/roup
cargo build --release

# 3. Build compatibility layer
cd compat/ompparser
mkdir -p build && cd build
cmake ..
make

# 4. Run tests
ctest --output-on-failure

Usage

Drop-in Replacement

Install system-wide and use exactly like original ompparser:

# Install
cd compat/ompparser/build
sudo make install
sudo ldconfig

# Use (unchanged!)
g++ mycompiler.cpp -lompparser -o mycompiler

Code Example

Your existing ompparser code works without changes:

#include <OpenMPIR.h>
#include <iostream>

int main() {
    // Parse OpenMP directive
    OpenMPDirective* dir = parseOpenMP("omp parallel num_threads(4)", nullptr);
    
    if (dir) {
        // Use ompparser methods (all work!)
        std::cout << "Kind: " << dir->getKind() << std::endl;
        std::cout << "String: " << dir->toString() << std::endl;
        
        // Access clauses
        auto* clauses = dir->getAllClauses();
        std::cout << "Clauses: " << clauses->size() << std::endl;
        
        delete dir;
    }
    
    return 0;
}

CMake Integration

Option 1: pkg-config

find_package(PkgConfig REQUIRED)
pkg_check_modules(OMPPARSER REQUIRED ompparser)

target_link_libraries(your_app ${OMPPARSER_LIBRARIES})
target_include_directories(your_app PRIVATE ${OMPPARSER_INCLUDE_DIRS})

Option 2: Direct linking

target_link_libraries(your_app
    ${PATH_TO_ROUP}/compat/ompparser/build/libompparser.so
)

What's Included

libompparser.so

Single self-contained library with:

• ROUP parser (statically embedded) - Rust-based, safe parsing
• ompparser methods - toString, generateDOT, etc.
• Compatibility wrapper - Seamless integration layer
• Self-contained - No libroup.so dependency (system libs via libc)

Comprehensive Testing

46 tests covering:

• Basic directives: parallel, for, sections, single, task, barrier, taskwait, critical, master
• Clauses: num_threads, private, shared, reduction, schedule, if, nowait, etc.
• String generation: toString(), generatePragmaString()
• Error handling: null input, invalid directives, malformed pragmas
• Memory management: allocations, deletion, reuse
• Language modes: C, C++, Fortran via setLang()

Run tests:

cd compat/ompparser/build
ctest --output-on-failure

Architecture

Your Application (OpenMP directives to parse)
    ↓
compat_impl.cpp (~190 lines) - Minimal wrapper
    ↓
ROUP C API (roup_parse, roup_directive_kind, etc.)
    ↓
ROUP Rust Parser (safe parser core)
    ↓
Returns: OpenMPDirective with ompparser methods

Key Design:

• Reuses 90% of ompparser code (no duplication)
• Git submodule approach - automatic ompparser upgrades
• Minimal unsafe code (~60 lines, 0.9%), all at FFI boundary

Known Limitations

1. Combined Directives ⚠️

Combined directives like parallel for are currently parsed as the first directive only.

Example:

parseOpenMP("omp parallel for", nullptr)
// Returns: OMPD_parallel (should be OMPD_parallel_for)

Status: ROUP core limitation, tracked for future improvement.

Workaround: Tests document expected behavior with clear warnings.

2. Clause Parameters 🔄

Basic clause detection works, but parameter extraction not yet implemented.

Example:

parseOpenMP("omp parallel num_threads(4)", nullptr)
// Detects: num_threads clause ✅
// Extracts "4": ❌ (TODO)

Status: Planned wrapper enhancement using ROUP's clause expression API.

Documentation

Complete documentation in compat/ompparser/:

• README.md - Complete compatibility layer guide with build instructions and examples

For detailed ROUP API documentation, see API Reference.

Requirements

• Rust toolchain (for ROUP core)
• CMake 3.10+
• C++11 compiler (gcc/clang)
• Git (for submodule management)

CI/CD

The compatibility layer is tested automatically via GitHub Actions (.github/workflows/build.yml):

- Tests ROUP core (always)
- Tests compat layer (if submodule initialized)
- Verifies library builds successfully
- Validates drop-in functionality
- Checks constants synchronization (checksum validation)

FAQ

Q: Do I need to change my code?
A: No! It's a drop-in replacement with the same API.

Q: What if I don't need compat layer?
A: ROUP works perfectly standalone. The compat layer is optional.

Q: How do I get ompparser upgrades?
A: git submodule update --remote pulls latest ompparser automatically.

Q: What about performance?
A: ROUP is expected to be faster than original ompparser due to Rust optimizations.

Q: Is it stable?
A: ⚠️ Experimental stage - thoroughly tested (46 tests) but under active development.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: See Contributing Guide

API Reference

ROUP provides comprehensive APIs for Rust, C, and C++.

Rust API Documentation

The complete Rust API documentation is auto-generated from the source code using rustdoc.

→ View Rust API Documentation

Key Modules

• roup::parser - Main parsing functions

  • parse() - Parse OpenMP directive from string
  • parse_with_config() - Parse with custom configuration

• roup::ir::directive - Directive types and structures

  • DirectiveIR - Main directive structure
  • DirectiveKind - Enum of directive types

• roup::ir::clause - Clause types and data

  • Clause - Clause structure
  • ClauseKind - Enum of clause types
  • ScheduleKind, ReductionOperator, etc.

• roup::ir::types - Common types

  • Language - Source language (C, C++, Fortran)
  • SourceLocation - Position in source code

Quick Links

• Parse Functions
• Directive Types
• Clause Types

C API Reference

ROUP exports 16 C functions for FFI integration, providing a minimal C API with unsafe pointer operations only at the FFI boundary. All functions use direct C pointers (*mut OmpDirective, *mut OmpClause) following a standard malloc/free pattern.

Source: src/c_api.rs (~60 lines of unsafe code at FFI boundary, ~0.9% of file)

Lifecycle Functions

// Parse OpenMP directive from C string
OmpDirective* roup_parse(const char* input);

// Free directive (required after parsing)
void roup_directive_free(OmpDirective* directive);

// Free clause (usually not needed - owned by directive)
void roup_clause_free(OmpClause* clause);

Directive Query Functions

// Get directive kind (0=parallel, 1=for, etc.)
int32_t roup_directive_kind(const OmpDirective* directive);

// Get number of clauses
int32_t roup_directive_clause_count(const OmpDirective* directive);

// Create clause iterator
OmpClauseIterator* roup_directive_clauses_iter(const OmpDirective* directive);

Iterator Functions

// Get next clause from iterator
// Returns 1 if clause available, 0 if done
int32_t roup_clause_iterator_next(OmpClauseIterator* iter, OmpClause** out);

// Free iterator
void roup_clause_iterator_free(OmpClauseIterator* iter);

Clause Query Functions

// Get clause kind (0=num_threads, 2=private, etc.)
int32_t roup_clause_kind(const OmpClause* clause);

// Get schedule kind (0=static, 1=dynamic, etc.)
int32_t roup_clause_schedule_kind(const OmpClause* clause);

// Get reduction operator (0=+, 1=-, 2=*, etc.)
int32_t roup_clause_reduction_operator(const OmpClause* clause);

// Get default data sharing (0=shared, 1=none)
int32_t roup_clause_default_data_sharing(const OmpClause* clause);

Variable List Functions

// Get variable list from clause (e.g., private(x, y, z))
OmpStringList* roup_clause_variables(const OmpClause* clause);

// Get length of string list
int32_t roup_string_list_len(const OmpStringList* list);

// Get string at index
const char* roup_string_list_get(const OmpStringList* list, int32_t index);

// Free string list
void roup_string_list_free(OmpStringList* list);

Mapping Tables

Important: These values are defined in src/c_api.rs. The C API uses a simple subset of OpenMP clauses with straightforward integer mapping.

Directive Kinds

The C API provides roup_directive_kind() which returns an integer representing the directive type. The specific mapping depends on the parser's internal directive registry.

Common directive types (from parser):

• Parallel constructs: parallel, parallel for, parallel sections
• Work-sharing: for, sections, single, workshare
• Tasking: task, taskloop, taskgroup, taskwait
• Device: target, target data, target update, teams
• Synchronization: barrier, critical, atomic, ordered
• SIMD: simd, declare simd, distribute
• Advanced: metadirective, declare variant, assume

For a complete list of all 120+ supported directives with version compatibility, see the OpenMP Support Matrix.

Clause Kinds (Integer Discriminants)

The C API supports 12 common clause types with simple integer mapping:

Note: The C API intentionally supports a focused subset of clauses for simplicity. The Rust API supports all 92+ OpenMP 6.0 clauses.

Schedule Kinds

Default Kinds (DefaultKind enum)

Reduction Operators (ReductionOperator enum)

C++ RAII Wrappers

For modern C++17 applications, use the RAII wrappers provided in the C++ Tutorial.

Key classes:

• roup::Directive - Auto-frees directive on destruction
• roup::ClauseIterator - Auto-frees iterator on destruction
• roup::StringList - Auto-frees string list on destruction

Example:

#include "roup_wrapper.hpp"

roup::Directive dir("#pragma omp parallel for num_threads(4)");
if (dir) {
    std::cout << "Kind: " << dir.kind() << std::endl;
    std::cout << "Clauses: " << dir.clause_count() << std::endl;
}
// Automatic cleanup when dir goes out of scope

Memory Management Rules

Rust API

• Automatic - Rust's ownership system handles everything
• No manual free() needed

C API

• Manual - Must call _free() functions
• Directive: Call roup_directive_free() when done
• Iterator: Call roup_clause_iterator_free() when done
• String List: Call roup_string_list_free() when done
• Clauses: Do NOT free - owned by directive

C++ RAII API

• Automatic - RAII wrappers call _free() in destructors
• Exception-safe - cleanup happens even with exceptions

Error Handling

Rust

use roup::parser::openmp;

let parser = openmp::parser();
match parser.parse(input) {
    Ok((_, directive)) => { /* use directive */ },
    Err(e) => eprintln!("Parse error: {:?}", e),
}

C

OmpDirective* dir = roup_parse(input);
if (dir == NULL) {
    fprintf(stderr, "Parse failed\n");
    return 1;
}
// Use dir...
roup_directive_free(dir);

C++

roup::Directive dir(input);
if (!dir) {
    std::cerr << "Parse failed\n";
    return 1;
}
// Use dir...

Thread Safety

• ✅ Parsing is thread-safe - Multiple threads can call parse() simultaneously
• ✅ Read operations are thread-safe - Query functions are read-only
• ⚠️ Modification is not thread-safe - Don't mutate same directive from multiple threads
• ⚠️ Iterators are single-threaded - One iterator per thread

Performance Tips

1. Reuse parsed directives when possible
2. Avoid reparsing the same string repeatedly
3. Use iterators instead of random access
4. Batch operations to minimize FFI overhead (C/C++)
5. Profile first - parsing is usually not the bottleneck

Further Reading

• Rust API Documentation - Complete rustdoc
• C++ Tutorial - Real-world C++ examples
• GitHub Repository - Source code and examples
• Quick Start Guide - Get started in 5 minutes

OpenMP Support

ROUP provides comprehensive support for OpenMP 6.0 directives and clauses for C/C++ and Fortran.

Quick Summary

ROUP supports the vast majority of OpenMP 3.0-6.0 directives and clauses. ✅

Directive Support

Core Parallelism (15 directives)

Tasking (10 directives)

Device Offloading (12 directives)

Combined Directives (60+ forms)

ROUP supports all standard combined directives:

Parallel + Worksharing:

• parallel for
• parallel for simd
• parallel loop
• parallel sections
• parallel master
• parallel masked

Target + Parallel:

• target parallel
• target parallel for
• target parallel for simd
• target parallel loop
• target teams
• target teams distribute
• target teams distribute parallel for
• target teams distribute parallel for simd

Teams + Distribute:

• teams distribute
• teams distribute simd
• teams distribute parallel for
• teams distribute parallel for simd
• teams loop

And many more... (all 120+ combinations from OpenMP 6.0)

Meta-directives & Variants (5 directives)

Utility Directives (6 directives)

Clause Support (92 clauses)

Data-Sharing Clauses (8)

Control Clauses (15)

Device Clauses (15)

SIMD Clauses (8)

Synchronization & Memory (12)

Metadirective & Variant Clauses (5)

Miscellaneous Clauses (29)

Version Compatibility

ROUP tracks the latest OpenMP specification and is updated with each new release.

Language Support

C/C++ Syntax

#pragma omp parallel for num_threads(4) schedule(static)
for (int i = 0; i < n; i++) {
    process(i);
}

✅ Supported: All C/C++ #pragma omp directives

Fortran Syntax

!$omp parallel do schedule(dynamic)
do i = 1, n
    call process(i)
end do
!$omp end parallel do

✅ Supported: Free-form (!$omp), Fixed-form (c$omp, *$omp)
✅ Case insensitive: !$OMP, !$Omp, !$omp all work

Test Coverage

ROUP includes comprehensive automated testing:

Every directive and clause in OpenMP 6.0 has a passing test. ✅

See tests/ directory for the full test suite.

Unsupported Features

ROUP focuses on directive parsing, not runtime semantics. The following are out of scope:

❌ Runtime execution - ROUP parses directives, doesn't execute them
❌ Code transformation - No AST rewriting or code generation
❌ Semantic validation - Doesn't check if directives make logical sense
❌ Context analysis - Doesn't validate directive placement in code

Use ROUP for:

• ✅ Static analysis tools
• ✅ Code documentation generators
• ✅ IDE syntax highlighting
• ✅ Linting and code quality checks
• ✅ Migration tools
• ✅ Research prototypes

Don't use ROUP for:

• ❌ Compiling OpenMP to executables (use GCC/Clang)
• ❌ Runtime task scheduling (use OpenMP runtime)
• ❌ Performance profiling (use performance tools)

Implementation Status

Future Additions

Tracking future OpenMP specifications:

ROUP will be updated as new OpenMP versions are released.

References

• OpenMP 6.0 Specification - Official spec
• OpenMP.org - OpenMP Architecture Review Board
• ROUP GitHub - Source code and tests

Summary

ROUP provides OpenMP 3.0-6.0 parsing support:

• ✅ 95 directives (core, combined, and meta-directives)
• ✅ 91 clause types (data-sharing, control, device, SIMD, sync, etc.)
• ✅ C/C++/Fortran syntax support
• ✅ 352 automated tests (comprehensive directive/clause coverage)
• ✅ Type-safe Rust API + C FFI
• ✅ Latest spec (OpenMP 6.0, 2024)

⚠️ Experimental - for research, education, and prototype tooling. Not yet production-ready. 🧪

OpenMP 6.0 Directives and Clauses

This comprehensive reference catalogue documents all OpenMP 6.0 keywords from the OpenMP Application Programming Interface Version 6.0 specification.

Purpose

This document serves as a complete keyword inventory for development and reference. Each entry includes:

• Specification section and page numbers
• Categorization and properties
• No duplication - each keyword appears once

Coverage

• 66 Directives/Constructs - All executable, declarative, and meta directives
• 125 Clauses - All clause keywords
• Modifiers - Map-type, dependence-type, schedule, and other modifiers
• Keywords & Values - Memory orders, atomic operations, schedule types, allocators, and more
• Reduction Operators - All supported reduction operations
• Special Identifiers - Reserved locators, device identifiers, and constants

Directives and Constructs

• allocate (Section 8.5; pp. 341–342; category: declarative; association: explicit; properties: pure)
• allocators (Section 8.7; category: executable; association: block : allocator; properties: default)
• assume (Section 10.6.3; category: informational; association: block; properties: pure)
• assumes (Section 10.6.2; p. 399; category: informational; association: unassociated; properties: pure)
• atomic (Section 17.8.5; pp. 525–528; category: executable; association: block : atomic; properties: mutual-exclusion, order-concurrent-nestable, simdizable)
• barrier (Section 17.3.1; pp. 506–508; category: executable; association: unassociated; properties: team-executed)
• begin assumes (Section 10.6.4; p. 399; category: informational; association: delimited; properties: default)
• begin declare_target (Section 9.9.2; p. 380; category: declarative; association: delimited; properties: declare-target, device, variant-generating)
• begin declare_variant (Section 9.6.5; p. 367; category: declarative; association: delimited; properties: default)
• cancel (Section 18.2; pp. 551–554; category: executable; association: unassociated; properties: default)
• cancellation_point (Section 18.3; pp. 555–556; category: executable; association: unassociated; properties: default)
• critical (Section 17.2; pp. 504–505; category: executable; association: block; properties: mutual-exclusion, thread-limiting, thread-exclusive)
• declare_induction (Section 7.6.17; pp. 294–295; category: declarative; association: unassociated; properties: pure)
• declare_mapper (Section 7.9.10; pp. 324–327; category: declarative; association: unassociated; properties: pure)
• declare_reduction (Section 7.6.14; pp. 291–292; category: declarative; association: unassociated; properties: pure)
• declare_simd (Section 9.8; pp. 372–373; category: declarative; association: declaration; properties: pure, variant-generating)
• declare_target (Section 9.9.1; pp. 377–379; category: declarative; association: explicit; properties: declare-target, device, pure, variant-generating)
• declare_variant (Section 9.6.4; pp. 365–366; category: declarative; association: declaration; properties: pure)
• depobj (Section 17.9.3; p. 536; category: executable; association: unassociated; properties: default)
• dispatch (Section 9.7; pp. 368–369; category: executable; association: block : function-dispatch; properties: context-matching)
• distribute (Section 13.7; pp. 451–452; category: executable; association: loop nest; properties: SIMD-partitionable, teams-nestable, work-distribution, partitioned)
• do (Section 13.6.2; p. 448; category: executable; association: loop nest; properties: work-distribution, team-executed, partitioned, SIMD-partitionable, worksharing, worksharing-loop, cancellable, context-matching)
• error (Section 10.1; p. 383; category: utility; association: unassociated; properties: pure)
• flush (Section 17.8.6; pp. 529–535; category: executable; association: unassociated; properties: default)
• for (Section 13.6.1; p. 447; category: executable; association: loop nest; properties: work-distribution, team-executed, partitioned, SIMD-partitionable, worksharing, worksharing-loop, cancellable, context-matching)
• fuse (Section 11.3; p. 405; category: executable; association: loop sequence; properties: loop-transforming, order-concurrent-nestable, pure, simdizable, teams-nestable)
• groupprivate (Section 7.13; pp. 332–333; category: declarative; association: explicit; properties: pure)
• interchange (Section 11.4; p. 406; category: executable; association: loop nest; properties: loop-transforming, nonrectangular-compatible, order-concurrent-nestable, pure, simdizable, teams-nestable)
• interop (Section 16.1; p. 499; category: executable; association: unassociated; properties: device)
• loop (Section 13.8; p. 454; category: executable; association: loop nest; properties: order-concurrent-nestable, partitioned, simdizable, team-executed, teams-nestable, work-distribution, worksharing)
• masked (Section 12.5; p. 433; category: executable; association: block; properties: thread-limiting, thread-selecting)
• begin metadirective (Section 9.4.4; p. 327; category: meta; association: delimited; properties: pure)
• metadirective (Section 9.4.3; p. 327; category: meta; association: unassociated; properties: pure)
• nothing (Section 10.7; pp. 400–402; category: utility; association: unassociated; properties: pure, loop-transforming)
• ordered (Section 17.10.2; pp. 546–547; category: executable; association: block; properties: mutual-exclusion, simdizable, thread-limiting, thread-exclusive)
• parallel (Section 12.1; pp. 415–418; category: executable; association: block; properties: cancellable, context-matching, order-concurrent-nestable, parallelism-generating, team-generating, teams-nestable, thread-limiting)
• requires (Section 10.5; p. 386; category: informational; association: unassociated; properties: default)
• reverse (Section 11.5; p. 407; category: executable; association: loop nest; properties: generally-composable, loop-transforming, order-concurrent-nestable, pure, simdizable, teams-nestable)
• scan (Section 7.7; pp. 297–299; category: subsidiary; association: separating; properties: pure)
• scope (Section 13.2; p. 437; category: executable; association: block; properties: work-distribution, team-executed, worksharing, thread-limiting)
• section (Section 13.3.1; p. 439; category: subsidiary; association: separating; properties: default)
• sections (Section 13.3; p. 438; category: executable; association: block; properties: work-distribution, team-executed, partitioned, worksharing, thread-limiting, cancellable)
• simd (Section 12.4; p. 430; category: executable; association: loop nest; properties: context-matching, order-concurrent-nestable, parallelism-generating, pure, simdizable)
• single (Section 13.1; p. 436; category: executable; association: block; properties: work-distribution, team-executed, partitioned, worksharing, thread-limiting, thread-selecting)
• split (Section 11.6; p. 408; category: executable; association: loop nest; properties: generally-composable, loop-transforming, order-concurrent-nestable, pure, simdizable, teams-nestable)
• stripe (Section 11.7; p. 410; category: executable; association: loop nest; properties: loop-transforming, order-concurrent-nestable, pure, simdizable, teams-nestable)
• target (Section 15.8; pp. 491–495; category: executable; association: block; properties: parallelism-generating, team-generating, thread-limiting, exception-aborting, task-generating, device, device-affecting, data-mapping, map-entering, map-exiting, context-matching)
• target_data (Section 15.7; pp. 489–490; category: executable; association: block; properties: device, device-affecting, data-mapping, map-entering, map-exiting, parallelism-generating, sharing-task, task-generating)
• target_enter_data (Section 15.5; pp. 485–486; category: executable; association: unassociated; properties: parallelism-generating, task-generating, device, device-affecting, data-mapping, map-entering)
• target_exit_data (Section 15.6; pp. 487–488; category: executable; association: unassociated; properties: parallelism-generating, task-generating, device, device-affecting, data-mapping, map-exiting)
• target_update (Section 15.9; pp. 496–498; category: executable; association: unassociated; properties: parallelism-generating, task-generating, device, device-affecting)
• task (Section 14.1; pp. 457–459; category: executable; association: block; properties: parallelism-generating, thread-limiting, task-generating)
• task_iteration (Section 14.2.3; p. 465; category: subsidiary; association: unassociated; properties: default)
• taskgraph (Section 14.3; pp. 466–468; category: executable; association: block; properties: default)
• taskgroup (Section 17.4; p. 509; category: executable; association: block; properties: cancellable)
• taskloop (Section 14.2; pp. 460–462; category: executable; association: loop nest; properties: parallelism-generating, SIMD-partitionable, task-generating)
• taskwait (Section 17.5; pp. 510–511; category: executable; association: unassociated; properties: default)
• taskyield (Section 14.12; pp. 477–480; category: executable; association: unassociated; properties: default)
• teams (Section 12.2; pp. 425–427; category: executable; association: block; properties: parallelism-generating, team-generating, thread-limiting, context-matching)
• threadprivate (Section 7.3; pp. 246–253; category: declarative; association: explicit; properties: pure)
• tile (Section 11.8; p. 411; category: executable; association: loop nest; properties: loop-transforming, order-concurrent-nestable, pure, simdizable, teams-nestable)
• unroll (Section 11.9; p. 412; category: executable; association: loop nest; properties: generally-composable, loop-transforming, order-concurrent-nestable, pure, simdizable, teams-nestable)
• workdistribute (Section 13.5; pp. 443–446; category: executable; association: block; properties: work-distribution, partitioned)
• workshare (Section 13.4; pp. 440–442; category: executable; association: block; properties: work-distribution, team-executed, partitioned, worksharing)

Clauses

• absent (Section 10.6.1.1; p. 394)
• acq_rel (Section 17.8.1.1; p. 515)
• acquire (Section 17.8.1.2; p. 516)
• adjust_args (Section 9.6.2; pp. 362–363)
• affinity (Section 14.10; p. 475)
• align (Section 8.3; p. 340)
• aligned (Section 7.12; p. 331)
• allocate (Section 8.6; pp. 343–345)
• allocator (Section 8.4; p. 340)
• append_args (Section 9.6.3; p. 364)
• apply (Section 11.1; pp. 403–404)
• at (Section 10.2; p. 383)
• atomic_default_mem_order (Section 10.5.1.1; p. 387)
• bind (Section 13.8.1; pp. 455–456)
• capture (Section 17.8.3.1; p. 521)
• collapse (Section 6.4.5; p. 236)
• collector (Section 7.6.19; p. 296)
• combiner (Section 7.6.15; p. 292)
• compare (Section 17.8.3.2; p. 522)
• contains (Section 10.6.1.2; p. 394)
• copyin (Section 7.8.1; p. 302)
• copyprivate (Section 7.8.2; pp. 303–309)
• counts (Section 11.6.1; p. 409)
• default (Section 7.5.1; p. 254)
• defaultmap (Section 7.9.9; pp. 322–323)
• depend (Section 17.9.5; pp. 538–540)
• destroy (Section 5.7; pp. 213–235)
• detach (Section 14.11; p. 476)
• device (Section 15.2; p. 482)
• device_safesync (Section 10.5.1.7; p. 393; properties: required, unique Members:)
• device_type (Section 15.1; p. 481)
• dist_schedule (Section 13.7.1; p. 453)
• doacross (Section 17.9.7; pp. 542–544)
• dynamic_allocators (Section 10.5.1.2; p. 388)
• enter (Section 7.9.7; p. 320)
• exclusive (Section 7.7.2; p. 300)
• fail (Section 17.8.3.3; p. 522)
• filter (Section 12.5.1; pp. 434–435)
• final (Section 14.7; p. 472)
• firstprivate (Section 7.5.4; pp. 258–259)
• from (Section 7.10.2; p. 329)
• full (Section 11.9.1; p. 413)
• grainsize (Section 14.2.1; p. 463)
• graph_id (Section 14.3.1; p. 468)
• graph_reset (Section 14.3.2; p. 469)
• has_device_addr (Section 7.5.9; p. 268)
• hint (Section 17.1; p. 503)
• holds (Section 10.6.1.3; p. 395)
• if (Section 5.5; p. 210)
• in_reduction (Section 7.6.12; p. 287)
• inbranch (Section 9.8.1.1; p. 374)
• inclusive (Section 7.7.1; p. 299)
• indirect (Section 9.9.3; pp. 381–382)
• induction (Section 7.6.13; pp. 288–290)
• inductor (Section 7.6.18; p. 296)
• init (Section 5.6; pp. 211–212)
• init_complete (Section 7.7.3; p. 301)
• initializer (Section 7.6.16; p. 293)
• interop (Section 9.7.1; p. 370)
• is_device_ptr (Section 7.5.7; p. 266)
• lastprivate (Section 7.5.5; pp. 260–262)
• linear (Section 7.5.6; pp. 263–265)
• link (Section 7.9.8; p. 321)
• local (Section 7.14; pp. 334–339)
• looprange (Section 6.4.7; pp. 238–245)
• map (Section 7.9.6; pp. 310–319)
• match (Section 9.6.1; p. 361)
• memscope (Section 17.8.4; p. 524)
• mergeable (Section 14.5; p. 470)
• message (Section 10.3; p. 384)
• no_openmp (Section 10.6.1.4; p. 396)
• no_openmp_constructs (Section 10.6.1.5; p. 396)
• no_openmp_routines (Section 10.6.1.6; p. 397)
• no_parallelism (Section 10.6.1.7; p. 398)
• nocontext (Section 9.7.3; p. 371)
• nogroup (Section 17.7; p. 514; properties: exclusive, unique Members:)
• nontemporal (Section 12.4.1; p. 431)
• notinbranch (Section 9.8.1.2; pp. 375–376)
• novariants (Section 9.7.2; p. 370)
• nowait (Section 17.6; pp. 512–513)
• num_tasks (Section 14.2.2; p. 464)
• num_teams (Section 12.2.1; p. 427)
• num_threads (Section 12.1.2; pp. 419–422)
• order (Section 12.3; pp. 428–429)
• ordered (Section 6.4.6; p. 237)
• otherwise (Section 9.4.2; pp. 357–360; properties: pure)
• partial (Section 11.9.2; p. 414)
• permutation (Section 11.4.1; p. 407)
• priority (Section 14.9; p. 474)
• private (Section 7.5.3; pp. 256–257)
• proc_bind (Section 12.1.4; p. 423)
• read (Section 17.8.2.1; p. 519)
• reduction (Section 7.6.10; pp. 283–285)
• relaxed (Section 17.8.1.3; p. 516)
• release (Section 17.8.1.4; p. 517)
• replayable (Section 14.6; p. 471)
• reverse_offload (Section 10.5.1.3; p. 389)
• safelen (Section 12.4.2; p. 431)
• safesync (Section 12.1.5; p. 424)
• schedule (Section 13.6.3; pp. 449–450)
• self_maps (Section 10.5.1.6; p. 392)
• seq_cst (Section 17.8.1.5; p. 518; properties: exclusive, unique Members:)
• severity (Section 10.4; p. 385)
• shared (Section 7.5.2; p. 255)
• simd (Section 17.10.3.2; pp. 549–550; properties: exclusive, required, unique Members:)
• simdlen (Section 12.4.3; p. 432)
• sizes (Section 11.2; p. 404)
• task_reduction (Section 7.6.11; p. 286)
• thread_limit (Section 15.3; pp. 483–484)
• threads (Section 17.10.3.1; p. 548)
• threadset (Section 14.8; p. 473)
• to (Section 7.10.1; p. 328)
• transparent (Section 17.9.6; p. 541)
• unified_address (Section 10.5.1.4; p. 390)
• unified_shared_memory (Section 10.5.1.5; p. 391)
• uniform (Section 7.11; p. 330)
• untied (Section 14.4; p. 470)
• update (Section 17.9.4; p. 537)
• use (Section 16.1.2; pp. 500–502)
• use_device_addr (Section 7.5.10; pp. 269–282)
• use_device_ptr (Section 7.5.8; p. 267)
• uses_allocators (Section 8.8; pp. 346–355)
• weak (Section 17.8.3.4; p. 523)
• when (Section 9.4.1; p. 356)
• write (Section 17.8.2.3; p. 520; properties: unique Members:)

Modifiers

Modifiers are keywords that modify the behavior of clauses. They appear as part of clause syntax to refine clause semantics.

Map-Type Modifiers

• storage (Section 7.9.1; p. 305; map-type modifier; default value)
• to (Section 7.9.1; p. 305; map-type modifier; map-entering, assigning)
• from (Section 7.9.1; p. 305; map-type modifier; map-exiting, assigning)
• tofrom (Section 7.9.1; p. 305; map-type modifier; map-entering, map-exiting, assigning)
• alloc (Section 7.9.1; p. 305; map-type modifier; alias for storage on map-entering constructs)
• release (Section 7.9.1; p. 305; map-type modifier; alias for storage on map-exiting constructs)
• delete (Section 7.9.1; p. 305; map-type modifier; used with delete-modifier)

Task-Dependence-Type Modifiers

• in (Section 17.9.1; p. 535; task-dependence-type modifier; input dependence)
• out (Section 17.9.1; p. 535; task-dependence-type modifier; output dependence)
• inout (Section 17.9.1; p. 535; task-dependence-type modifier; input-output dependence)
• inoutset (Section 17.9.1; p. 535; task-dependence-type modifier; inout with set semantics)
• mutexinoutset (Section 17.9.1; p. 535; task-dependence-type modifier; mutual exclusion inout)
• depobj (Section 17.9.1; p. 535; task-dependence-type modifier; depend object)

Schedule Modifiers

• monotonic (Section 13.6.3; p. 449; ordering-modifier for schedule clause)
• nonmonotonic (Section 13.6.3; p. 449; ordering-modifier for schedule clause)
• simd (Section 13.6.3; p. 449; chunk-modifier for schedule clause)

Reduction and Induction Modifiers

• reduction-identifier (Section 7.6.9; p. 282; modifier specifying reduction operation)
• iterator (Section 5.2.6; p. 200; modifier for creating iterator expressions)

Other Clause Modifiers

• ref (Section 7.9.5; ref-modifier for map clause; indicates referencing variable)
• mapper (Section 7.9.4; mapper-modifier for map clause; specifies custom mapper)
• allocator-simple-modifier (Section 8.6; allocator modifier; simple allocator specification)
• allocator-complex-modifier (Section 8.6; allocator modifier; complex allocator specification)
• prefer-type (Section 16.1.3; p. 501; prefer-type modifier for interop clause)
• directive-name-modifier (Section 5.4; p. 204; conditional modifier using directive name)

Map Clause Modifiers

• always (Section 7.9.6; always-modifier; forces data transfer)
• close (Section 7.9.6; close-modifier; allocates in fastest memory)
• present (Section 7.9.6; present-modifier; data must be present)
• self (Section 7.9.6; self-modifier; for device-host data mapping)

Lastprivate Modifiers

• conditional (Section 7.5.5; p. 261; modifier for lastprivate clause; conditional assignment)

Original-Sharing Modifiers

• original (Section 7.6.10; original-sharing-modifier; preserves original data-sharing)

Keywords and Values

Keywords and values used as arguments to clauses and directives.

Memory Order Keywords

• seq_cst (Section 17.8.1.5; p. 518; sequentially consistent memory ordering)
• acq_rel (Section 17.8.1.1; p. 515; acquire-release memory ordering)
• acquire (Section 17.8.1.2; p. 516; acquire memory ordering)
• release (Section 17.8.1.4; p. 517; release memory ordering)
• relaxed (Section 17.8.1.3; p. 516; relaxed memory ordering)

Atomic Operation Keywords

• read (Section 17.8.2.1; p. 519; atomic read operation)
• write (Section 17.8.2.3; p. 520; atomic write operation)
• update (Section 17.8.2.2; atomic update operation)
• capture (Section 17.8.3.1; p. 521; atomic capture operation)
• compare (Section 17.8.3.2; p. 522; atomic compare operation)
• weak (Section 17.8.3.4; p. 523; weak compare semantics)
• fail (Section 17.8.3.3; fail memory order for atomic compare)

Schedule Types

• static (Section 13.6.3; p. 449; static loop schedule)
• dynamic (Section 13.6.3; p. 449; dynamic loop schedule)
• guided (Section 13.6.3; p. 449; guided loop schedule)
• auto (Section 13.6.3; p. 449; implementation-defined loop schedule)
• runtime (Section 13.6.3; p. 449; runtime-determined loop schedule)

Proc_bind Values

• primary (Section 12.1.4; p. 423; bind to primary thread's place)
• close (Section 12.1.4; p. 423; bind close to parent thread)
• spread (Section 12.1.4; p. 423; spread across places)
• master (deprecated; use primary instead)

Order Values

• concurrent (Section 12.3; p. 428; concurrent execution ordering)
• reproducible (Section 12.3; p. 428; reproducible ordering)
• unconstrained (Section 12.3; p. 428; unconstrained ordering)

Device-Type Values

• host (Section 15.1; p. 481; host device type)
• nohost (Section 15.1; p. 481; non-host device type)
• any (Section 15.1; p. 481; any device type)

Bind Values

• thread (Section 13.8.1; p. 455; bind to thread)
• parallel (Section 13.8.1; p. 455; bind to parallel region)
• teams (Section 13.8.1; p. 455; bind to teams region)

Default Values

• shared (Section 7.5.1; p. 254; default shared data-sharing)
• private (Section 7.5.1; p. 254; default private data-sharing)
• firstprivate (Section 7.5.1; p. 254; default firstprivate data-sharing)
• none (Section 7.5.1; p. 254; no default data-sharing)

Error Directive Values

• compilation (Section 10.2; at clause value; error at compilation time)
• execution (Section 10.2; at clause value; error at execution time)
• fatal (Section 10.4; p. 385; severity clause value; fatal error)
• warning (Section 10.4; p. 385; severity clause value; warning)

Defaultmap Values

• alloc (Section 7.9.9; p. 322; defaultmap behavior)
• to (Section 7.9.9; p. 322; defaultmap behavior)
• from (Section 7.9.9; p. 322; defaultmap behavior)
• tofrom (Section 7.9.9; p. 322; defaultmap behavior)
• firstprivate (Section 7.9.9; p. 322; defaultmap behavior)
• none (Section 7.9.9; p. 322; defaultmap behavior)
• default (Section 7.9.9; p. 322; defaultmap behavior)
• present (Section 7.9.9; p. 322; defaultmap behavior)

Variable Categories (for defaultmap)

• scalar (Section 7.9.9; p. 322; scalar variable category)
• aggregate (Section 7.9.9; p. 322; aggregate variable category)
• allocatable (Section 7.9.9; p. 322; allocatable variable category)
• pointer (Section 7.9.9; p. 322; pointer variable category)

Predefined Allocators

OpenMP defines several predefined memory allocators for different memory spaces.

Standard Allocators

• omp_default_mem_alloc (Section 8.2; p. 336; default memory allocator)
• omp_large_cap_mem_alloc (Section 8.2; p. 336; large capacity memory allocator)
• omp_const_mem_alloc (Section 8.2; p. 336; constant memory allocator)
• omp_high_bw_mem_alloc (Section 8.2; p. 336; high bandwidth memory allocator)
• omp_low_lat_mem_alloc (Section 8.2; p. 336; low latency memory allocator)
• omp_cgroup_mem_alloc (Section 8.2; p. 336; contention group memory allocator)
• omp_pteam_mem_alloc (Section 8.2; p. 336; parallel team memory allocator)
• omp_thread_mem_alloc (Section 8.2; p. 336; thread-private memory allocator)

Special Allocator Values

• omp_null_allocator (Section 8.2; p. 336; null allocator value)

Allocator Traits

• sync_hint (Section 8.2; p. 336; allocator trait; contended, uncontended, serialized, private)
• alignment (Section 8.2; p. 336; allocator trait; byte alignment)
• access (Section 8.2; p. 336; allocator trait; all, memspace, device, cgroup, pteam, thread)
• pool_size (Section 8.2; p. 336; allocator trait; pool size limit)
• fallback (Section 8.2; p. 336; allocator trait; default_mem_fb, null_fb, abort_fb, allocator_fb)
• fb_data (Section 8.2; p. 336; allocator trait; fallback allocator handle)
• pinned (Section 8.2; p. 336; allocator trait; true, false)
• partition (Section 8.2; p. 336; allocator trait; environment, nearest, blocked, interleaved, partitioner)

Reserved Locators

Reserved locators are special OpenMP identifiers representing system storage.

• omp_all_memory (Section 5.2.2; p. 195; reserved locator representing all memory)

Reduction Operators

Reduction operators used with reduction clauses.

Arithmetic Operators

• + (Section 7.6.3; addition reduction)
• - (Section 7.6.3; subtraction reduction)
• * (Section 7.6.3; multiplication reduction)

Bitwise Operators

• & (Section 7.6.3; bitwise AND reduction)
• | (Section 7.6.3; bitwise OR reduction)
• ^ (Section 7.6.3; bitwise XOR reduction)

Logical Operators

• && (Section 7.6.3; logical AND reduction)
• || (Section 7.6.3; logical OR reduction)

Min/Max Operators

• min (Section 7.6.3; minimum reduction)
• max (Section 7.6.3; maximum reduction)

Language-Specific Operators

• .eqv. (Fortran; Section 7.6.3; logical equivalence reduction)
• .neqv. (Fortran; Section 7.6.3; logical non-equivalence reduction)
• .and. (Fortran; Section 7.6.3; logical AND reduction)
• .or. (Fortran; Section 7.6.3; logical OR reduction)
• iand (Fortran; Section 7.6.3; bitwise AND reduction)
• ior (Fortran; Section 7.6.3; bitwise OR reduction)
• ieor (Fortran; Section 7.6.3; bitwise XOR reduction)

Special Constants and Identifiers

Device Identifiers

• omp_invalid_device (Section 15.2; invalid device number)
• omp_initial_device (Section 15.2; initial device identifier)

Interop Type Identifiers

• targetsync (Section 16.1.2; p. 500; target synchronization interop type)
• target (Section 16.1.2; p. 500; target interop type)

Doacross Keywords

• source (Section 17.9.7; p. 543; doacross source)
• sink (Section 17.9.7; p. 543; doacross sink)
• source_omp_cur_iteration (Section 17.9.7; p. 543; current iteration source)

OpenMP 6.0 Directive–Clause Components

For each OpenMP 6.0 directive or construct, this section lists every clause permitted by the specification. Clause entries include their specification metadata as well as the argument and modifier tables transcribed verbatim from the standard to preserve exact semantics.

allocate (Section 8.5; pp. 341–342; category: declarative; association: explicit; properties: pure)

Clause align (Section 8.3; p. 340)

Permitted on directives: allocate.

Arguments

Name Type Properties
alignment expression of integer
type
constant, positive

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause allocator (Section 8.4)

Permitted on directives: allocate.

Arguments

Name Type Properties
allocator expression of allocator_-
handle type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

allocators (Section 8.7; category: executable; association: block : allocator; properties: default)

Clause allocate (Section 8.6; pp. 343–345)

Permitted on directives: allocators, distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskgroup, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
allocator-simple-
modifier
list expression of OpenMP allo-
cator_handle type
exclusive, unique
allocator-complex-
modifier
list Complex, name:
allocator

assume (Section 10.6.3; category: informational; association: block; properties: pure)

Clause absent (Section 10.6.1.1; p. 394)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
directive-name-list list of directive-name list
item type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause contains (Section 10.6.1.2)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
directive-name-list list of directive-name list
item type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause holds (Section 10.6.1.3; p. 395)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
hold-expr expression of OpenMP
logical type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp (Section 10.6.1.4; p. 396)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp_constructs (Section 10.6.1.5)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp_routines (Section 10.6.1.6; p. 397)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_parallelism (Section 10.6.1.7; p. 398)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

assumes (Section 10.6.2; p. 399; category: informational; association: unassociated; properties: pure)

Clause absent (Section 10.6.1.1; p. 394)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
directive-name-list list of directive-name list
item type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause contains (Section 10.6.1.2)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
directive-name-list list of directive-name list
item type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause holds (Section 10.6.1.3; p. 395)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
hold-expr expression of OpenMP
logical type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp (Section 10.6.1.4; p. 396)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp_constructs (Section 10.6.1.5)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp_routines (Section 10.6.1.6; p. 397)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_parallelism (Section 10.6.1.7; p. 398)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

atomic (Section 17.8.5; pp. 525–528; category: executable; association: block : atomic; properties: mutual-exclusion, order-)

Clause acq_rel (Section 17.8.1.1; p. 515)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use-semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause acquire (Section 17.8.1.2; p. 516)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause capture (Section 17.8.3.1; p. 521)

Permitted on directives: atomic.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause compare (Section 17.8.3.2; p. 522)

Permitted on directives: atomic.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause fail (Section 17.8.3.3)

Permitted on directives: atomic.

Arguments

Name Type Properties
memorder Keyword:acquire,
relaxed, seq_cst
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause hint (Section 17.1; p. 503)

Permitted on directives: atomic, critical.

Arguments

Name Type Properties
hint-expr expression of sync_hint
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause memscope (Section 17.8.4; p. 524)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
scope-specifier Keyword:all,
cgroup,device
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause read (Section 17.8.2.1; p. 519)

Permitted on directives: atomic.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause relaxed (Section 17.8.1.3)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause release (Section 17.8.1.4; p. 517)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause seq_cst (Section 17.8.1.5; p. 518; properties: exclusive, unique Members:)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause weak (Section 17.8.3.4; p. 523)

Permitted on directives: atomic.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause write (Section 17.8.2.3; p. 520; properties: unique Members:)

Permitted on directives: atomic.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

barrier (Section 17.3.1; pp. 506–508; category: executable; association: unassociated; properties: team-executed)

No clauses are defined for this directive in the specification.

begin assumes (Section 10.6.4; category: informational; association: delimited; properties: default)

Clause absent (Section 10.6.1.1; p. 394)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
directive-name-list list of directive-name list
item type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause contains (Section 10.6.1.2)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
directive-name-list list of directive-name list
item type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause holds (Section 10.6.1.3; p. 395)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
hold-expr expression of OpenMP
logical type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp (Section 10.6.1.4; p. 396)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp_constructs (Section 10.6.1.5)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_openmp_routines (Section 10.6.1.6; p. 397)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause no_parallelism (Section 10.6.1.7; p. 398)

Permitted on directives: assume, assumes, begin assumes.

Arguments

Name Type Properties
can_assume expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

begin declare_target (Section 9.9.2; p. 380; category: declarative; association: delimited; properties: declare-target, device,)

Clause device_type (Section 15.1; p. 481)

Permitted on directives: begin declare_target, declare_target, groupprivate, target.

Arguments

Name Type Properties
device-type-description Keyword:any,host,
nohost
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause indirect (Section 9.9.3; pp. 381–382)

Permitted on directives: begin declare_target, declare_target.

Arguments

Name Type Properties
invoked-by-fptr expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

begin declare_variant (Section 9.6.5; p. 367; category: declarative; association: delimited; properties: default)

Clause match (Section 9.6.1; p. 361)

Permitted on directives: begin declare_variant, declare_variant.

Arguments

Name Type Properties
context-selector An OpenMP context-
selector-specification
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

cancel (Section 18.2; pp. 551–554; category: executable; association: unassociated; properties: default)

Clause if (Section 5.5; p. 210)

Permitted on directives: cancel, parallel, simd, target, target_data, target_enter_data, target_exit_data, target_update, task, task_iteration, taskgraph, taskloop, teams.

Arguments

Name Type Properties
if-expression expression of OpenMP
logical type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

cancellation_point (Section 18.3; pp. 555–964; category: executable; association: unassociated; properties: default)

No clauses are defined for this directive in the specification.

critical (Section 17.2; pp. 504–505; category: executable; association: block; properties: mutual-exclusion, thread-)

Clause hint (Section 17.1; p. 503)

Permitted on directives: atomic, critical.

Arguments

Name Type Properties
hint-expr expression of sync_hint
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

declare_induction (Section 7.6.17; pp. 294–295; category: declarative; association: unassociated; properties: pure)

Clause collector (Section 7.6.19)

Permitted on directives: declare_induction.

Arguments

Name Type Properties
collector-expr expression of collector
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause inductor (Section 7.6.18; p. 296)

Permitted on directives: declare_induction.

Arguments

Name Type Properties
inductor-expr expression of inductor
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

declare_mapper (Section 7.9.10; pp. 324–327; category: declarative; association: unassociated; properties: pure)

Clause map (Section 7.9.6; pp. 310–319)

Permitted on directives: declare_mapper, target, target_data, target_enter_data, target_exit_data.

Arguments

Name Type Properties
locator-list list of locator list item
type
default

Modifiers

Name Modifies Type Properties
always-modifier locator-list Keyword:always map-type-
modifying
close-modifier locator-list Keyword:close map-type-
modifying
present-modifier locator-list Keyword:present map-type-
modifying
self-modifier locator-list Keyword:self map-type-
modifying
ref-modifier all arguments Keyword:ref_ptee,
ref_ptr,ref_ptr_ptee
unique
delete-modifier locator-list Keyword:delete map-type-
modifying
mapper locator-list Complex, name:mapper

declare_reduction (Section 7.6.14; pp. 291–292; category: declarative; association: unassociated; properties: pure)

Clause combiner (Section 7.6.15)

Permitted on directives: declare_reduction.

Arguments

Name Type Properties
combiner-expr expression of combiner
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause initializer (Section 7.6.16; p. 293)

Permitted on directives: declare_reduction.

Arguments

Name Type Properties
initializer-expr expression of initializer
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

declare_simd (Section 9.8; pp. 372–373; category: declarative; association: declaration; properties: pure, variant-generating)

Clause aligned (Section 7.12; p. 331)

Permitted on directives: declare_simd, simd.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
alignment list OpenMP integer expression positive, region
invariant, ultimate,
unique
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause inbranch (Section 9.8.1.1; p. 374)

Permitted on directives: declare_simd.

Arguments

Name Type Properties
inbranch expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause linear (Section 7.5.6; pp. 263–265)

Permitted on directives: declare_simd, do, for, simd.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
step-simple-
modifier
list OpenMP integer expression exclusive, region-
invariant, unique
step-complex-
modifier
list Complex, name:step

Clause notinbranch (Section 9.8.1.2; pp. 375–376)

Permitted on directives: declare_simd.

Arguments

Name Type Properties
notinbranch expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause simdlen (Section 12.4.3; p. 432)

Permitted on directives: declare_simd, simd.

Arguments

Name Type Properties
length expression of integer
type
positive, constant

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause uniform (Section 7.11; p. 330)

Permitted on directives: declare_simd.

Arguments

Name Type Properties
parameter-list list of parameter list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

declare_target (Section 9.9.1; pp. 377–379; category: declarative; association: explicit; properties: declare-target, device,)

Clause device_type (Section 15.1; p. 481)

Permitted on directives: begin declare_target, declare_target, groupprivate, target.

Arguments

Name Type Properties
device-type-description Keyword:any,host,
nohost
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause enter (Section 7.9.7; p. 320)

Permitted on directives: declare_target.

Arguments

Name Type Properties
list list of extended list item
type
default

Modifiers

Name Modifies Type Properties
automap-modifier list Keyword:automap default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause indirect (Section 9.9.3; pp. 381–382)

Permitted on directives: begin declare_target, declare_target.

Arguments

Name Type Properties
invoked-by-fptr expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause link (Section 7.9.8; p. 321)

Permitted on directives: declare_target.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause local (Section 7.14; pp. 334–339)

Permitted on directives: declare_target.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

declare_variant (Section 9.6.4; pp. 365–366; category: declarative; association: declaration; properties: pure)

Clause adjust_args (Section 9.6.2; pp. 362–363)

Permitted on directives: declare_variant.

Arguments

Name Type Properties
parameter-list list of parameter list item
type
default

Modifiers

Name Modifies Type Properties
adjust-op parameter-list Keyword:
need_device_addr,
need_device_ptr,
nothing
required
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause append_args (Section 9.6.3; p. 364)

Permitted on directives: declare_variant.

Arguments

Name Type Properties
append-op-list list of OpenMP opera-
tion list item type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause match (Section 9.6.1; p. 361)

Permitted on directives: begin declare_variant, declare_variant.

Arguments

Name Type Properties
context-selector An OpenMP context-
selector-specification
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

depobj (Section 17.9.3; p. 536; category: executable; association: unassociated; properties: default)

Clause destroy (Section 5.7; pp. 213–235)

Permitted on directives: depobj, interop.

Arguments

Name Type Properties
destroy-var variable of OpenMP
variable type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause init (Section 5.6; pp. 211–212)

Permitted on directives: depobj, interop.

Arguments

Name Type Properties
init-var variable of OpenMP
type
default

Modifiers

Name Modifies Type Properties
prefer-type init-var Complex, name:
prefer_type

Clause update (Section 17.9.4; p. 537)

Permitted on directives: depobj.

Arguments

Name Type Properties
update-var variable of OpenMP
depend type
default

Modifiers

Name Modifies Type Properties
task-dependence-
type
all arguments Keyword:depobj, in,
inout,inoutset,
mutexinoutset, out
unique
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

dispatch (Section 9.7; pp. 368–369; category: executable; association: block : function-dispatch; properties: context-matching)

Clause depend (Section 17.9.5; pp. 538–540)

Permitted on directives: dispatch, interop, target, target_data, target_enter_data, target_exit_data, target_update, task, task_iteration, taskwait.

Arguments

Name Type Properties
locator-list list of locator list item
type
default

Modifiers

Name Modifies Type Properties
task-dependence-
type
all arguments Keyword:depobj, in,
inout,inoutset,
mutexinoutset, out
unique
iterator locator-list Complex, name:iterator

Clause device (Section 15.2; p. 482)

Permitted on directives: dispatch, interop, target, target_data, target_enter_data, target_exit_data, target_update.

Arguments

Name Type Properties
device-description expression of integer
type
default

Modifiers

Name Modifies Type Properties
device-modifier device-description Keyword:ancestor,
device_num
default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause has_device_addr (Section 7.5.9; p. 268)

Permitted on directives: dispatch, target.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause interop (Section 9.7.1; p. 370)

Permitted on directives: dispatch.

Arguments

Name Type Properties
interop-var-list list of variable of interop
OpenMP type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause is_device_ptr (Section 7.5.7; p. 266)

Permitted on directives: dispatch, target.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause nocontext (Section 9.7.3; p. 371)

Permitted on directives: dispatch.

Arguments

Name Type Properties
do-not-update-context expression of OpenMP
logical type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause novariants (Section 9.7.2)

Permitted on directives: dispatch.

Arguments

Name Type Properties
do-not-use-variant expression of OpenMP
logical type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause nowait (Section 17.6; pp. 512–513)

Permitted on directives: dispatch, do, for, interop, scope, sections, single, target, target_data, target_enter_data, target_exit_data, target_update, taskwait, workshare.

Arguments

Name Type Properties
do_not_synchronize expression of OpenMP
logical type
optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

distribute (Section 13.7; pp. 451–452; category: executable; association: loop nest; properties: SIMD-partitionable,)

Clause allocate (Section 8.6; pp. 343–345)

Permitted on directives: allocators, distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskgroup, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
allocator-simple-
modifier
list expression of OpenMP allo-
cator_handle type
exclusive, unique
allocator-complex-
modifier
list Complex, name:
allocator

Clause collapse (Section 6.4.5; p. 236)

Permitted on directives: distribute, do, for, loop, simd, taskloop.

Arguments

Name Type Properties
n expression of integer
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause dist_schedule (Section 13.7.1; p. 453)

Permitted on directives: distribute.

Arguments

Name Type Properties
kind Keyword:static default
chunk_size expression of integer
type
ultimate, optional, posi-
tive, region-invariant

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause firstprivate (Section 7.5.4; pp. 258–259)

Permitted on directives: distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
saved list Keyword:saved default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause induction (Section 7.6.13; pp. 288–290)

Permitted on directives: distribute, do, for, simd, taskloop.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
induction-
identifier
list OpenMP induction identifier required, ultimate
step-modifier list Complex, name:step

Clause lastprivate (Section 7.5.5; pp. 260–262)

Permitted on directives: distribute, do, for, loop, sections, simd, taskloop.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
lastprivate-
modifier
list Keyword:conditional default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause order (Section 12.3; pp. 428–429)

Permitted on directives: distribute, do, for, loop, simd.

Arguments

Name Type Properties
ordering Keyword:
concurrent
default

Modifiers

Name Modifies Type Properties
order-modifier ordering Keyword:reproducible,
unconstrained
default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause private (Section 7.5.3; pp. 256–257)

Permitted on directives: distribute, do, for, loop, parallel, scope, sections, simd, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

do (Section 13.6.2; p. 448; category: executable; association: loop nest; properties: work-distribution,)

Clause allocate (Section 8.6; pp. 343–345)

Permitted on directives: allocators, distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskgroup, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
allocator-simple-
modifier
list expression of OpenMP allo-
cator_handle type
exclusive, unique
allocator-complex-
modifier
list Complex, name:
allocator

Clause collapse (Section 6.4.5; p. 236)

Permitted on directives: distribute, do, for, loop, simd, taskloop.

Arguments

Name Type Properties
n expression of integer
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause firstprivate (Section 7.5.4; pp. 258–259)

Permitted on directives: distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
saved list Keyword:saved default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause induction (Section 7.6.13; pp. 288–290)

Permitted on directives: distribute, do, for, simd, taskloop.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
induction-
identifier
list OpenMP induction identifier required, ultimate
step-modifier list Complex, name:step

Clause lastprivate (Section 7.5.5; pp. 260–262)

Permitted on directives: distribute, do, for, loop, sections, simd, taskloop.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
lastprivate-
modifier
list Keyword:conditional default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause linear (Section 7.5.6; pp. 263–265)

Permitted on directives: declare_simd, do, for, simd.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
step-simple-
modifier
list OpenMP integer expression exclusive, region-
invariant, unique
step-complex-
modifier
list Complex, name:step

Clause nowait (Section 17.6; pp. 512–513)

Permitted on directives: dispatch, do, for, interop, scope, sections, single, target, target_data, target_enter_data, target_exit_data, target_update, taskwait, workshare.

Arguments

Name Type Properties
do_not_synchronize expression of OpenMP
logical type
optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause order (Section 12.3; pp. 428–429)

Permitted on directives: distribute, do, for, loop, simd.

Arguments

Name Type Properties
ordering Keyword:
concurrent
default

Modifiers

Name Modifies Type Properties
order-modifier ordering Keyword:reproducible,
unconstrained
default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause ordered (Section 6.4.6; p. 237)

Permitted on directives: do, for.

Arguments

Name Type Properties
n expression of integer
type
optional, constant, posi-
tive

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause private (Section 7.5.3; pp. 256–257)

Permitted on directives: distribute, do, for, loop, parallel, scope, sections, simd, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause reduction (Section 7.6.10; pp. 283–285)

Permitted on directives: do, for, loop, parallel, scope, sections, simd, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
reduction-
identifier
all arguments An OpenMP reduction iden-
tifier
required, ultimate
reduction-modifier list Keyword:default,
inscan, task
default
original-sharing-
modifier
list Complex, name:original

Clause schedule (Section 13.6.3; pp. 449–450)

Permitted on directives: do, for.

Arguments

Name Type Properties
kind Keyword:auto,
dynamic, guided,
runtime, static
default
chunk_size expression of integer
type
ultimate, optional, posi-
tive, region-invariant

Modifiers

Name Modifies Type Properties
ordering-modifier kind Keyword:monotonic,
nonmonotonic
unique
chunk-modifier kind Keyword:simd unique
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

error (Section 10.1; p. 383; category: utility; association: unassociated; properties: pure)

Clause at (Section 10.2)

Permitted on directives: error.

Arguments

Name Type Properties
action-time Keyword:
compilation,
execution
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause message (Section 10.3; p. 384)

Permitted on directives: error, parallel.

Arguments

Name Type Properties
msg-string expression of string type default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause severity (Section 10.4; p. 385)

Permitted on directives: error, parallel.

Arguments

Name Type Properties
sev-level Keyword:fatal,
warning
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

flush (Section 17.8.6; pp. 529–535; category: executable; association: unassociated; properties: default)

Clause acq_rel (Section 17.8.1.1; p. 515)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use-semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause acquire (Section 17.8.1.2; p. 516)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause memscope (Section 17.8.4; p. 524)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
scope-specifier Keyword:all,
cgroup,device
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause relaxed (Section 17.8.1.3)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause release (Section 17.8.1.4; p. 517)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause seq_cst (Section 17.8.1.5; p. 518; properties: exclusive, unique Members:)

Permitted on directives: atomic, flush.

Arguments

Name Type Properties
use_semantics expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

for (Section 13.6.1; p. 447; category: executable; association: loop nest; properties: work-distribution,)

Clause allocate (Section 8.6; pp. 343–345)

Permitted on directives: allocators, distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskgroup, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
allocator-simple-
modifier
list expression of OpenMP allo-
cator_handle type
exclusive, unique
allocator-complex-
modifier
list Complex, name:
allocator

Clause collapse (Section 6.4.5; p. 236)

Permitted on directives: distribute, do, for, loop, simd, taskloop.

Arguments

Name Type Properties
n expression of integer
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause firstprivate (Section 7.5.4; pp. 258–259)

Permitted on directives: distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
saved list Keyword:saved default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause induction (Section 7.6.13; pp. 288–290)

Permitted on directives: distribute, do, for, simd, taskloop.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
induction-
identifier
list OpenMP induction identifier required, ultimate
step-modifier list Complex, name:step

Clause lastprivate (Section 7.5.5; pp. 260–262)

Permitted on directives: distribute, do, for, loop, sections, simd, taskloop.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
lastprivate-
modifier
list Keyword:conditional default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause linear (Section 7.5.6; pp. 263–265)

Permitted on directives: declare_simd, do, for, simd.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
step-simple-
modifier
list OpenMP integer expression exclusive, region-
invariant, unique
step-complex-
modifier
list Complex, name:step

Clause nowait (Section 17.6; pp. 512–513)

Permitted on directives: dispatch, do, for, interop, scope, sections, single, target, target_data, target_enter_data, target_exit_data, target_update, taskwait, workshare.

Arguments

Name Type Properties
do_not_synchronize expression of OpenMP
logical type
optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause order (Section 12.3; pp. 428–429)

Permitted on directives: distribute, do, for, loop, simd.

Arguments

Name Type Properties
ordering Keyword:
concurrent
default

Modifiers

Name Modifies Type Properties
order-modifier ordering Keyword:reproducible,
unconstrained
default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause ordered (Section 6.4.6; p. 237)

Permitted on directives: do, for.

Arguments

Name Type Properties
n expression of integer
type
optional, constant, posi-
tive

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause private (Section 7.5.3; pp. 256–257)

Permitted on directives: distribute, do, for, loop, parallel, scope, sections, simd, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause reduction (Section 7.6.10; pp. 283–285)

Permitted on directives: do, for, loop, parallel, scope, sections, simd, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
reduction-
identifier
all arguments An OpenMP reduction iden-
tifier
required, ultimate
reduction-modifier list Keyword:default,
inscan, task
default
original-sharing-
modifier
list Complex, name:original

Clause schedule (Section 13.6.3; pp. 449–450)

Permitted on directives: do, for.

Arguments

Name Type Properties
kind Keyword:auto,
dynamic, guided,
runtime, static
default
chunk_size expression of integer
type
ultimate, optional, posi-
tive, region-invariant

Modifiers

Name Modifies Type Properties
ordering-modifier kind Keyword:monotonic,
nonmonotonic
unique
chunk-modifier kind Keyword:simd unique
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

fuse (Section 11.3; p. 405; category: executable; association: loop sequence; properties: loop-transforming, order-)

Clause apply (Section 11.1; pp. 403–404)

Permitted on directives: fuse, interchange, nothing, reverse, split, stripe, tile, unroll.

Arguments

Name Type Properties
applied-directives list of directive specifi-
cation list item type
default

Modifiers

Name Modifies Type Properties
loop-modifier applied-directives Complex, Keyword:
fused,grid, identity,
interchanged,
intratile,offsets,
reversed, split,
unrolled

Clause looprange (Section 6.4.7; pp. 238–245)

Permitted on directives: fuse.

Arguments

Name Type Properties
first expression of OpenMP
integer type
constant, positive
count expression of OpenMP
integer type
constant, positive, ulti-
mate

Modifiers

Name Modifies Type Properties
saved list Keyword:saved default

groupprivate (Section 7.13; pp. 332–333; category: declarative; association: explicit; properties: pure)

Clause device_type (Section 15.1; p. 481)

Permitted on directives: begin declare_target, declare_target, groupprivate, target.

Arguments

Name Type Properties
device-type-description Keyword:any,host,
nohost
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

interchange (Section 11.4; p. 406; category: executable; association: loop nest; properties: loop-transforming,)

Clause apply (Section 11.1; pp. 403–404)

Permitted on directives: fuse, interchange, nothing, reverse, split, stripe, tile, unroll.

Arguments

Name Type Properties
applied-directives list of directive specifi-
cation list item type
default

Modifiers

Name Modifies Type Properties
loop-modifier applied-directives Complex, Keyword:
fused,grid, identity,
interchanged,
intratile,offsets,
reversed, split,
unrolled

Clause permutation (Section 11.4.1; p. 407)

Permitted on directives: interchange.

Arguments

Name Type Properties
permutation-list list of OpenMP integer
expression type
constant, positive

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

interop (Section 16.1; p. 499; category: executable; association: unassociated; properties: device)

Clause depend (Section 17.9.5; pp. 538–540)

Permitted on directives: dispatch, interop, target, target_data, target_enter_data, target_exit_data, target_update, task, task_iteration, taskwait.

Arguments

Name Type Properties
locator-list list of locator list item
type
default

Modifiers

Name Modifies Type Properties
task-dependence-
type
all arguments Keyword:depobj, in,
inout,inoutset,
mutexinoutset, out
unique
iterator locator-list Complex, name:iterator

Clause destroy (Section 5.7; pp. 213–235)

Permitted on directives: depobj, interop.

Arguments

Name Type Properties
destroy-var variable of OpenMP
variable type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause device (Section 15.2; p. 482)

Permitted on directives: dispatch, interop, target, target_data, target_enter_data, target_exit_data, target_update.

Arguments

Name Type Properties
device-description expression of integer
type
default

Modifiers

Name Modifies Type Properties
device-modifier device-description Keyword:ancestor,
device_num
default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause init (Section 5.6; pp. 211–212)

Permitted on directives: depobj, interop.

Arguments

Name Type Properties
init-var variable of OpenMP
type
default

Modifiers

Name Modifies Type Properties
prefer-type init-var Complex, name:
prefer_type

Clause nowait (Section 17.6; pp. 512–513)

Permitted on directives: dispatch, do, for, interop, scope, sections, single, target, target_data, target_enter_data, target_exit_data, target_update, taskwait, workshare.

Arguments

Name Type Properties
do_not_synchronize expression of OpenMP
logical type
optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause use (Section 16.1.2; pp. 500–502)

Permitted on directives: interop.

Arguments

Name Type Properties
interop-var variable of interop
OpenMP type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

loop (Section 13.8; p. 454; category: executable; association: loop nest; properties: order-concurrent-nestable,)

Clause bind (Section 13.8.1; pp. 455–456)

Permitted on directives: loop.

Arguments

Name Type Properties
binding Keyword:parallel,
teams,thread
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause collapse (Section 6.4.5; p. 236)

Permitted on directives: distribute, do, for, loop, simd, taskloop.

Arguments

Name Type Properties
n expression of integer
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause lastprivate (Section 7.5.5; pp. 260–262)

Permitted on directives: distribute, do, for, loop, sections, simd, taskloop.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
lastprivate-
modifier
list Keyword:conditional default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause order (Section 12.3; pp. 428–429)

Permitted on directives: distribute, do, for, loop, simd.

Arguments

Name Type Properties
ordering Keyword:
concurrent
default

Modifiers

Name Modifies Type Properties
order-modifier ordering Keyword:reproducible,
unconstrained
default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause private (Section 7.5.3; pp. 256–257)

Permitted on directives: distribute, do, for, loop, parallel, scope, sections, simd, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause reduction (Section 7.6.10; pp. 283–285)

Permitted on directives: do, for, loop, parallel, scope, sections, simd, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
reduction-
identifier
all arguments An OpenMP reduction iden-
tifier
required, ultimate
reduction-modifier list Keyword:default,
inscan, task
default
original-sharing-
modifier
list Complex, name:original

masked (Section 12.5; p. 433; category: executable; association: block; properties: thread-limiting, thread-)

Clause filter (Section 12.5.1; pp. 434–435)

Permitted on directives: masked.

Arguments

Name Type Properties
thread_num expression of integer
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

nothing (Section 10.7; pp. 400–402; category: utility; association: unassociated; properties: pure, loop-transforming)

Clause apply (Section 11.1; pp. 403–404)

Permitted on directives: fuse, interchange, nothing, reverse, split, stripe, tile, unroll.

Arguments

Name Type Properties
applied-directives list of directive specifi-
cation list item type
default

Modifiers

Name Modifies Type Properties
loop-modifier applied-directives Complex, Keyword:
fused,grid, identity,
interchanged,
intratile,offsets,
reversed, split,
unrolled

ordered (Section 17.10.2; pp. 546–547; category: executable; association: block; properties: mutual-exclusion, simdiz-)

Clause doacross (Section 17.9.7; pp. 542–544)

Permitted on directives: ordered.

Arguments

Name Type Properties
iteration-specifier OpenMP iteration speci-
fier
default

Modifiers

Name Modifies Type Properties
dependence-type iteration-specifier Keyword:sink, source required
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause simd (Section 17.10.3.2; pp. 549–550; properties: exclusive, required, unique Members:)

Permitted on directives: ordered.

Arguments

Name Type Properties
apply-to-simd expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause threads (Section 17.10.3.1; p. 548)

Permitted on directives: ordered.

Arguments

Name Type Properties
apply-to-threads expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

parallel (Section 12.1; pp. 415–418; category: executable; association: block; properties: cancellable, context-)

Clause allocate (Section 8.6; pp. 343–345)

Permitted on directives: allocators, distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskgroup, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
allocator-simple-
modifier
list expression of OpenMP allo-
cator_handle type
exclusive, unique
allocator-complex-
modifier
list Complex, name:
allocator

Clause copyin (Section 7.8.1; p. 302)

Permitted on directives: parallel.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause default (Section 7.5.1; p. 254)

Permitted on directives: parallel, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
data-sharing-attribute Keyword:
firstprivate,
none, private,
shared
default

Modifiers

Name Modifies Type Properties
variable-category implicit-behavior Keyword:aggregate,
all, allocatable,
pointer,scalar
default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause firstprivate (Section 7.5.4; pp. 258–259)

Permitted on directives: distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
saved list Keyword:saved default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause if (Section 5.5; p. 210)

Permitted on directives: cancel, parallel, simd, target, target_data, target_enter_data, target_exit_data, target_update, task, task_iteration, taskgraph, taskloop, teams.

Arguments

Name Type Properties
if-expression expression of OpenMP
logical type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause message (Section 10.3; p. 384)

Permitted on directives: error, parallel.

Arguments

Name Type Properties
msg-string expression of string type default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause num_threads (Section 12.1.2; pp. 419–422)

Permitted on directives: parallel.

Arguments

Name Type Properties
nthreads list of OpenMP integer
expression type
positive

Modifiers

Name Modifies Type Properties
prescriptiveness nthreads Keyword:strict default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause private (Section 7.5.3; pp. 256–257)

Permitted on directives: distribute, do, for, loop, parallel, scope, sections, simd, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause proc_bind (Section 12.1.4; p. 423)

Permitted on directives: parallel.

Arguments

Name Type Properties
affinity-policy Keyword:close,
primary, spread
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause reduction (Section 7.6.10; pp. 283–285)

Permitted on directives: do, for, loop, parallel, scope, sections, simd, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
reduction-
identifier
all arguments An OpenMP reduction iden-
tifier
required, ultimate
reduction-modifier list Keyword:default,
inscan, task
default
original-sharing-
modifier
list Complex, name:original

Clause safesync (Section 12.1.5; p. 424)

Permitted on directives: parallel.

Arguments

Name Type Properties
width expression of integer
type
positive, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause severity (Section 10.4; p. 385)

Permitted on directives: error, parallel.

Arguments

Name Type Properties
sev-level Keyword:fatal,
warning
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause shared (Section 7.5.2; p. 255)

Permitted on directives: parallel, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

requires (Section 10.5; p. 386; category: informational; association: unassociated; properties: default)

Clause atomic_default_mem_order (Section 10.5.1.1; p. 387)

Permitted on directives: requires.

Arguments

Name Type Properties
memory-order Keyword:acq_rel,
acquire,relaxed,
release,seq_cst
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause device_safesync (Section 10.5.1.7; p. 393; properties: required, unique Members:)

Permitted on directives: requires.

Arguments

Name Type Properties
required expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause dynamic_allocators (Section 10.5.1.2; p. 388)

Permitted on directives: requires.

Arguments

Name Type Properties
required expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause reverse_offload (Section 10.5.1.3; p. 389)

Permitted on directives: requires.

Arguments

Name Type Properties
required expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause self_maps (Section 10.5.1.6; p. 392)

Permitted on directives: requires.

Arguments

Name Type Properties
required expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause unified_address (Section 10.5.1.4; p. 390)

Permitted on directives: requires.

Arguments

Name Type Properties
required expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause unified_shared_memory (Section 10.5.1.5; p. 391)

Permitted on directives: requires.

Arguments

Name Type Properties
required expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

reverse (Section 11.5; category: executable; association: loop nest; properties: generally-composable,)

Clause apply (Section 11.1; pp. 403–404)

Permitted on directives: fuse, interchange, nothing, reverse, split, stripe, tile, unroll.

Arguments

Name Type Properties
applied-directives list of directive specifi-
cation list item type
default

Modifiers

Name Modifies Type Properties
loop-modifier applied-directives Complex, Keyword:
fused,grid, identity,
interchanged,
intratile,offsets,
reversed, split,
unrolled

scan (Section 7.7; pp. 297–299; category: subsidiary; association: separating; properties: pure)

Clause exclusive (Section 7.7.2; p. 300)

Permitted on directives: scan.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause inclusive (Section 7.7.1)

Permitted on directives: scan.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause init_complete (Section 7.7.3; p. 301)

Permitted on directives: scan.

Arguments

Name Type Properties
create_init_phase expression of OpenMP
logical type
constant, optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

scope (Section 13.2; p. 437; category: executable; association: block; properties: work-distribution, team-)

Clause allocate (Section 8.6; pp. 343–345)

Permitted on directives: allocators, distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskgroup, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
allocator-simple-
modifier
list expression of OpenMP allo-
cator_handle type
exclusive, unique
allocator-complex-
modifier
list Complex, name:
allocator

Clause firstprivate (Section 7.5.4; pp. 258–259)

Permitted on directives: distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
saved list Keyword:saved default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause nowait (Section 17.6; pp. 512–513)

Permitted on directives: dispatch, do, for, interop, scope, sections, single, target, target_data, target_enter_data, target_exit_data, target_update, taskwait, workshare.

Arguments

Name Type Properties
do_not_synchronize expression of OpenMP
logical type
optional

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause private (Section 7.5.3; pp. 256–257)

Permitted on directives: distribute, do, for, loop, parallel, scope, sections, simd, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause reduction (Section 7.6.10; pp. 283–285)

Permitted on directives: do, for, loop, parallel, scope, sections, simd, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
reduction-
identifier
all arguments An OpenMP reduction iden-
tifier
required, ultimate
reduction-modifier list Keyword:default,
inscan, task
default
original-sharing-
modifier
list Complex, name:original

section (Section 13.3.1; p. 439; category: subsidiary; association: separating; properties: default)

No clauses are defined for this directive in the specification.

sections (Section 13.3; p. 438; category: executable; association: block; properties: work-distribution, team-)

Clause allocate (Section 8.6; pp. 343–345)

Permitted on directives: allocators, distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskgroup, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
allocator-simple-
modifier
list expression of OpenMP allo-
cator_handle type
exclusive, unique
allocator-complex-
modifier
list Complex, name:
allocator

Clause firstprivate (Section 7.5.4; pp. 258–259)

Permitted on directives: distribute, do, for, parallel, scope, sections, single, target, target_data, task, taskloop, teams.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
saved list Keyword:saved default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause lastprivate (Section 7.5.5; pp. 260–262)

Permitted on directives: distribute, do, for, loop, sections, simd, taskloop.

Arguments

Name Type Properties
list list of variable list item
type
default

Modifiers

Name Modifies Type Properties
lastprivate-
modifier
list Keyword:conditional default
directive-name-
modifier
all arguments Keyword:directive-name(a
directive name)
unique

Clause nowait (Section 17.6; pp. 512–513)

Permitted on directives: dispatch, do, for, interop, scope, sections, single, target, target_data, target_enter_data, target_exit_data, target_update, taskwait, workshare.