# dgruber/drmaa architecture

> Architecture diagram of the GitHub repository dgruber/drmaa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dgruber/drmaa
- Repository: https://github.com/dgruber/drmaa

## Overview

##### Project type and purpose
- This is an open-source Go library (“go-drmaa”) that wraps the DRMAA C API for job submission to cluster schedulers.
- Its goal is to provide Go applications with a native interface to the DRMAA standard, supporting Grid Engine, Torque, SLURM and others.

##### File structure
- Top-level Go files:
- drmaa.go / drmaa_test.go – core CGO wrapper and unit tests
- gestatus/ – subpackage with Grid-Engine-specific status utilities
- examples/ – sample Go programs demonstrating job submission, status checks, array jobs
- dockerfiles/ – helper images to build and test against Open Cluster Scheduler and SLURM C libraries
- build.sh, go.mod – build script and module definition
- README.md, LICENSE, COPYING – documentation and licensing

##### Key README insights
- Explains supported resource managers, compilation flags, environment setup
- Describes session lifecycle, job template allocation, job submission, waiting, termination
- Highlights C-Go boundary and need for CGO and LD_LIBRARY_PATH

##### Main components
a. Go-drmaa library:
– drmaa package (CGO bindings)
– gestatus subpackage
b. Example applications:
– simplesubmit, simplearrayjob, simplegestatus
c. External C DRMAA library (libdrmaa.so)
d. Cluster scheduler services:
– Univa/Grid Engine, Torque, SLURM, Open Cluster Scheduler
e. Build/packaging:
– Docker images under dockerfiles/ for each scheduler

##### Relationships & data flow
- Examples/apps → call Go-drmaa API
- Go-drmaa CGO layer → invokes C DRMAA functions
- C DRMAA library → communicates over network or IPC with scheduler daemons
- Scheduler → manages job lifecycle on compute nodes

##### Architectural patterns & design principles
- Adapter/Wrapper pattern: Go API adapts C library calls
- Separation of concerns:
- Core wrapper (drmaa) vs. scheduler-specific helpers (gestatus)
- Examples decoupled from library code
- Extensibility: Additional resource managers plugged in via build flags & CGO

##### Relevant technologies
- Go / CGO
- C DRMAA standard (libdrmaa.so)
- Docker for build/test environments
- Makefile / shell scripts for cross-platform builds

##### Final advice
- Be exhaustive: include every logical component (even small scripts) so reviewers see the full picture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Go Application Layer
    subgraph "Go Application Layer"
        direction TB
        SS["SimpleSubmit"]:::go
        SA["SimpleArrayJob"]:::go
        SG["SimpleGestatus"]:::go
    end

    %% Go-drmaa Library
    subgraph "Go-drmaa Library"
        direction TB
        DR["drmaa package"]:::go
        GE["gestatus subpackage"]:::go
    end

    %% CGO Boundary
    CGO["CGO / C-API Boundary"]:::c

    %% C Library
    CL["C DRMAA Library (libdrmaa.so)"]:::c

    %% Cluster Schedulers
    subgraph "Cluster Schedulers"
        direction TB
        GE_Sched["Grid Engine"]:::external
        Torque["Torque"]:::external
        SLURM_Sched["SLURM"]:::external
        OCS["Open Cluster Scheduler"]:::external
    end

    %% Build/Packaging Tools
    subgraph "Build/Packaging Tools"
        direction TB
        DF_OCS["Docker OpenClusterScheduler Env"]:::tooling
        DF_SLURM["Docker SLURM Env"]:::tooling
        Build["build.sh & go.mod"]:::tooling
    end

    %% Documentation
    subgraph "Documentation & Licensing"
        direction TB
        README["README.md"]:::tooling
        LICENSE_F["LICENSE"]:::tooling
        COPYING_F["COPYING"]:::tooling
    end

    %% Connections
    SS -->|"RunJob()"| DR
    SA -->|"RunArrayJob()"| DR
    SG -->|"GetStatus()"| GE
    DR -->|"drmaa_make_session()"| CGO
    CGO -->|"drmaa_run_job()"| CL
    CL -->|"communicates"| GE_Sched
    CL -->|"communicates"| Torque
    CL -->|"communicates"| SLURM_Sched
    CL -->|"communicates"| OCS
    DF_OCS -->|"build/test"| CL
    DF_SLURM -->|"build/test"| CL
    Build -->|"orchestrates"| DR
    Build -->|"orchestrates"| GE
    Build -->|"uses"| DF_OCS
    Build -->|"uses"| DF_SLURM

    %% Click Events for component mapping
    click DR "https://github.com/dgruber/drmaa/blob/master/drmaa.go"
    click DR "https://github.com/dgruber/drmaa/blob/master/drmaa_test.go"
    click GE "https://github.com/dgruber/drmaa/blob/master/gestatus/gestatus.go"
    click GE "https://github.com/dgruber/drmaa/blob/master/gestatus/private_gestatus/private_gestatus.go"
    click SS "https://github.com/dgruber/drmaa/blob/master/examples/simplesubmit/submit.go"
    click SS "https://github.com/dgruber/drmaa/blob/master/examples/simplesubmit/build.sh"
    click SA "https://github.com/dgruber/drmaa/blob/master/examples/simplearrayjob/simplearrayjob.go"
    click SA "https://github.com/dgruber/drmaa/blob/master/examples/simplearrayjob/build.sh"
    click SG "https://github.com/dgruber/drmaa/blob/master/examples/simplegestatus/status.go"
    click SG "https://github.com/dgruber/drmaa/blob/master/examples/simplegestatus/build.sh"
    click DF_OCS "https://github.com/dgruber/drmaa/tree/master/dockerfiles/openclusterscheduler"
    click DF_SLURM "https://github.com/dgruber/drmaa/tree/master/dockerfiles/slurm"
    click Build "https://github.com/dgruber/drmaa/blob/master/build.sh"
    click Build "https://github.com/dgruber/drmaa/blob/master/go.mod"
    click README "https://github.com/dgruber/drmaa/blob/master/README.md"
    click LICENSE_F "https://github.com/dgruber/drmaa/tree/master/LICENSE"
    click COPYING_F "https://github.com/dgruber/drmaa/tree/master/COPYING"

    %% Styles
    classDef go fill:#e0f7e9,stroke:#2d7a3e,stroke-width:2px
    classDef c fill:#e0e7f7,stroke:#3a4a9f,stroke-width:2px
    classDef external fill:#fde4c2,stroke:#d97800,stroke-width:2px
    classDef tooling fill:#f0f0f0,stroke:#666666,stroke-width:2px
```
