AkkEngine のアーキテクチャ

AkkEngine は、高レベルのテーブル API、API サーバー、Cluster 実行環境、VersionLog の下にあるストレージ中核です。バイト列のキーと値を受け取り、シーケンス番号を割り当て、有効化されたストレージ構成要素を協調させます。

実行時の構成

部品	役割
公開 API	put、remove、get、scan、history、getAt、ロールバック、統計、flush、sync、close。
WAL	有効な場合、現在状態の変更を永続化する先行書き込みログ。
MemTable	最近の書き込みと tombstone を保持する、メモリ上の現在状態インデックス。
SST	flush 済みの現在状態データを保持する、ソート済みの永続ファイル。
Blob	設定されたしきい値を超える値の外部ストレージ。
VersionLog	有効な場合、古い値とロールバックのための追記専用履歴ストリーム。
Manifest	ストレージファイルと復旧のための永続メタデータ。

書き込み経路

通常の put(key, value) はエンジン状態を検証し、シーケンス番号を割り当て、設定済みの構成要素を通じて永続状態を記録し、メモリ上の現在状態を更新します。remove(key) も同じ経路を通りますが、値ではなく tombstone を書きます。

WAL が有効な場合、現在状態の変更は設定された同期モードに従って WAL に書かれます。VersionLog が有効な場合は、あとからキーを検査またはロールバックできるように履歴メタデータも記録されます。大きな値は Blob ストレージに逃がされますが、公開されるキーは通常のキー/値エントリとして振る舞います。

読み取り経路

読み取りは現在状態のストレージを確認します。最近の値は MemTable から返ることがあります。flush 済みの古い値は SST ファイルから見つかることがあります。Blob に退避された値は Blob メタデータを解決してから論理値として返されます。

get() は所有権を持つ vector を返します。getInto() は呼び出し側の保存領域を再利用します。getIntoArena() は BufferArena に紐づく view を返すため、局所的なホットパスには向きますが、arena の寿命の外へ出してはいけません。

走査経路

scan(arena, start, end) は半開区間のバイト範囲 [start, end) を走査します。返される view は arena によって裏付けられており、arena が生きていて reset されていない間だけ有効です。

エンジンは生のバイト列を辞書順にソートするため、範囲の挙動は呼び出し側のキーエンコードによって決まります。テキスト接頭辞、ソート可能なビッグエンディアン数値キー、固定幅セグメントがよく使われる設計です。

耐久性の境界

耐久性は API 名だけで決まるものではなく、設定で決まります。

制御	効果
WAL 同期モード	現在状態の変更をどれだけ積極的に同期するか。
forceFlush()	MemTable の状態を SST ストレージ側へ進めます。
forceSync()	WAL や VersionLog などの永続状態を同期します。
runtime.forceFlushOnClose	close 時の flush 挙動。
runtime.forceSyncOnClose	close 時の sync 挙動。

処理を次に進める前に明確な永続化境界が必要な場合は、DURABLE 相当の設定や明示的な sync 呼び出しを使います。

VersionLog の境界

VersionLog はエンジン構成要素です。history(key)、getAt(key, seq)、rollbackKey(key, seq)、rollbackTo(seq) はバイト列のキーとエンジンのシーケンス番号に対して動きます。

rollbackKey() は 1 つのキーだけに影響します。rollbackTo() はエンジン状態を指定シーケンスまで戻すため、運用上の影響範囲が大きい操作です。Blob GC は、古いバージョンが Blob に退避された値を参照している可能性があるため、VersionLog 有効時には意図的に併用不可です。

所有権の境界

AkkEngine はスキーマや型付きエンティティを理解しません。保存するのはバイト列です。呼び出し側が次を所有します。

• キー配置と接頭辞ルール
• 値のエンコード
• スキーマ互換性
• キーをまたぐ不変条件
• 返されたバッファのリクエスト単位またはスレッド単位の所有権

高レベル API はこの層の上に型付き構造体のエンコードとテーブルメタデータを追加しますが、最終的には AkkEngine にバイト列のキーと値を書きます。