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