# アーキテクチャ構成図

## システム全体構成図

```mermaid
graph TB
    subgraph "Hack Standard Library (HSL)"
        subgraph "Public API Layer"
            Vec[Vec<br/>vec操作]
            Dict[Dict<br/>dict操作]
            Keyset[Keyset<br/>keyset操作]
            C[C<br/>Container共通]
            Str[Str<br/>文字列操作]
            Regex[Regex<br/>正規表現]
            Math[Math<br/>数学演算]
            Random[Random<br/>乱数生成]
            Async[Async<br/>非同期処理]
            IO[IO<br/>入出力]
            File[File<br/>ファイル操作]
            TCP[TCP<br/>TCP通信]
            Unix[Unix<br/>Unixソケット]
            Network[Network<br/>ネットワーク共通]
            OS[OS<br/>システム操作]
            Locale[Locale<br/>ロケール]
            Ref[Ref<br/>参照ラッパー]
        end

        subgraph "Internal Implementation Layer"
            Private[_Private<br/>内部ユーティリティ]
            PrivateStr[_Private\_Str<br/>文字列内部実装]
            PrivateRegex[_Private\_Regex<br/>正規表現内部実装]
            PrivateFile[_Private\_File<br/>ファイル内部実装]
            PrivateIO[_Private\_IO<br/>IO内部実装]
            PrivateTCP[_Private\_TCP<br/>TCP内部実装]
            PrivateNetwork[_Private\_Network<br/>ネットワーク内部実装]
            PrivateOS[_Private\_OS<br/>OS内部実装]
        end
    end

    subgraph "External Dependencies"
        HHVM[HHVM Runtime]
        PCRE[PCRE Library]
        POSIX[POSIX System Calls]
    end

    %% Container operations dependencies
    Vec --> C
    Vec --> Dict
    Vec --> Keyset
    Vec --> Private
    Dict --> C
    Dict --> Private
    Keyset --> C
    Keyset --> Private
    C --> Private

    %% String operations dependencies
    Str --> Private
    Str --> PrivateStr
    Regex --> Private
    Regex --> PrivateRegex
    Regex --> Str

    %% I/O dependencies
    File --> IO
    File --> OS
    File --> PrivateFile
    IO --> PrivateIO
    TCP --> Network
    TCP --> OS
    TCP --> PrivateTCP
    TCP --> PrivateNetwork
    Unix --> OS
    Unix --> Private
    Network --> PrivateNetwork

    %% OS dependencies
    OS --> PrivateOS

    %% Async dependencies
    Async --> C

    %% External dependencies
    PrivateRegex --> PCRE
    PrivateOS --> POSIX
    Private --> HHVM
    PrivateIO --> POSIX
    PrivateNetwork --> POSIX
```

## モジュール依存関係図

```mermaid
graph LR
    subgraph "Container Modules"
        Vec
        Dict
        Keyset
        C
    end

    subgraph "String Modules"
        Str
        Regex
        Locale
    end

    subgraph "I/O Modules"
        IO
        File
    end

    subgraph "Network Modules"
        TCP
        Unix
        Network
    end

    subgraph "System Modules"
        OS
        Async
    end

    subgraph "Utility Modules"
        Math
        Random
        Ref
    end

    Vec --> C
    Vec --> Dict
    Vec --> Keyset
    Dict --> C
    Keyset --> C

    Str --> Locale
    Regex --> Str

    File --> IO
    File --> OS
    IO --> OS

    TCP --> Network
    TCP --> OS
    Unix --> OS
    Network --> OS
```

## 非同期処理フロー図

```mermaid
sequenceDiagram
    participant User as User Code
    participant Sem as Async\Semaphore
    participant Cond as Condition
    participant Func as Processing Function

    User->>Sem: new Semaphore($limit, $func)
    User->>Sem: waitForAsync($input1)

    alt Running count < Limit
        Sem->>Func: Execute $func($input1)
        Func-->>Sem: Result
        Sem-->>User: Awaitable<Result>
    else Running count >= Limit
        Sem->>Cond: Create Condition
        Sem->>Cond: waitForNotificationAsync()
        Note over Cond: Waiting for slot
        Cond-->>Sem: Notification received
        Sem->>Func: Execute $func($input1)
        Func-->>Sem: Result
        Sem-->>User: Awaitable<Result>
    end

    Note over Sem: On completion
    Sem->>Cond: succeed(null) to next waiting
```

