# 機能設計書 114-sysatomics

## 概要

本ドキュメントは、Nim標準ライブラリの`sysatomics`モジュールの機能設計について記載する。このモジュールはアトミック（不可分）操作のためのプリミティブを提供する。

### 本機能の処理概要

sysatomicsモジュールは、マルチスレッド環境での安全なメモリ操作を実現するためのアトミック操作関数群を提供する。これらの操作は、複数のスレッドが同時にメモリにアクセスする際のデータ競合を防止する。

**業務上の目的・背景**：並行プログラミングにおいて、複数のスレッドが同一のメモリ位置に対して読み書きを行う場合、データ競合が発生する可能性がある。アトミック操作は、これらの操作を不可分（他のスレッドから中断されない）なものとして実行し、スレッドセーフなプログラムを構築するための基盤を提供する。

**機能の利用シーン**：
- ロックフリーデータ構造の実装
- 参照カウンタの管理
- フラグやステータスの並行更新
- Compare-And-Swap（CAS）パターンの実装

**主要な処理内容**：
1. アトミックロード/ストア（`atomicLoadN`, `atomicStoreN`）
2. アトミック交換（`atomicExchangeN`）
3. Compare-And-Swap（`atomicCompareExchangeN`, `cas`）
4. アトミック算術演算（`atomicAddFetch`, `atomicSubFetch`等）
5. アトミックインクリメント/デクリメント（`atomicInc`, `atomicDec`）
6. メモリフェンス（`fence`, `atomicThreadFence`）

**関連システム・外部連携**：
- GCCビルトインアトミック関数
- MSVC intrin.h
- プラットフォーム固有のアセンブリ命令

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | プログラム内部で使用するライブラリ機能 |

## 機能種別

システムプログラミング / 並列処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| p | ptr T | Yes | 操作対象のメモリ位置 | AtomType型制約 |
| val | T | Yes | 書き込み/加算する値 | - |
| mem | AtomMemModel | Yes | メモリオーダリングモデル | 有効なモデル値 |
| expected | ptr T | No | CAS操作での期待値 | - |
| desired | T | No | CAS操作での設定値 | - |

### 入力データソース

プログラムコード内の変数ポインタ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| T | AtomType | ロードまたは交換前の値 |
| bool | bool | CAS操作の成功/失敗 |
| int | int | atomicInc/atomicDecの結果 |

### 出力先

指定されたメモリ位置、または戻り値

## 処理フロー

### 処理シーケンス

```
1. アトミック操作の種類を選択
   └─ load / store / exchange / CAS / 算術演算

2. メモリオーダリングモデルを指定
   └─ RELAXED / ACQUIRE / RELEASE / SEQ_CST など

3. コンパイラ/プラットフォーム固有の実装を呼び出し
   └─ GCC: __atomic_* ビルトイン
   └─ MSVC: _Interlocked* 関数
   └─ TCC: インラインアセンブリ

4. 操作結果を返却
   └─ 旧値、新値、または成功フラグ
```

### フローチャート

