Lập trình generic trong Ada — Viết hợp đồng bằng kiểu, tái sử dụng với chi phí zero

flowchart LR
    accTitle: Ba cách tái sử dụng mã
    accDescr: So sánh copy-paste, void-star hoặc cast, và generic Ada về sót sửa, lỗi runtime, và kiểm tra lúc biên dịch
    A["Logic muốn tái sử dụng"] --> B{"Tái sử dụng thế nào?"}
    B --> C["Copy và paste"]
    B --> D["void* / Object / cast"]
    B --> E["Generic Ada"]

    C --> C1["Dễ sót chỗ sửa"]
    D --> D1["Dễ lỗi runtime hoặc mất an toàn kiểu"]
    E --> E1["An toàn kiểu"]
    E --> E2["Kiểm tra lúc biên dịch"]
    E --> E3["Không có dispatch thừa lúc runtime"]

flowchart LR
    accTitle: Bản đồ tri thức lập trình generic của Ada
    accDescr: Sơ đồ cho thấy Generic Subprogram và Generic Package được xây trên hợp đồng (contract model) của các formal parameter kiểu, giá trị, subprogram và package, việc kiểm hợp đồng đó lúc instantiation bằng new, cùng khác biệt với vấn đề lỗi chỉ lộ khi instantiate mà template C++ từng gặp trong lịch sử
    ada_generics["Generic của Ada (generic unit)"]
    ada_generic_contract_model["Contract model của generic Ada"]
    ada["Ada (ngôn ngữ lập trình)"]
    ada_generic_subprogram["Generic Subprogram"]
    ada_generic_package["Generic Package"]
    ada_generic_formal_type["Formal Type (tham số kiểu)"]
    ada_generic_formal_subprogram["Formal Subprogram (tham số subprogram)"]
    ada_generic_formal_package["Formal Package (tham số package)"]
    ada_generic_instantiation["Instantiation (khởi tạo generic)"]
    ada_generic_formal_object["Formal Object (tham số giá trị)"]
    late_instantiation_error["Lỗi template chỉ phát hiện lúc instantiation"]
    cpp_templates["Template C++"]
    gnat["GNAT"]
    alire["Alire"]
    ada -->|"triển khai"| ada_generics
    ada_generics -->|"sử dụng"| ada_generic_subprogram
    ada_generics -->|"sử dụng"| ada_generic_package
    ada_generic_subprogram -.->|"yêu cầu"| ada_generic_formal_type
    ada_generics -->|"sử dụng"| ada_generic_formal_subprogram
    ada_generics -->|"sử dụng"| ada_generic_formal_package
    ada_generics -->|"yêu cầu"| ada_generic_instantiation
    ada_generic_formal_type -->|"cấu hình bằng"| ada_generic_instantiation
    ada_generic_package -.->|"yêu cầu"| ada_generic_formal_type
    ada_generic_package -.->|"yêu cầu"| ada_generic_formal_object
    ada_generic_formal_subprogram -->|"triển khai"| ada_generic_contract_model
    ada_generic_formal_type -->|"triển khai"| ada_generic_contract_model
    ada_generic_contract_model -->|"ngăn chặn"| late_instantiation_error
    cpp_templates -.->|"có thể gây"| late_instantiation_error
    ada_generic_formal_package -->|"yêu cầu"| ada_generic_instantiation
    gnat -->|"triển khai"| ada
    gnat -.->|"cấu hình bằng"| alire
    ada_generic_subprogram -.->|"sử dụng"| ada_generic_formal_subprogram
    ada_generic_package -.->|"sử dụng"| ada_generic_formal_subprogram
    ada_generic_instantiation -.->|"yêu cầu"| ada_generic_formal_object
    ada_generic_formal_object -->|"triển khai"| ada_generic_contract_model

mindmap
    root((Ada Generics))
      Generic Subprogram
        Swap
        Count_If
        Sort
      Generic Package
        Stack
        Statistics
        KV Store
      Formal Parameters
        Type
          private
          limited private
          range box
          mod box
          digits box
          delta box
          discrete box
        Object
          Max_Size
          Threshold
        Subprogram
          Less function
          Equals function
          Predicate
        Package
          with package P is new Generic
      Design Ideas
        Contract Model
        Static Checking
        Zero-Cost Abstraction
        Separate Specification and Body