## ファイルI/Oフロー図

```mermaid
sequenceDiagram
    participant User as User Code
    participant FileAPI as File\open_*
    participant OSModule as OS\open
    participant Handle as CloseableHandle
    participant System as Operating System

    User->>FileAPI: open_read_only($path)
    FileAPI->>OSModule: open($path, O_RDONLY)
    OSModule->>System: open() syscall
    System-->>OSModule: File Descriptor
    OSModule-->>FileAPI: fd
    FileAPI->>Handle: new CloseableReadHandle(fd, path)
    Handle-->>User: CloseableReadHandle

    User->>Handle: readAllAsync()
    Handle->>System: read() syscall
    System-->>Handle: Data
    Handle-->>User: Awaitable<string>

    User->>Handle: close()
    Handle->>System: close() syscall
    System-->>Handle: Success
```

## コンテナ操作フロー図

```mermaid
flowchart TD
    subgraph "Vec\filter() Flow"
        A[Input: Traversable] --> B{Has predicate?}
        B -->|No| C[Use default boolval]
        B -->|Yes| D[Use provided predicate]
        C --> E[Initialize empty vec]
        D --> E
        E --> F[Foreach element in traversable]
        F --> G{predicate returns true?}
        G -->|Yes| H[Append to result vec]
        G -->|No| I[Skip element]
        H --> J{More elements?}
        I --> J
        J -->|Yes| F
        J -->|No| K[Return result vec]
    end
```

## パッケージ構造図

```mermaid
graph TB
    subgraph "src/"
        Ref.php
        private.php

        subgraph "_Private/"
            _Private_common[Common utilities]
        end

        subgraph "async/"
            Semaphore.php
            Condition.php
            Poll.php
        end

        subgraph "c/"
            c_introspect[introspect.php]
            c_select[select.php]
            c_order[order.php]
        end

        subgraph "vec/"
            vec_select[select.php]
            vec_transform[transform.php]
            vec_order[order.php]
        end

        subgraph "dict/"
            dict_select[select.php]
            dict_transform[transform.php]
            dict_combine[combine.php]
        end

        subgraph "str/"
            str_transform[transform.php]
            str_select[select.php]
        end

        subgraph "io/"
            Handle.php
            ReadHandle.php
            WriteHandle.php
            subgraph "io/_Private/"
                io_priv[Internal handles]
            end
        end

        subgraph "file/"
            file_open[open.php]
            file_Handle[Handle.php]
            subgraph "file/_Private/"
                file_priv[Internal handles]
            end
        end

        subgraph "os/"
            Errno.php
            os_socket[socket.php]
            os_open[open.php]
            subgraph "os/_Private/"
                os_priv[Internal functions]
            end
        end

        subgraph "tcp/"
            tcp_connect[connect.php]
            tcp_Server[Server.php]
        end

        subgraph "unix/"
            unix_connect[connect.php]
            unix_Server[Server.php]
        end
    end
```

## I/Oハンドル継承関係図

```mermaid
classDiagram
    class Handle {
        <<interface>>
    }

    class ReadHandle {
        <<interface>>
        +readAsync() Awaitable~?string~
        +readLineAsync() Awaitable~?string~
    }

    class WriteHandle {
        <<interface>>
        +writeAsync(string) Awaitable~int~
        +writeAllAsync(string) Awaitable~void~
    }

    class SeekableHandle {
        <<interface>>
        +seek(int) void
        +tell() int
    }

    class CloseableHandle {
        <<interface>>
        +close() void
    }

    class FDHandle {
        <<interface>>
    }

    Handle <|-- ReadHandle
    Handle <|-- WriteHandle
    Handle <|-- SeekableHandle
    Handle <|-- CloseableHandle
    Handle <|-- FDHandle

    class CloseableReadHandle {
        <<interface>>
    }

    class CloseableWriteHandle {
        <<interface>>
    }

    class CloseableReadWriteHandle {
        <<interface>>
    }

    ReadHandle <|-- CloseableReadHandle
    CloseableHandle <|-- CloseableReadHandle

    WriteHandle <|-- CloseableWriteHandle
    CloseableHandle <|-- CloseableWriteHandle

    CloseableReadHandle <|-- CloseableReadWriteHandle
    CloseableWriteHandle <|-- CloseableReadWriteHandle

    class FileHandle {
        <<interface>>
    }

    SeekableHandle <|-- FileHandle
    FDHandle <|-- FileHandle
```