```mermaid
flowchart TD
    A[アトミック操作呼び出し] --> B{コンパイラ?}
    B -->|GCC/Clang| C[__atomic_* ビルトイン]
    B -->|MSVC| D[_Interlocked* 関数]
    B -->|TCC| E[インラインアセンブリ]
    B -->|その他| F[フォールバック実装]
    C --> G[結果返却]
    D --> G
    E --> G
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-114-01 | AtomType制約 | SomeNumber/pointer/ptr/char/boolのみ使用可 | 常時 |
| BR-114-02 | RELAXED | バリアなし、同期なし | パフォーマンス優先時 |
| BR-114-03 | ACQUIRE | 読み取りバリア、後続の読み書きと同期 | ロック取得時 |
| BR-114-04 | RELEASE | 書き込みバリア、先行の読み書きと同期 | ロック解放時 |
| BR-114-05 | SEQ_CST | 完全な順序保証 | デフォルト/安全優先時 |

### 計算ロジック

- `atomicInc(x, n)` = `atomicAddFetch(x.addr, n, SEQ_CST)`
- `atomicDec(x, n)` = `atomicSubFetch(x.addr, n, SEQ_CST)`

## データベース操作仕様

### 操作別データベース影響一覧

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンパイルエラー | 非AtomType型の使用 | 対応型に変更 |
| - | 未定義動作 | 不正なメモリアクセス | ポインタを検証 |

### リトライ仕様

CAS操作は失敗時に通常ループでリトライする（スピンロック）

## トランザクション仕様

該当なし

## パフォーマンス要件

- アトミック操作はロックなしで実行（ロックフリー）
- CPUキャッシュの同期オーバーヘッドあり
- `cpuRelax`でスピンウェイト時のCPU負荷を軽減

## セキュリティ考慮事項

- メモリ安全性はプログラマの責任
- 不正なポインタ使用は未定義動作

## 備考

- `nimPreviewSlimSystem`定義時は非推奨警告が表示される
- `std/atomics`の使用を推奨

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sysatomics.nim | `lib/std/sysatomics.nim` | AtomType型クラス（22-23行目） |
| 1-2 | sysatomics.nim | `lib/std/sysatomics.nim` | AtomMemModel型（26-48行目） |

**読解のコツ**: AtomTypeはSomeNumber|pointer|ptr|char|boolの型クラス。AtomMemModelはメモリオーダリングの種類を表す。

#### Step 2: GCC/Clang実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sysatomics.nim | `lib/std/sysatomics.nim` | atomicLoadN（50-53行目） |
| 2-2 | sysatomics.nim | `lib/std/sysatomics.nim` | atomicStoreN（59-62行目） |
| 2-3 | sysatomics.nim | `lib/std/sysatomics.nim` | atomicExchangeN（68-72行目） |
| 2-4 | sysatomics.nim | `lib/std/sysatomics.nim` | atomicCompareExchangeN（79-93行目） |
| 2-5 | sysatomics.nim | `lib/std/sysatomics.nim` | Fetch系操作（103-128行目） |
| 2-6 | sysatomics.nim | `lib/std/sysatomics.nim` | atomicThreadFence（143-146行目） |

**主要処理フロー**:
- **50-53行目**: `__atomic_load_n`をインポート
- **79-93行目**: `__atomic_compare_exchange_n`をインポート
- **171行目**: `fence()`はSEQ_CSTモデルでthreadFenceを呼び出し

#### Step 3: MSVC実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sysatomics.nim | `lib/std/sysatomics.nim` | MSVC用定数定義（173-181行目） |
| 3-2 | sysatomics.nim | `lib/std/sysatomics.nim` | _Interlocked関数群（189-211行目） |
| 3-3 | sysatomics.nim | `lib/std/sysatomics.nim` | barrierテンプレート（214-220行目） |
| 3-4 | sysatomics.nim | `lib/std/sysatomics.nim` | MSVC用atomicStoreN/LoadN（222-228行目） |

#### Step 4: 高レベルAPI を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sysatomics.nim | `lib/std/sysatomics.nim` | atomicInc（267-276行目） |
| 4-2 | sysatomics.nim | `lib/std/sysatomics.nim` | atomicDec（278-290行目） |
| 4-3 | sysatomics.nim | `lib/std/sysatomics.nim` | cas汎用関数（292-351行目） |
| 4-4 | sysatomics.nim | `lib/std/sysatomics.nim` | cpuRelax（355-368行目） |

### プログラム呼び出し階層図

```
アプリケーション
    │
    ├─ atomicInc(memLoc, x)
    │      └─ GCC: atomicAddFetch() or MSVC: addAndFetch()
    │
    ├─ atomicDec(memLoc, x)
    │      └─ GCC: atomicSubFetch() or MSVC: addAndFetch(-x)
    │
    ├─ cas(p, oldValue, newValue)
    │      └─ GCC: atomicCompareExchangeN()
    │      └─ MSVC: interlockedCompareExchange*()
    │      └─ TCC: __tcc_cas()
    │
    └─ fence()
           └─ GCC: atomicThreadFence(SEQ_CST)
           └─ MSVC: _ReadWriteBarrier()
```

### データフロー図

```
[入力]               [処理]                    [出力]

ptr T ──────────▶ atomicLoadN ───────▶ T (読み取り値)
                      │
ptr T + val ────▶ atomicStoreN ──────▶ void (書き込み)
                      │
ptr T + val ────▶ atomicExchangeN ───▶ T (旧値)
                      │
ptr T + exp + des ▶ cas ──────────────▶ bool (成功/失敗)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sysatomics.nim | `lib/std/sysatomics.nim` | ソース | アトミック操作API |
| atomics.nim | `lib/pure/concurrency/atomics.nim` | ソース | 推奨される高レベルAPI |
| locks.nim | `lib/pure/locks.nim` | ソース | ロック機構（内部でアトミック使用） |