flowchart TB
    accTitle: Bố cục sample của bài viết
    accDescr: Thư mục ada-generic-programming chứa src/snippets với sáu file .ada và README.md
    R[ada-generic-programming/] --> S[src/]
    S --> N[snippets/]
    N --> A[01_swap.ada]
    N --> B[02_stack.ada]
    N --> C[03_sort.ada]
    N --> D[04_statistics.ada]
    N --> E[05_filter.ada]
    N --> F[06_kv_store.ada]
    R --> README[README.md]

sequenceDiagram
    accTitle: Quy trình biên dịch sample
    accDescr: gnatchop tách file .ada rồi gnatmake biên dịch và chạy file thực thi
    participant Dev as Nhà phát triển
    participant Chop as gnatchop
    participant Build as gnatmake
    participant Exe as File thực thi

    Dev->>Chop: Đưa một file .ada
    Chop-->>Dev: Tách thành .ads / .adb / main
    Dev->>Build: gnatmake -gnata main
    Build-->>Dev: Bind và link xong
    Dev->>Exe: ./main
    Exe-->>Dev: Kết quả chạy

flowchart LR
    accTitle: Mô hình cơ bản của generic Ada
    accDescr: Khai báo generic, formal parameter, body, rồi instantiation bằng new để dùng như subprogram hoặc package thường
    G["khai báo generic"] --> F["formal parameter"]
    F --> B["generic body"]
    B --> I["instantiation bằng new"]
    I --> U["Dùng như subprogram hoặc package thường"]

    F --> F1["Kiểu"]
    F --> F2["Giá trị"]
    F --> F3["Subprogram"]
    F --> F4["Package"]

flowchart TB
    accTitle: Instantiation Generic_Swap theo từng kiểu
    accDescr: Cùng template Generic_Swap tạo Swap_Integer, Swap_Character, Swap_My_Record tùy kiểu truyền vào
    Template[Generic_Swap<br/>type Element is private] -->|"Truyền Integer"| SwapInt[Swap_Integer]
    Template -->|"Truyền Character"| SwapChar[Swap_Character]
    Template -->|"Truyền My_Record"| SwapRecord[Swap_My_Record]

    SwapInt --> ICall["Hoán đổi biến Integer"]
    SwapChar --> CCall["Hoán đổi biến Character"]
    SwapRecord --> RCall["Hoán đổi biến My_Record"]

flowchart TB
    accTitle: Bốn loại formal parameter của generic Ada
    accDescr: Generic Ada nhận formal parameter kiểu, giá trị, subprogram, và package chứ không chỉ kiểu
    P[generic formal parameters] --> T["Type parameter"]
    P --> O["Object / value parameter"]
    P --> S["Subprogram parameter"]
    P --> PKG["Package parameter"]

    T --> T1[type Element is private]
    T --> T2[type Index is box]
    T --> T3[type Real is digits box]
    O --> O1[Max_Size : Positive]
    O --> O2[Default_Value : Element]
    S --> S1[with function Less...]
    S --> S2[with procedure Put ...]
    PKG --> P1[with package P is new ...]

flowchart LR
    accTitle: Luồng hoán đổi Generic_Swap
    accDescr: Temp nhận A, A nhận B, rồi B nhận Temp, hai biến đổi chỗ sau lời gọi
    subgraph Before["Trước khi gọi"]
        A1["A = 10"]
        B1["B = 20"]
    end

    A1 --> T["Temp = A"]
    B1 --> A2["A = B"]
    T --> B2["B = Temp"]

    subgraph After["Sau khi gọi"]
        A2["A = 20"]
        B2["B = 10"]
    end

flowchart TB
    accTitle: Generic_Stack nhận kiểu và kích thước
    accDescr: Generic_Stack lấy Element_Type và Max_Size rồi sinh các instance stack Integer, Float, Unbounded_String
    G[Generic_Stack] --> P1[Element_Type]
    G --> P2[Max_Size]
    G --> Ops[Push / Pop / Size / Is_Empty / Is_Full]

    G --> I1[Int_Stack<br/>Element=Integer<br/>Max_Size=5]
    G --> I2[Float_Stack<br/>Element=Float<br/>Max_Size=3]
    G --> I3[String_Stack<br/>Element=Unbounded_String<br/>Max_Size=20]

