# 機能設計書 86-asyncfile

## 概要

本ドキュメントは、Nim標準ライブラリのasyncfileモジュールに関する機能設計書である。ファイルの非同期読み書き機能を提供し、I/Oブロッキングなしでファイル操作を実行可能にする。

### 本機能の処理概要

asyncfileモジュールは、ファイルI/Oを非同期で実行するためのAsyncFile型と関連関数を提供する。asyncdispatchと連携し、ファイル読み書きの間も他の非同期処理を実行可能にする。

**業務上の目的・背景**：大規模ファイルの読み書き、ログファイルの非同期書き込み、ファイルベースのデータ処理において、I/O待ち時間を有効活用することでアプリケーションの応答性を向上させる。

**機能の利用シーン**：ログファイルの非同期書き込み、大規模ファイルのストリーミング読み込み、ファイルアップロード/ダウンロード処理、バックアップ処理など。

**主要な処理内容**：
1. ファイルの非同期オープン（openAsync関数）
2. 非同期読み込み（read, readAll, readLine関数）
3. 非同期書き込み（write, writeBuffer関数）
4. ファイルポジション管理（getFilePos, setFilePos関数）
5. ストリーム連携（writeFromStream, readToStream関数）

**関連システム・外部連携**：asyncdispatch、asyncstreamsと連携。

**権限による制御**：ファイルシステムのアクセス権限に従う。

## 関連画面

該当なし

## 機能種別

非同期ファイルI/O

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| filename | string | Yes | ファイルパス | 有効なファイルパス |
| mode | FileMode | No | ファイルモード（デフォルトfmRead） | fmRead/fmWrite/fmAppend/fmReadWrite |
| size | int | Yes | 読み込みサイズ | 正の整数 |
| data | string | Yes | 書き込みデータ | - |
| pos | int64 | Yes | ファイルポジション | 0以上 |

### 入力データソース

ファイルシステム

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AsyncFile | ref object | 非同期ファイルオブジェクト |
| Future[string] | object | 読み込みデータのFuture |
| Future[int] | object | 読み込みバイト数のFuture |
| Future[void] | object | 書き込み完了のFuture |

### 出力先

ファイルシステム / Future経由での結果返却

## 処理フロー

### 処理シーケンス

```
1. ファイルオープン
   └─ openAsync(filename, mode)
      ├─ [Windows] createFileW + FILE_FLAG_OVERLAPPED
      ├─ [Unix] open + O_NONBLOCK
      └─ register(fd) でディスパッチャに登録

2. 非同期読み込み
   └─ read(size)
      ├─ [Windows] ReadFile + OVERLAPPED → IOCP完了待ち
      ├─ [Unix] addRead + nativesockets.read
      └─ Future[string]で結果返却

3. 非同期書き込み
   └─ write(data)
      ├─ [Windows] WriteFile + OVERLAPPED → IOCP完了待ち
      ├─ [Unix] addWrite + nativesockets.write
      └─ Future[void]で完了通知

4. ファイルクローズ
   └─ close()
      ├─ unregister(fd)
      └─ closeHandle / close
```

### フローチャート

```mermaid
flowchart TD
    A[openAsync] --> B{プラットフォーム}
    B -->|Windows| C[createFileW + OVERLAPPED]
    B -->|Unix| D[open + O_NONBLOCK]
    C --> E[register fd]
    D --> E

    F[read/write] --> G{プラットフォーム}
    G -->|Windows| H[ReadFile/WriteFile + IOCP]
    G -->|Unix| I[addRead/addWrite + syscall]
    H --> J[Future完了]
    I --> J

    K[close] --> L[unregister]
    L --> M[closeHandle/close]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-86-01 | オフセット管理 | 読み書きでファイルオフセットを自動更新 | read/write実行時 |
| BR-86-02 | 非ブロッキング必須 | Unix版はO_NONBLOCKで開く | ファイルオープン時 |
| BR-86-03 | Appendモード | fmAppendはオフセットをファイル末尾に設定 | openAsync時 |
| BR-86-04 | EOFハンドリング | EOF到達時は空文字列を返す | read時 |

### 計算ロジック

**ファイルサイズ取得**（getFileSize関数）:
- Windows: GetFileSize API
- Unix: lseek(SEEK_END) + lseek(SEEK_SET)

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| OSError | ファイルオープン失敗 | ファイルが存在しない等 | パス確認、権限確認 |
| OSError | 読み書きエラー | ディスクフル等 | ディスク空き確認 |
| ERROR_HANDLE_EOF | EOF | ファイル終端 | 正常終了として処理 |

### リトライ仕様

- Unix: EAGAIN時は自動リトライ

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

該当なし

## パフォーマンス要件

- Windows: IOCPによる効率的な非同期I/O
- Unix: selectorsによるイベント駆動
- 大規模ファイルでもメモリ効率の良い逐次処理が可能

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

- ファイルアクセス権限はOSに従う
- パーミッションはS_IRUSR|S_IWUSR|S_IRGRP|S_IWGRP|S_IROTH（0664）

## 備考

- 使用例がモジュールドキュメントに記載

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | asyncfile.nim | `lib/pure/asyncfile.nim` | AsyncFile型（40-43行目） |

**読解のコツ**: fd（AsyncFD）とoffset（int64）を持つシンプルな構造。

#### Step 2: ファイルオープンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | asyncfile.nim | `lib/pure/asyncfile.nim` | getDesiredAccess（46-53行目、Windows版） |
| 2-2 | asyncfile.nim | `lib/pure/asyncfile.nim` | getPosixFlags（64-76行目、Unix版） |
| 2-3 | asyncfile.nim | `lib/pure/asyncfile.nim` | openAsync関数（98-125行目） |

#### Step 3: 読み書き操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | asyncfile.nim | `lib/pure/asyncfile.nim` | read関数（204-297行目） |
| 3-2 | asyncfile.nim | `lib/pure/asyncfile.nim` | write関数（407-486行目） |
| 3-3 | asyncfile.nim | `lib/pure/asyncfile.nim` | readAll関数（329-336行目） |
| 3-4 | asyncfile.nim | `lib/pure/asyncfile.nim` | readLine関数（299-312行目） |

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

```
アプリケーションコード
    │
    ├─ openAsync(filename, mode)
    │      ├─ [Win] createFileW(FILE_FLAG_OVERLAPPED)
    │      ├─ [Unix] open(O_NONBLOCK)
    │      └─ register(fd)
    │
    ├─ read(size)
    │      ├─ newFuture[string]
    │      ├─ [Win] ReadFile + newCustom
    │      ├─ [Unix] addRead + read syscall
    │      └─ Future.complete(data)
    │
    ├─ write(data)
    │      ├─ newFuture[void]
    │      ├─ [Win] WriteFile + newCustom
    │      ├─ [Unix] addWrite + write syscall
    │      └─ Future.complete()
    │
    └─ close()
           ├─ unregister(fd)
           └─ closeHandle/close
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| asyncfile.nim | `lib/pure/asyncfile.nim` | メインソース | 非同期ファイルI/O実装 |
| asyncdispatch.nim | `lib/pure/asyncdispatch.nim` | 依存 | イベントループ |
| asyncstreams.nim | `lib/pure/asyncstreams.nim` | 依存 | FutureStream連携 |
| os.nim | `lib/pure/os.nim` | 依存 | OS関連定義 |
| winlean.nim | `lib/windows/winlean.nim` | 依存 | Windows API |
| posix.nim | `lib/posix/posix.nim` | 依存 | POSIX API |
