CLFS ストリームへのデータ レコードの書き込み

共通ログ・ファイル・システム (CLFS) ストリームには、データ レコードと再開始レコードの 2 種類のレコードがあります。 このトピックでは、ストリームにデータ レコードを書き込む方法について説明します。 再開始レコードを書き込む方法については、 「LFS ストリームへの再開始レコードの書き込み」 を参照してください。

CLFS ストリームにデータ レコードを書き込む前に、 ClfsCreateMarshallingArea を呼び出してマーシャリング領域を作成する必要があります。 その後、(揮発性メモリ内にある) マーシャリング領域にレコードを追加でき、CLFS は定期的にレコードを安定ストレージにフラッシュします。

ストリームへのデータ レコードの書き込みには、いくつかのバリエーションがあります。 たとえば、事前に領域を予約してから複数のレコードを書き込んだり、領域を予約せずにレコードを書き込んだりすることができます。 マーシャリング領域に書き込んだレコードを安定ストレージへすぐにキューイングするか、CLFS がそのポリシーに従ってレコードをキューイングすることもできます。

データ レコードの書き込みのすべてのバリエーションについては、次の手順を実行します。

1. 1 つ以上の CLFS_WRITE_ENTRY 構造体の配列を作成します。 各書き込みエントリ構造体は、レコード データを格納したバッファーを指します。

2. ClfsReserveAndAppendLog または ClfsReserveAndAppendLogAligned を呼び出します。

次のサブセクションの表は、ストリームにレコードを書き込む際のいくつかのバリエーションに対して ClfsReserveAndAppendLog のパラメーターを設定する方法を示しています。

ストリームへの単一データ バッファーの書き込み

マーシャリング領域に書き込むデータ バッファーが 1 つあるとします。 CLFS ポリシーに従ってレコードを安定ストレージにフラッシュすることを希望しており、レコードをレコードチェーンの一部にしたくない場合。 次の表は、 ClfsReserveAndAppendLog を呼び出すときにパラメーターを設定する方法を示しています。

パラメーター名	値
pvMarshalContext	マーシャリング領域へのポインター。
rgWriteEntries	CLFS_WRITE_ENTRY 構造体へのポインター。
cWriteEntries	1
plsnUndoNext	CLFS_LSN_INVALID
plsnPrevious	CLFS_LSN_INVALID
cReserveRecords	0
rgcbReservation	NULL
fFlags	0
plsn	CLFS_LSN 構造体へのポインター。 (これは、書き込まれるレコードの LSN を受け取る出力パラメーターです)。

一連の CLFS ログ レコードの領域の予約

ClfsReserveAndAppendLog を使用すると、実際にレコードを書き込まずに、ログ レコードのセットのマーシャリング領域に領域を予約できます。 次の表は、レコード領域を予約するパラメーターを設定する方法を示しています。

パラメーター名	値
pvMarshalContext	マーシャリング領域へのポインター。
rgWriteEntries	NULL
cWriteEntries	0
plsnUndoNext	CLFS_LSN_INVALID
plsnPrevious	CLFS_LSN_INVALID
cReserveRecords	rgcbReservation が指す配列内の要素の数。
rgcbReservation	LONGLONG 型変数の配列へのポインター。 配列内の各要素は、領域が予約されるレコードのサイズ (バイト単位) です。 これはレコードのデータ部分のサイズであることに注意してください。ヘッダーまたはパディングのサイズを含める必要はありません。
fFlags	0
plsn	NULL

注: マーシャリング領域の領域を予約するもう 1 つの方法は、 ClfsAlignReservedLog の後に ClfsAllocReservedLog を呼び出す方法です。

予約領域へのレコードの書き込み

サイズ (バイト単位) が 100、200、300 の 3 つのレコード用に、既に予約済みの領域があるとします。 マーシャリング領域の予約レコード数は 3 で、600 バイトのレコード データ、レコード ヘッダー、およびアラインメントに必要なパディングを保持するのに十分な予約領域があります。

次に、これらのレコードの 1 つをマーシャリング領域の予約済み領域に書き込む必要があるとします。 使用可能な予約領域が減り、予約レコード数が 3 から 2 に減らされます。 次の表は、 ClfsReserveAndAppendLog を呼び出すときにパラメーターを設定する方法を示しています。

パラメーター名	値
pvMarshalContext	マーシャリング領域へのポインター。
rgWriteEntries	CLFS_WRITE_ENTRY 構造体の配列へのポインター。
cWriteEntries	rgWriteEntries が指す配列内の要素の数。
plsnUndoNext	CLFS_LSN_INVALID または元に戻すチェーン内の前のレコードの LSN。 元に戻すチェーンの詳細については、 「CLFS ログ シーケンス番号」 を参照してください。
plsnPrevious	CLFS_LSN_INVALID または前の LSN チェーン内の前のログ レコードの LSN。 以前の LSN チェーンの詳細については、 「CLFS ログ シーケンス番号」 を参照してください。
cReserveRecords	0
rgcbReservation	NULL
fFlags	CLFS_FLAG_USE_RESERVATION
plsn	CLFS_LSN 構造体へのポインター。 (これは、書き込まれるレコードの LSN を受け取る出力パラメーターです)。

整合済みエントリを含むレコードの書き込み

3 つの書き込みエントリを持つレコードを書き込む場合を考えてみます。 書き込みエントリのサイズは 300 から 500 バイトの間で異なりますが、各書き込みエントリは 512 バイトの境界で開始する必要があります。 次の表は、 ClfsReserveAndAppendLogAligned 関数のパラメーターを設定する方法を示しています。

パラメーター名	値
pvMarshalContext	マーシャリング領域へのポインター。
rgWriteEntries	3 つの CLFS_WRITE_ENTRY 構造体の配列へのポインター。
cWriteEntries	3
cbEntryAlignment	512
plsnUndoNext	CLFS_LSN_INVALID または元に戻すチェーン内の前のレコードの LSN。 元に戻すチェーンの詳細については、 「CLFS ログ シーケンス番号」 を参照してください。
plsnPrevious	CLFS_LSN_INVALID または前の LSN チェーン内の前のログ レコードの LSN。 以前の LSN チェーンの詳細については、 「CLFS ログ シーケンス番号」 を参照してください。
cReserveRecords	0
rgcbReservation	NULL
fFlags	フラッシュと予約の基本設定を指定するフラグの 0 または何らかの組み合わせ。
plsn	CLFS_LSN 構造体へのポインター。 (これは、書き込まれるレコードの LSN を受け取る出力パラメーターです)。

上記の表は、レコード領域の予約と CLFS ストリームへのレコードの書き込みに関する多くのバリエーションのほんの一部を示しています。 他のバリエーションを考える場合は、 ClfsReserveAndAppendLog (または ClfsReserveAndAppendLogAligned) によって実行されるアクションはアトミックであることに注意してください。 たとえば、 ClfsReserveAndAppendLog を 1 回呼び出して、レコードの領域を予約し、レコードをストリームに書き込むことができます。 アクション (予約、書き込み) のペアは、全体として成功するか、全体として失敗します。