flowchart LR
    accTitle: Mỗi instance stack có trạng thái riêng
    accDescr: Int_Stack và Float_Stack sinh từ cùng Generic_Stack nhưng không chia sẻ Top hay Data
    Template[Generic_Stack] --> IntStack[Int_Stack]
    Template --> FloatStack[Float_Stack]

    subgraph I["Trạng thái của Int_Stack"]
        ITop[Top]
        IData["Data : mảng Integer"]
    end

    subgraph F["Trạng thái của Float_Stack"]
        FTop[Top]
        FData["Data : mảng Float"]
    end

    IntStack --> I
    FloatStack --> F

stateDiagram-v2
    accTitle: Máy trạng thái của stack
    accDescr: Stack chuyển Empty, NonEmpty, Full, Overflow, Underflow theo Push và Pop
    [*] --> Empty
    Empty --> NonEmpty: Push
    NonEmpty --> NonEmpty: Push / Pop
    NonEmpty --> Empty: Pop lấy phần tử cuối
    NonEmpty --> Full: Push tới Max_Size
    Full --> NonEmpty: Pop
    Full --> Overflow: Push
    Empty --> Underflow: Pop

flowchart LR
    accTitle: Formal parameter của Generic_Insertion_Sort
    accDescr: Sort generic nhận kiểu phần tử, index, mảng, và hàm so sánh để đổi thứ tự tăng hoặc giảm
    A[Generic_Insertion_Sort] --> T[Item_Type]
    A --> I[Index]
    A --> ARR[Item_Array]
    A --> CMP["Hàm so sánh"]

    CMP --> ASC["Dùng so sánh chuẩn"]
    CMP --> DESC["Truyền Greater để giảm dần"]
    CMP --> CUSTOM["Truyền thứ tự riêng"]

flowchart TB
    accTitle: Luồng insertion sort
    accDescr: Lấy Key từ trái sang, dịch phần tử đứng trước khi Key đứng trước, rồi chèn Key cho đến hết mảng
    Start["Mảng chưa sắp"] --> Pick["Lần lượt lấy Key từ trái"]
    Pick --> Compare{"Key đứng trước phần tử ngay trước?"}
    Compare -->|Yes| Shift["Dịch phần tử ngay trước sang phải"]
    Shift --> Compare
    Compare -->|No| Insert["Chèn Key"]
    Insert --> Done{"Xử lý hết chưa?"}
    Done -->|No| Pick
    Done -->|Yes| End["Mảng đã sắp"]

flowchart LR
    accTitle: Cùng body, hai thứ tự nhờ đổi hàm so sánh
    accDescr: Sort_Asc dùng so sánh chuẩn, Sort_Desc truyền Greater, nên cùng dữ liệu ra hai thứ tự ngược nhau
    Data[99, 3, 47, 12] --> A[Sort_Asc<br/>so sánh chuẩn]
    Data --> D[Sort_Desc<br/>truyền Greater làm hàm so sánh]
    A --> AO[3, 12, 47, 99]
    D --> DO[99, 47, 12, 3]

flowchart TB
    accTitle: Các category của formal type
    accDescr: Formal type có thể là private, limited private, discrete, range, mod, digits, delta, hoặc access
    FormalType[Formal Type] --> Private[private]
    FormalType --> Limited[limited private]
    FormalType --> Discrete["discrete box: discrete type"]
    FormalType --> Signed["range box: signed integer"]
    FormalType --> Modular["mod box: modular integer"]
    FormalType --> Float["digits box: floating-point"]
    FormalType --> Fixed["delta box: fixed-point"]
    FormalType --> Access["kiểu access"]

    Discrete --> Enum["Enumeration"]
    Discrete --> Int["Integer"]
    Float --> F1[Float]
    Float --> F2[Long_Float]
    Float --> F3["Floating-point do người dùng định nghĩa"]

flowchart LR
    accTitle: Generic_Statistics cho nhiều độ chính xác
    accDescr: Cùng statistics package instantiate cho Float, Long_Float, và Real do người dùng định nghĩa
    Stats[Generic_Statistics<br/>Real is digits box] --> FS[Float_Stats]
    Stats --> LS[Long_Stats]
    Stats --> MS[My_Real_Stats]

    FS --> FCalc["Mean / Variance trên Float"]
    LS --> LCalc["Mean / Variance trên Long_Float"]
    MS --> MCalc["Mean / Variance trên Real do người dùng định nghĩa"]

flowchart LR
    accTitle: Luồng Generic_Count_If
    accDescr: Duyệt mảng, tăng Count khi Predicate đúng, bỏ qua khi sai, rồi trả Count
    Arr["Mảng"] --> Loop["Duyệt từng phần tử"]
    Loop --> P{"Predicate(Item)?"}
    P -->|True| Inc["Tăng Count"]
    P -->|False| Skip["Không làm gì"]
    Inc --> Next["Sang phần tử tiếp"]
    Skip --> Next
    Next --> Result["Trả Count"]

flowchart TB
    accTitle: Cùng vòng lặp, hai predicate khác nhau
    accDescr: Count_Even đếm số chẵn, Count_Large đếm phần tử lớn hơn 50, cùng Generic_Count_If
    G[Generic_Count_If] --> E[Count_Even<br/>Predicate = Is_Even]
    G --> L[Count_Large<br/>Predicate = Is_Large]

    Data[12, 7, 88, 3, 56, 91, 44, 19, 62] --> E
    Data --> L
    E --> ER["Số phần tử chẵn"]
    L --> LR["Số phần tử lớn hơn 50"]

flowchart TB
    accTitle: Generic_KV_Store ghép nhiều formal parameter
    accDescr: Store nhận Key_Type, Value_Type, hàm so khớp khóa, và Max_Entries cho Put, Get, Contains
    KV[Generic_KV_Store] --> K[Key_Type]
    KV --> V[Value_Type]
    KV --> EQ["Hàm khớp khóa"]
    KV --> M[Max_Entries]

    KV --> Ops[Put / Get / Contains]
    Ops --> Use1["Store giá trị cấu hình"]
    Ops --> Use2["Cache quy mô nhỏ"]
    Ops --> Use3["Từ điển độ dài cố định cho embedded"]

sequenceDiagram
    accTitle: Luồng Put và Get của KV store
    accDescr: Put ghi đè khi khóa đã có, cấp slot mới khi khóa mới, Get tìm index rồi trả giá trị
    participant App as Phía gọi
    participant Store as Instance Generic_KV_Store
    participant Data as Keys/Values/Used

    App->>Store: Put(Key, Value)
    Store->>Data: Find_Index(Key)
    alt Khóa đã có
        Store->>Data: Values(Pos) := Value
    else Khóa mới
        Store->>Data: Find_Free
        Store->>Data: Keys(Pos) := Key
        Store->>Data: Values(Pos) := Value
        Store->>Data: Used(Pos) := True
    end
    App->>Store: Get(Key)
    Store->>Data: Find_Index(Key)
    Data-->>Store: Pos
    Store-->>App: Values(Pos)

flowchart LR
    accTitle: Logger nhận instance của Generic_Stack
    accDescr: Int_Stack instantiate từ Generic_Stack rồi được truyền vào Generic_Stack_Logger
    GS[Generic_Stack] --> IS[Int_Stack]
    IS --> Logger[Generic_Stack_Logger]
    Logger --> Logged[Int_Stack_Logger_Instance]

flowchart TB
    accTitle: Generic lồng nhau qua formal package
    accDescr: Tầng một tạo Int_Stack, tầng hai nhận stack đó để tạo logger và API Print_Size
    subgraph Layer1["Tầng 1"]
        T1[Generic_Stack] --> I1[Int_Stack]
    end

    subgraph Layer2["Tầng 2"]
        T2[Generic_Stack_Logger] --> I2[Int_Stack_Logger]
    end

    I1 --> T2
    I2 --> API[Print_Size]

flowchart TB
    accTitle: Contract model của generic Ada
    accDescr: Formal part là hợp đồng, body được kiểm kiểu độc lập, instantiation kiểm actual có thỏa hợp đồng không
    Spec[generic formal part<br/>hợp đồng] --> Body[generic body<br/>cài trong phạm vi hợp đồng]
    Body --> Check1["Kiểm kiểu body độc lập"]
    Spec --> Inst[instantiation]
    Actual[actual parameters<br/>kiểu, hàm, giá trị thực] --> Inst
    Inst --> Check2["Kiểm actual có thỏa hợp đồng"]
    Check2 --> Instance["Package/subprogram thường"]

flowchart LR
    accTitle: Ada viết hợp đồng trước, template C++ cụ thể hóa lúc instantiate
    accDescr: Ada kiểm body trong phạm vi formal part rồi kiểm actual lúc instantiate; C++ trước đây cụ thể hóa lúc instantiate dù concepts đã cải thiện
    subgraph Ada[Ada]
        A1["Viết hợp đồng ở formal part"] --> A2["body được kiểm trong hợp đồng"]
        A2 --> A3["instantiation kiểm actual"]
    end

    subgraph CPP[C++ templates]
        C1["Viết template body"] --> C2["Yêu cầu cụ thể hóa lúc instantiate"]
        C2 --> C3["Có thể nêu ràng buộc bằng concepts"]
    end

flowchart TB
    accTitle: Quyết định cái gì nên thành generic
    accDescr: Khác mỗi kiểu thì type parameter, khác kích thước thì value parameter, khác hành vi thì formal subprogram, có trạng thái thì generic package
    Start["Có xử lý muốn tái sử dụng"] --> Q1{"Chỉ khác kiểu?"}
    Q1 -->|Yes| GType["Xem type parameter"]
    Q1 -->|No| Q2{"Kích thước hay ngưỡng cũng khác?"}
    Q2 -->|Yes| GObject["Thêm value parameter"]
    Q2 -->|No| Q3{"Hành vi so sánh hay kiểm điều kiện cũng khác?"}
    Q3 -->|Yes| GSubp["Thêm formal subprogram"]
    Q3 -->|No| Q4{"Muốn gom trạng thái nội bộ và API?"}
    Q4 -->|Yes| GPackage["Generic package"]
    Q4 -->|No| Normal["Subprogram thường là đủ"]

flowchart LR
    accTitle: Spec công khai, body ẩn, formal part là hợp đồng
    accDescr: Formal part ràng spec và body, phía dùng chỉ thấy public API của package spec
    Spec[package spec<br/>public API] --> User["Phía dùng"]
    Body[package body<br/>cài đặt nội bộ] -.ẩn.-> User
    Formal[generic formal part<br/>hợp đồng kiểu, giá trị, hàm] --> Spec
    Formal --> Body

flowchart LR
    accTitle: So sánh trên private phải được ghi vào formal part
    accDescr: Muốn so sánh trong body thì viết hàm so sánh vào formal part; chỉ private sẽ lỗi biên dịch
    Need["Muốn so sánh trong body"] --> Contract["Viết hàm so sánh ở formal part"]
    Contract --> OK["Lúc instantiate xác nhận có so sánh được"]
    Need --> NoContract["Chỉ private"]
    NoContract --> Error["Lỗi biên dịch trong generic body"]

flowchart TB
    accTitle: Exception khai báo trong generic là riêng từng instance
    accDescr: Int_Stack.Stack_Overflow và Float_Stack.Stack_Overflow là hai exception khác nhau
    Generic[Generic_Stack<br/>khai báo Stack_Overflow] --> I[Int_Stack.Stack_Overflow]
    Generic --> F[Float_Stack.Stack_Overflow]
    I -.exception khác.-> F

flowchart LR
    accTitle: Mỗi instantiation sinh mã riêng
    accDescr: Một generic body sinh bản Integer, Float, Long_Float, My_Type, tránh boxing lúc runtime nhưng có thể tăng kích thước
    Generic["Một generic body"] --> I1["Bản Integer"]
    Generic --> I2["Bản Float"]
    Generic --> I3["Bản Long_Float"]
    Generic --> I4["Bản My_Type"]

    I1 --> Code["Mã sinh ra"]
    I2 --> Code
    I3 --> Code
    I4 --> Code

    Code --> Pros["Dễ tránh kiểm kiểu hay boxing lúc runtime"]
    Code --> Cons["Nhiều instance thì chú ý tăng kích thước"]

flowchart LR
    accTitle: Generic_Min đòi hàm so sánh
    accDescr: Element cộng hàm so sánh tạo Generic_Min, trả về giá trị nhỏ hơn
    T[Element] --> C["Cần hàm so sánh"]
    C --> M[Generic_Min]
    M --> R["Trả về cái nhỏ hơn"]

flowchart TB
    accTitle: Tiêm thủ tục Put để đổi đích xuất
    accDescr: Generic_Print_Twice nhận Put rồi có thể in console, log, hoặc buffer kiểm thử
    Print[Generic_Print_Twice] --> Put["Nhận Put như formal subprogram"]
    Put --> Console["Xuất console"]
    Put --> Log["Xuất log"]
    Put --> Test["Buffer kiểm thử"]

flowchart LR
    accTitle: Không cố định kiểu index của mảng
    accDescr: Formal Index kiểu discrete nhận Positive, enumeration Day hoặc State, và kiểu số nguyên riêng
    Index[Index is discrete] --> Positive[Positive range]
    Index --> Day["Enumeration Day"]
    Index --> State["Enumeration State"]
    Index --> Slot["Kiểu nguyên riêng"]

flowchart TB
    accTitle: Danh sách kiểm tra thiết kế generic Ada
    accDescr: Kiểm formal tối thiểu, phép toán đã nêu trong formal part, category, named association, exception theo instance, kích thước mã, và instance kiểm thử
    C["Kiểm thiết kế generic"] --> C1["Formal parameter đã tối thiểu?"]
    C --> C2["Phép toán cần thiết đã nêu ở formal part?"]
    C --> C3["Category private / range / digits đã phù hợp?"]
    C --> C4["Instantiate được dễ đọc bằng named association?"]
    C --> C5["Đã ý thức trạng thái và exception theo từng instance?"]
    C --> C6["Có chấp nhận tăng kích thước mã?"]
    C --> C7["Đã chuẩn bị instance cho kiểm thử?"]

flowchart TB
    accTitle: Tách spec, body, và demo thành file
    accDescr: Thư mục src/generics giữ ads và adb, src/demos giữ các chương trình demo
    Root[ada-generic-programming] --> Src[src]
    Src --> G[generics]
    Src --> D[demos]

    G --> SwapSpec[generic_swap.ads]
    G --> SwapBody[generic_swap.adb]
    G --> StackSpec[generic_stack.ads]
    G --> StackBody[generic_stack.adb]
    G --> SortSpec[generic_insertion_sort.ads]
    G --> SortBody[generic_insertion_sort.adb]
    G --> StatsSpec[generic_statistics.ads]
    G --> StatsBody[generic_statistics.adb]
    G --> CountSpec[generic_count_if.ads]
    G --> CountBody[generic_count_if.adb]
    G --> KVSpec[generic_kv_store.ads]
    G --> KVBody[generic_kv_store.adb]

    D --> SwapDemo[swap_demo.adb]
    D --> StackDemo[stack_demo.adb]
    D --> SortDemo[sort_demo.adb]
    D --> StatsDemo[statistics_demo.adb]
    D --> CountDemo[count_if_demo.adb]
    D --> KVDemo[kv_demo.adb]

flowchart LR
    accTitle: Từ hợp đồng tới tái sử dụng an toàn kiểu
    accDescr: Viết hợp đồng, viết generic body, instantiate với kiểu giá trị hàm, rồi dùng an toàn kiểu mà không copy mã
    Contract["Viết hợp đồng"] --> Generic["Viết generic body"]
    Generic --> Instance["Instantiate với kiểu, giá trị, hàm"]
    Instance --> Safe["Dùng an toàn kiểu"]
    Safe --> Reuse["Tái sử dụng không copy"]